API

Search mods, check for updates and publish new versions from scripts or CI. Everything is JSON at https://celestiamods.com/api/v1, described in OpenAPI 3.1.

Download openapi.json Create a token

Permissions and limits

Read (read): every token has it. Reading public data needs no token at all.
Create and edit mods (mods:write)
Upload versions (versions:write)
Each token has its own rate limit, set in Settings. Requests without a token share a limit per address.
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get 429 with Retry-After.
Errors look like {"error": {"code": "…", "message": "…"}}.

“Try it out” below sends real requests from your browser to this site. A token you paste into “Authorize” is kept only in this tab and is gone when you close it.

Endpoints

The interactive explorer needs JavaScript. Every endpoint, with full details in openapi.json:

GET /mods Search and filter public mods.
POST /mods Create a mod page as a draft. Needs “Create and edit mods”.
GET /mods/{slug} One public mod, with its latest version.
PATCH /mods/{slug} Change a mod’s details. Fields you leave out keep their values. Needs “Create and edit mods”.
GET /mods/{slug}/versions A mod’s approved versions, newest first.
GET /mods/{slug}/versions/{version} One approved version and its download link. Use `latest` for the newest.
GET /mods/{slug}/versions/{version}/download Download a version’s file. Use `latest` for the newest.
POST /mods/{slug}/versions Upload a new version as a .zip. Needs “Upload versions”.
GET /mods/{slug}/stats Downloads, follows, rating and the last 30 days of downloads.
GET /updates Newer releases for the mods you have installed.
GET /me The token’s user, permissions and limits.
GET /me/mods Every mod you own or help maintain, in any state.

Publishing from GitHub Actions

Create a token with only “Upload versions”, save it as the repository secret CELESTIA_TOKEN, and add this workflow. Each published release builds the mod, zips it and uploads it as a new version. It goes to review like any upload, unless you’re a trusted author.

name: Publish to Celestia
on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: dotnet build -c Release
      - name: Zip the mod
        run: cd bin/Release/Mods/mymod && zip -r "$GITHUB_WORKSPACE/mymod.zip" .
      - name: Upload the version
        env:
          CELESTIA_TOKEN: ${{ secrets.CELESTIA_TOKEN }}
          # Through the environment, never pasted into the script: release notes contain quotes.
          CHANGELOG: ${{ github.event.release.body }}
        run: |
          curl --fail-with-body \
            -H "Authorization: Bearer $CELESTIA_TOKEN" \
            -F "file=@mymod.zip" \
            -F "game_versions[]=1.20.12" \
            -F "changelog=$CHANGELOG" \
            https://celestiamods.com/api/v1/mods/my-mod/versions