Developer docs
The mod registry is where every CosmicPrisons mod gets approved and listed, and the official API is how mods read Cosmic data without scraping. This page covers the rules and the process. The rest of the docs cover the protocol.
Grace period ends September 17, 2026 at 12:00 PM
Every mod that shows or acts on CosmicPrisons data must be submitted here, whether or not it uses the API. Mods approved under the old process are no longer approved. After the grace period, using a mod that is not listed as approved is punishable under the in-game rules for blacklisted clients and mods.Submitting a mod
Create the app
Sign in to the Developer dashboard with Discord. Give the mod a name, a version, and a description that accurately says what it does.
Choose API access or none
Request the scopes and hook events you need, or state that the mod does not use the API. Either way, every mod must send the presence handshake on join so we can see which mods a player is running.
Provide the source
Link a public repository URL or connect a private repository through the Cosmic GitHub App. We read the source before we build anything.
Test while you wait
Submitting puts the app in review. Client mods can test their API access on your own account and up to three testers you name. Nothing works for other players until the app is approved.
Get approved
We review the description, the requested access, and the source. If we return it, you get a reason to fix and resubmit. Once approved, players can use it live, we build the jar and list it for download, and the mod appears on the registry home page.
Resubmit each version
New versions go through review again before the listing updates. Reviews of updates are much faster than the first one. Players who run the Cosmic updater get the new version at their next restart.
What will not be approved
Provides an unfair gameplay advantage.
Sends input to the server that a vanilla client cannot send, other than what the API expressly grants.
Contains an auto-updater or any self-updating code, other than the unmodified Cosmic updater library nested as a jar-in-jar dependency. The build verifies its hash.
Executes code that does not match its stated purpose.
Scrapes server data from the scoreboard, tab list, chat, inventory, or items. If the API has an endpoint for it, use the endpoint.
Everything else is judged case by case. If we start declining a kind of feature, we will say so in the Discord announcements channel.
Listing rules
Name and description are always public and must accurately represent the mod.
You may hide the download link and your source from other players.
Only mods listed as approved on this site are allowed on the server.
App types
Client mod
A Minecraft client mod. No backend secret.
Backend app
A server-side integration that calls the API with a secret key.
Hybrid
A client mod plus a backend integration.
How API access works
Declare what you need
Choose the scopes and hook events your app requests. Backend apps also get an app key; client mods use their public App ID.
Players approve access
If the mod reads player data, the player approves it in game the first time it connects. Mods with no API access skip this step.
The server enforces it
Every request is tied to the live player session and checked server-side. Your app only gets what it requested, intersected with what was approved and what the player granted.
Players stay in control
Players can revoke a grant at any time. Revoking stops delivery immediately, and suspending an app stops it after the next cache refresh.
Key concepts
App ID
Your app's public identity. It names an app but cannot authorize anything on its own.
App key
A backend secret (csk_live_…) that authenticates server-side API calls. It never ships inside a client mod.
Scope
One permission your app can request, like player.inventory:read. Some are marked sensitive.
Hook event
A push event you can subscribe to. Each is gated by a backing read scope.
Grant
A player's approval of your app's scopes and hooks. Players can revoke it any time.
Session
A live, player-approved connection. Player-scoped reads are authorized through its session id.
Planet
Which server a request targets, like aether or celestial.
Review statuses
Not submitted yet.
Only the developer's linked Minecraft account can use it.
Waiting for the Cosmic team to review.
Live and usable.
Returned with notes. Edit and resubmit.
Temporarily disabled by an admin.
Permanently disabled.
Questions and bugs
Questions about the registry go to a General Support ticket. Bugs in the registry or the API go to a Bug Report ticket.