API endpoints

Overview Client mods Auto-updates API endpoints Hooks Webhooks Actions

Backend apps call these HTTPS endpoints with an approved app key. Client mods use the in-game broker transport, so each endpoint card also shows the matching client-mod payload when that broker equivalent exists.

Request basics

Every route lives under /v1/cosmic-api. Backend apps call it over HTTPS. Client mods do not call HTTP directly. They send and receive JSON over the in-game broker channel after the player approves the mod.

The client mod payload shown under each HTTPS route is the broker-side shape for that same capability. If the card says available: false, that endpoint is currently backend HTTPS only and there is no direct client-mod query for it yet.

Authentication

Backend apps send their approved app key.

A testing key (csk_test_…) works while the app is in testing or review and every response carries mock data with meta.testingData set.

Once approved, a live key may also hold scopes still in review. Responses under those scopes carry mock data with meta.testingData set. So do reads under a scope the session lists in testingScopes.

Mock data keeps the real shape: strings read testing-<field>, numbers 0, booleans false, times 2026-01-01T00:00:00.000Z, and lists keep their first entry. Reads that wait on the game return empty lists and run nothing in game.

Player-scoped reads also need the x-cosmic-api-session-id header for a live broker session the player approved.

Service and admin callers can read public data without a player subject.

Errors

Error bodies carry error and reason.

400 — a bad path or query value, or a request the game rejects, such as item_required.

403 — missing or invalid key, missing scope, or no live approved session for that player.

404 — not found, or runtime_live_unavailable when no live snapshot is published.

409 — the game refused the read for now, such as a locked cell vault page.

429 — rate_limited, counted per session, or per key without one. Reads that wait on the game (library, libraries, private and cell vaults, market history) allow 60 a minute, nearby guards 180, other reads 600.

502 — runtime_action_failed: the game could not finish the read.

504 — the game server didn't complete a scoped read before the API timeout.

Response envelope

Every response is JSON shaped as data plus meta. meta always includes a request id and timestamp; live reads add cache TTL, source, and the required scope that authorized them. Every item, in a read or a hook payload, carries material as described on the inventory read.

{
  "data": { /* endpoint payload */ },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "cacheTtlMs": 5000
  }
}

Mod registry

Public, approved registry listings and the grant requirements players see.

GET/v1/cosmic-api/registry/mods

registry:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Registry discovery is HTTPS and website or developer portal only today. Client mods identify themselves during client_hello."
}

List registry mods

Returns public, approved mod registry listings.

Required scope

Mod registry

registry:read

Read public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.

Request

Approved app key with registry:read.

Optional query: category.

Optional query: server.

Optional query: page.

Optional query: pageSize.

Response

data.mods: public approved mod records visible in the registry.

data.page: current page number.

data.pageSize: requested page size.

data.total: total matching records when available.

meta.requestId and meta.asOf.

Example response

{
  "data": {
    "mods": [
      {
        "id": "app_public_other",
        "name": "Gang Tools",
        "slug": "gang-tools",
        "summary": "Tools for gang coordination.",
        "appType": "client_mod",
        "visibility": "public",
        "status": "approved",
        "requiredScopes": ["gang.profile:read"],
        "optionalScopes": ["gang.members:read"]
      }
    ],
    "page": 1,
    "pageSize": 24,
    "total": 1
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z"
  }
}

GET/v1/cosmic-api/registry/mods/:slug

registry:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Registry discovery is HTTPS and website or developer portal only today. Client mods identify themselves during client_hello."
}

Read registry mod

Returns one public, approved registry mod by slug or id.

Required scope

Mod registry

registry:read

Read public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.

Request

Approved app key with registry:read.

Path param: slug. This can match id, appId, appPublicId, clientId, modId, or slug.

Response

data.mod: the public mod record.

404 when the mod is private, unapproved, or missing.

meta.requestId and meta.asOf.

Example response

{
  "data": {
    "mod": {
      "id": "app_public_other",
      "name": "Gang Tools",
      "slug": "gang-tools",
      "summary": "Tools for gang coordination.",
      "description": "Public registry details for the mod.",
      "appType": "client_mod",
      "visibility": "public",
      "status": "approved",
      "requiredScopes": ["gang.profile:read"],
      "optionalScopes": ["gang.members:read"],
      "requestedHookEvents": []
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z"
  }
}

GET/v1/cosmic-api/registry/mods/:slug/grant-requirements

registry:read

Client mod payload

{
  "type": "client_hello",
  "protocolVersion": 1,
  "clientId": "client_...",
  "modId": "app_public_other",
  "installId": "install_...",
  "modLoader": "fabric",
  "minecraftVersion": "1.21.9",
  "modVersion": "1.0.0",
  "requestedScopes": ["gang.profile:read"],
  "requestedHooks": []
}

Read grant requirements

Returns the scope and hook requirements shown before a player grants access.

Required scope

Mod registry

registry:read

Read public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.

Request

Approved app key with registry:read.

Path param: slug. This can match id, appId, appPublicId, clientId, modId, or slug.

Response

data.appId and data.name.

data.requiredScopes and data.optionalScopes.

data.dangerousScopes for sensitive access warnings.

data.grantCopy with player-facing title/body text.

404 when the mod is private, unapproved, or missing.

Example response

{
  "data": {
    "appId": "app_public_other",
    "name": "Gang Tools",
    "requiredScopes": ["gang.profile:read"],
    "optionalScopes": ["gang.members:read"],
    "dangerousScopes": [],
    "grantCopy": [
      {
        "scope": "gang.profile:read",
        "title": "Read your gang profile",
        "body": "Allows this app to read the public-safe profile for your current gang."
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z"
  }
}

Servers & status

What the API serves, the public server list, and per-server online state.

Required scope

None. Any valid key can call it.

Request

No parameters.

Fields

Under data.

apiVersionstring

The API contract date.

authModestring

How this request signed in: app_key, service or admin.

accessModesstring[]

subject_bound, service_key_scoped and admin.

serverScopesstring[]

The planets: aether and celestial.

featuresRecord<string, boolean>

true for each feature served, including playerWallet, playerProgression, playerState, cellVaults, playerLibraries, marketHistory and midas.

Response

A testing key gets mock values like every other response, so its flags read false.

Example response

{
  "data": {
    "apiVersion": "2026-05-28",
    "authMode": "app_key",
    "accessModes": ["subject_bound", "service_key_scoped", "admin"],
    "serverScopes": ["aether", "celestial"],
    "features": {
      "events": true,
      "hooks": true,
      "playerWallet": true,
      "playerProgression": true,
      "playerState": true,
      "cellVaults": true,
      "playerLibraries": true,
      "marketHistory": true,
      "midas": true
      /* one flag per feature */
    }
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z" }
}

GET/v1/cosmic-api/runtime/servers

server.status:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Client mods do not query public server status through the broker today. Approved sessions receive their serverScope in the resolve payload."
}

List servers

Returns the public server list.

Required scope

Server status

server.status:read

See the public server list, whether each server is online, its server role, and when that status was last updated. This does not include player counts, warp counts, outpost state, player locations, or infrastructure details.

Request

Approved app key with server.status:read.

Response

data.servers[].scope: server scope such as aether or celestial.

data.servers[].label: public display name.

data.servers[].state: online or offline.

data.servers[].role: discovered server role.

data.servers[].updatedAt: status update time.

Does not return player counts, warp counts, outpost state, hostnames, IPs, ports, tunnel ids, machine ids, Redis status, database status, or agent names.

Example response

{
  "data": {
    "servers": [
      {
        "scope": "aether",
        "label": "Aether",
        "state": "online",
        "role": "live",
        "updatedAt": "2026-06-02T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "cacheTtlMs": 5000
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/status

server.status:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Client mods do not query public server status through the broker today. Approved sessions receive their serverScope in the resolve payload."
}

Read server status

Returns public status for one server scope.

Required scope

Server status

server.status:read

Request

Approved app key with server.status:read.

Path param: serverScope. Current valid values are aether and celestial.

Response

data.server.scope: server scope.

data.server.label: public display name.

data.server.state: online or offline.

data.server.role: discovered server role.

data.server.updatedAt: status update time.

404 when the server scope is valid but not found.

Example response

{
  "data": {
    "server": {
      "scope": "aether",
      "label": "Aether",
      "state": "online",
      "role": "live",
      "updatedAt": "2026-06-02T00:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 5000
  }
}

Events & world state

The live event schedule, weather, mine vaults, Prison Break, Ground Zero and Midas state.

GET/v1/cosmic-api/runtime/servers/:serverScope/events

events:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.event.schedule.changed",
  "payload": {
    "id": "evt_...",
    "type": "server.event.schedule.changed",
    "eventType": "server.event.schedule.changed",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "events": [
        {
          "id": "event_meteor",
          "name": "Meteor",
          "nextStartAtMillis": 1780362000000
        }
      ]
    }
  }
}

List events

Returns the current Redis runtime event list for a server.

Required scope

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Path param: serverScope. Current valid values are aether and celestial.

Response

data.events: pass-through event records from the runtime event snapshot.

meta.source: redis_runtime.

meta.snapshotName: events.

meta.snapshotStatus: snapshot availability.

meta.snapshotUpdatedAt: runtime snapshot update time.

The API does not normalize event record fields today.

Example response

{
  "data": {
    "events": [
      {
        "id": "event_meteor",
        "name": "Meteor",
        "nextStartAtMillis": 1780362000000
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "events",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 5000
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/events/next

events:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.event.schedule.changed",
  "payload": {
    "id": "evt_...",
    "type": "server.event.schedule.changed",
    "eventType": "server.event.schedule.changed",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "events": [
        {
          "id": "event_meteor",
          "name": "Meteor",
          "nextStartAtMillis": 1780362000000
        }
      ]
    }
  }
}

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Path param: serverScope. Current valid values are aether and celestial.

Response

data.nextEvent: the current next event value from the runtime snapshot.

data.events: the same pass-through event list returned by /events.

meta.source: redis_runtime.

meta.snapshotName: events.

Today nextEvent is the last event entry from the Redis runtime list unless the writer publishes a different ordered list.

Example response

{
  "data": {
    "nextEvent": {
      "id": "event_meteor",
      "name": "Meteor",
      "nextStartAtMillis": 1780362000000
    },
    "events": [
      {
        "id": "event_meteor",
        "name": "Meteor",
        "nextStartAtMillis": 1780362000000
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "events",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 5000
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/events/:eventId

events:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.event.schedule.changed",
  "payload": {
    "id": "evt_...",
    "type": "server.event.schedule.changed",
    "eventType": "server.event.schedule.changed",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "events": [
        {
          "id": "event_meteor",
          "name": "Meteor",
          "nextStartAtMillis": 1780362000000
        }
      ]
    }
  }
}

Read one event

Returns one event from the Redis runtime event list.

Required scope

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Path param: serverScope. Current valid values are aether and celestial.

Path param: eventId. Lookup checks id, eventId, eventType, type, slug, and name case-insensitively.

Response

data.event: the matching pass-through event record.

404 with error event_not_found when no runtime event matches.

meta.source: redis_runtime.

meta.snapshotName: events.

meta.snapshotUpdatedAt: runtime snapshot update time.

Example response

{
  "data": {
    "event": {
      "id": "event_meteor",
      "name": "Meteor",
      "nextStartAtMillis": 1780362000000
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "events",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 5000
  }
}

Required scope

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Path param: serverScope. Current valid values are aether and celestial.

Response

data.world.weather: active event, surge, the last event, and the next event time. Null when the weather system is off.

data.world.mineVaults.raids[]: mine, tier, trigger, HP, participant count, idle time left rounded to 5 s, and the top three damagers.

data.world.mineVaults.naturalTimers[]: time until each natural mine vault.

data.world.prisonBreak: phase, seconds left, round, mode, tier and roster size. Null when no match exists.

data.world.groundZero: reset countdown and whether a reset is running.

data.world.midas: the same section as /world/midas.

Does not return pity chances, flashpoint coordinates or success rates, surge timing, vault anchor coordinates, loot tables, tier odds, lucky-effect or boost weights.

Sub-routes /world/weather, /world/vaults, /world/prisonbreak and /world/groundzero return one section each under the same scope.

meta.snapshotName: world. meta.cacheTtlMs: 2500.

404 with runtime_live_unavailable when no Redis world snapshot is available.

Example response

{
  "data": {
    "world": {
      "weather": {
        "active": { "id": "acid_rain", "displayName": "Acid Rain", "subtitle": "Ores drop double", "areaLabel": "All mines", "color": "#55ff55", "startedAtMillis": 1756800000000, "endsAtMillis": 1756801800000, "remainingMillis": 900000 },
        "surge": null,
        "last": { "id": "money_bubble", "displayName": "Money Bubble", "endedAtMillis": 1756790000000 },
        "nextEventAtMillis": 1756805400000
      },
      "mineVaults": {
        "raids": [
          { "mine": "diamond", "tier": 3, "trigger": "natural", "maxHp": 500000, "remainingHp": 120000, "hpPercent": 24, "participantCount": 12, "startedAtMillis": 1756800000000, "idleRemainingMillis": 240000,
            "topDamagers": [ { "playerId": "00000000-0000-0000-0000-000000000000", "playerName": "Steve", "damage": 80000 } ] }
        ],
        "naturalTimers": [ { "mine": "emerald", "remainingMillis": 1800000 } ]
      },
      "prisonBreak": { "phase": "GAME", "isGame": true, "phaseSecondsLeft": 412, "round": 2, "matchRemainingMillis": 900000, "mode": "solo", "tier": 2, "rosterSize": 18 },
      "groundZero": { "resetRemainingMillis": 5400000, "resetting": false }
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-09-03T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "world",
    "serverScope": "aether",
    "cacheTtlMs": 2500
  }
}

Required scope

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.worldState.vault: mine, contribution and rank in the active raid the player has damaged, or null. Rank is 0 outside the top 25.

data.worldState.prisonBreak: points and active lucky effects with ticks left, only while the player is in the match roster.

Rankings beyond the player's own rank are not returned; use the leaderboards for standings.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "worldState": {
      "vault": { "mine": "diamond", "contribution": 80000, "rank": 1 },
      "prisonBreak": { "points": 42, "luckyEffects": [ { "id": "double_points", "title": "Double Points", "polarity": "good", "remainingTicks": 1200 } ] }
    },
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Events and world state

events:read

Read the public events schedule, plus weather, mine vault raids, Prison Break, Ground Zero reset and Midas state. Also reads your own mine vault contribution and Prison Break points.

Request

Approved app key with events:read.

Path param: serverScope. Current valid values are aether and celestial.

Fields

Under data.midas.

enabledboolean

Whether the Midas vault is on.

bankers[]object[]

One per blood banker: finger, alive, respawnInSeconds (0 while alive), respawnAt (null while alive) and location as { x, y, z }.

bossRoomobject | null

phase (locked, open, ongoing or ending), openedBy as { uuid, name }, openedAt, secondsInPhase, secondsRemaining (null outside open and ending), playersInside and maxPlayers.

Response

Subscribe to server.midas.banker.changed and server.midas.boss_room.changed for changes.

meta.snapshotName: world. meta.cacheTtlMs: 2500.

404 with runtime_live_unavailable when no Redis world snapshot is available.

Testing mode: the same shape with mock values.

Example response

{
  "data": {
    "midas": {
      "enabled": true,
      "bankers": [ { "finger": "index", "alive": false, "respawnInSeconds": 240, "respawnAt": "2026-10-11T00:04:00.000Z", "location": { "x": 210, "y": 70, "z": -88 } } ],
      "bossRoom": { "phase": "open", "openedBy": { "uuid": "00000000-0000-0000-0000-000000000001", "name": "Steve" }, "openedAt": "2026-10-11T00:00:00.000Z",
        "secondsInPhase": 35, "secondsRemaining": 85, "playersInside": 4, "maxPlayers": 10 }
    }
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "source": "redis_runtime", "snapshotName": "world", "serverScope": "aether", "cacheTtlMs": 2500 }
}

Player data

Reads for the approved player, plus the leaderboards and catalogs they draw from.

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/inventory

player.inventory:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Raw inventory reads are not sent directly to the client mod today. Backend apps use HTTPS with the approved live session."
}

Read player inventory

Returns sanitized item data for the approved player's live inventory.

Required scope

Your inventory

player.inventory:readSensitive

Read the item type, amount, Cosmic item id, and approved custom data for items in your inventory.

Request

Approved app key with player.inventory:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Response

data.playerId: the approved player id.

data.inventory[]: non-empty inventory items only.

data.inventory[].slot: 0-35 for main inventory/hotbar, 36 boots, 37 leggings, 38 chestplate, 39 helmet, 40 offhand.

data.inventory[].material: Bukkit material enum name, e.g. DIAMOND_PICKAXE. The Minecraft id is minecraft: plus the name in lowercase.

data.inventory[].amount: stack amount.

data.inventory[].cosmicItemId: Cosmic item definition id when the stack is a registered Cosmic item, otherwise null.

data.inventory[].customData: JSON-safe Cosmic custom data from the item.

customData does not include custom_item_id, UUID values, note ids, anti-dupe tracking fields, raw byte arrays, raw NBT, or serialized item blobs.

403 when the app key has no live subject session, the session is for a different player, or the session lacks player.inventory:read.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "inventory": [
      {
        "slot": 0,
        "material": "DIAMOND_PICKAXE",
        "amount": 1,
        "cosmicItemId": "cosmic_pickaxe",
        "customData": {
          "item_level": 42,
          "enchants": "momentum:3,efficiency:5",
          "energy": 12500
        }
      }
    ],
    "serverTime": "2026-06-04T00:00:00.000Z"
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "players",
    "snapshotStatus": "available",
    "serverScope": "aether",
    "accessMode": "app_key",
    "relationship": "player_self",
    "requiredScope": "player.inventory:read",
    "sessionId": "sess_..."
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/inventory/:slot

player.inventory:read

Client mod payload

{
  "available": false,
  "transport": "cosmicapi:main",
  "reason": "Raw inventory reads are not sent directly to the client mod today. Backend apps use HTTPS with the approved live session."
}

Read one inventory slot

Returns sanitized item data for one approved player inventory slot.

Required scope

Your inventory

player.inventory:readSensitive

Read the item type, amount, Cosmic item id, and approved custom data for items in your inventory.

Request

Approved app key with player.inventory:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Path param: slot. Valid values are 0-40.

Response

data.slot: requested slot number.

data.item: the sanitized item object for that slot, or null when the slot is empty.

Item fields match the player inventory endpoint.

403 when the app key has no live subject session, the session is for a different player, or the session lacks player.inventory:read.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "serverScope": "aether",
    "slot": 0,
    "item": {
      "slot": 0,
      "material": "DIAMOND_PICKAXE",
      "amount": 1,
      "cosmicItemId": "cosmic_pickaxe",
      "customData": {
        "item_level": 42,
        "enchants": "momentum:3,efficiency:5",
        "energy": 12500
      }
    },
    "serverTime": "2026-06-04T00:00:00.000Z"
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "players",
    "snapshotStatus": "available",
    "serverScope": "aether",
    "cacheTtlMs": 1000,
    "accessMode": "app_key",
    "relationship": "player_self",
    "requiredScope": "player.inventory:read",
    "sessionId": "sess_..."
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/private-vaults/:vaultNumber

player.private_vaults:read

Client mod payload

{
  "type": "action",
  "sessionId": "sess_...",
  "actionType": "private_vault.read",
  "requestId": "req_...",
  "payload": { "vaultNumber": 1 }
}

Read one private vault

Returns sanitized item data for one approved player private vault page.

Required scope

Your private vaults

player.private_vaults:readSensitive

Read the item type, amount, Cosmic item id, and approved custom data for one private vault page at a time.

Request

Approved app key with player.private_vaults:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Path param: vaultNumber. This reads one vault page only.

Response

data.vaultNumber: requested private vault number.

data.items[]: non-empty items from that vault page only.

data.items[].slot: slot within that vault page.

Item fields match the player inventory endpoint.

There is no endpoint to read every private vault at once.

The response does not include raw vault base64, raw NBT, UUID values, note ids, or anti-dupe tracking fields.

403 when the app key has no live subject session, the session is for a different player, or the session lacks player.private_vaults:read.

504 when the game server does not complete the scoped vault read before the API timeout.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "serverScope": "aether",
    "vaultNumber": 1,
    "asOf": "2026-06-04T00:00:00.000Z",
    "items": [
      {
        "slot": 12,
        "material": "ENCHANTED_BOOK",
        "amount": 1,
        "cosmicItemId": "mystery_book",
        "customData": {
          "tier": "elite",
          "success": 72,
          "destroy": 18
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "serverScope": "aether",
    "actionId": "act_...",
    "accessMode": "app_key",
    "relationship": "player_self",
    "requiredScope": "player.private_vaults:read",
    "sessionId": "sess_..."
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/private-vaults/:vaultNumber/:slot

player.private_vaults:read

Client mod payload

{
  "type": "action",
  "sessionId": "sess_...",
  "actionType": "private_vault.read",
  "requestId": "req_...",
  "payload": { "vaultNumber": 1, "slot": 0 }
}

Read one private vault slot

Returns sanitized item data for one slot in one approved player private vault page.

Required scope

Your private vaults

player.private_vaults:readSensitive

Read the item type, amount, Cosmic item id, and approved custom data for one private vault page at a time.

Request

Approved app key with player.private_vaults:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Path param: vaultNumber. This reads one vault page only.

Path param: slot. Valid values are 0-53.

Response

data.vaultNumber and data.slot: requested vault page and slot.

data.item: the sanitized item object for that slot, or null when the slot is empty.

Item fields match the player inventory endpoint.

The response does not include raw vault base64, raw NBT, UUID values, note ids, or anti-dupe tracking fields.

403 when the app key has no live subject session, the session is for a different player, or the session lacks player.private_vaults:read.

504 when the game server does not complete the scoped vault read before the API timeout.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "serverScope": "aether",
    "vaultNumber": 1,
    "asOf": "2026-06-04T00:00:00.000Z",
    "slot": 12,
    "item": {
      "slot": 12,
      "material": "ENCHANTED_BOOK",
      "amount": 1,
      "cosmicItemId": "mystery_book",
      "customData": {
        "tier": "elite",
        "success": 72,
        "destroy": 18
      }
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "serverScope": "aether",
    "actionId": "act_...",
    "accessMode": "app_key",
    "relationship": "player_self",
    "requiredScope": "player.private_vaults:read",
    "sessionId": "sess_..."
  }
}

Required scope

Leaderboards

leaderboards:read

Read public leaderboard standings for every /top board.

Request

Approved app key with leaderboards:read.

Path param: serverScope. Current valid values are aether and celestial.

Path param: category. One of balance, blocks, gift, bandit, level, gang, coinflip_wins, prison_break, clue_scroll, rep, top_credit, jackpot_wins.

Optional query: page and pageSize.

Response

data.entries[]: rank, playerId, playerName and value, plus the board's own value key: wins (coinflip_wins, jackpot_wins), score (prison_break), scrolls (clue_scroll), reputation (rep), credits (top_credit).

The original boards keep their row shapes: balance, blocksMined, giftCred, banditsKilled; level rows carry level, prestige and xp; gang rows carry gangId, title and points.

playerName is present when the server has the name cached, otherwise omitted.

Ranks are counted after banned players and staff are removed, so they can differ from the in-game board. The gang board is not filtered.

A board that has not loaded since the last restart answers empty until its next refresh, same as the /top menu.

meta.snapshotName: leaderboards. meta.cacheTtlMs: 15000.

Example response

{
  "data": {
    "category": "prison_break",
    "page": 1,
    "pageSize": 25,
    "totalEntries": 25,
    "entries": [
      { "rank": 1, "playerId": "00000000-0000-0000-0000-000000000000", "playerName": "Steve", "value": 1280, "score": 1280 }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "source": "redis_runtime", "snapshotName": "leaderboards", "serverScope": "aether", "cacheTtlMs": 15000 }
}

Required scope

Your satchels

player.satchels:read

Read your satchel fill amounts and the satchels stored in your backpacks.

Request

Approved app key with player.satchels:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.satchels[]: satchels held directly in the inventory. Rows carry slot, type (Cosmic item id), material, name, amount, level, energy, maxEnergy, ore, refined, tier (ore variant: regular, deepslate or block; null for tiered drop satchels), count and capacity.

data.satchelBackpacks[]: up to 6 backpacks with slot, bagId, level, usedSlots, capacity, energy, maxEnergy and storedSatchels[] (same row shape as data.satchels, with slot as the place inside the backpack).

Subscribe to player.satchel.changed and player.satchel_backpack.changed; both carry full rows.

Does not return other players' backpacks, level-up odds or wormhole session internals.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "satchels": [
      { "slot": 3, "type": "diamond_ore_satchel", "material": "DIAMOND_ORE", "name": "Diamond Ore Satchel", "amount": 1, "level": 2, "energy": 80, "maxEnergy": 200, "ore": "DIAMOND", "refined": false, "tier": "regular", "count": 1240, "capacity": 5000 }
    ],
    "satchelBackpacks": [
      { "slot": 8, "bagId": "00000000-0000-0000-0000-000000000001", "level": 2, "usedSlots": 4, "capacity": 10, "energy": 120, "maxEnergy": 300,
        "storedSatchels": [ { "slot": 0, "type": "deepslate_iron_ore_satchel", "material": "DEEPSLATE_IRON_ORE", "name": "Deepslate Iron Ore Satchel", "amount": 1, "level": 1, "ore": "IRON", "refined": false, "tier": "deepslate", "count": 300, "capacity": 1000 } ] }
    ],
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your emblems

player.emblems:read

See your equipped emblem, emblem progress, login streak and recent unlocks.

Request

Approved app key with player.emblems:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.emblems.equipped: id, displayName, symbol and tier, or null.

data.emblems.buffsEnabled and loginStreak.

data.emblems.progress[]: up to 32 rows for emblems the player has progress on, in catalog order, with value, requirement and nextTier.

data.emblems.unlocks[]: the 10 most recent tier unlocks.

Service and admin callers without a player session get only equipped.id and equipped.tier, which every player can already see in chat and tab.

Does not return composed multipliers or perk values beyond the catalog perk line.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "emblems": {
      "equipped": { "id": "miner", "displayName": "Miner", "symbol": "⛏", "tier": 3 },
      "buffsEnabled": true,
      "loginStreak": 4,
      "progress": [ { "id": "miner", "value": 120000, "requirement": 250000, "nextTier": 4 } ],
      "unlocks": [ { "id": "miner", "tier": 3, "unlockedAtMillis": 1756700000000 } ]
    },
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your emblems

player.emblems:read

See your equipped emblem, emblem progress, login streak and recent unlocks.

Request

Approved app key with player.emblems:read.

Path param: serverScope. Current valid values are aether and celestial.

App-key callers must include x-cosmic-api-session-id for a live subject broker session.

Service and admin callers can read without a player subject.

Response

data.emblems[]: id, displayName, symbol, category, perkType and tiers[] with requirement and perkLine.

meta.snapshotName: emblems. meta.cacheTtlMs: 60000.

Example response

{
  "data": {
    "emblems": [
      { "id": "miner", "displayName": "Miner", "symbol": "⛏", "category": "mining", "perkType": "xp",
        "tiers": [ { "tier": 1, "requirement": 10000, "perkLine": "+2% mining XP" } ] }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "source": "redis_runtime", "snapshotName": "emblems", "serverScope": "aether", "cacheTtlMs": 60000 }
}

Required scope

Your top credits

player.top_credits:read

Read your Top Credit balances, ledger and the next payout checkpoint.

Request

Approved app key with player.top_credits:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.topCredits.spendable and lifetime for the current server.

data.topCredits.nextCheckpoint: key, label, atMillis, countdownMillis and mapEnd.

data.topCredits.ledger[]: the 25 newest entries with type, map, checkpointKey, board, rank, amount, detail and timestampMillis.

Does not return reputation, receipts or admin adjustments.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "topCredits": {
      "spendable": 12,
      "lifetime": 40,
      "nextCheckpoint": { "key": "day_7", "label": "Day 7", "atMillis": 1756900000000, "countdownMillis": 86400000, "mapEnd": false },
      "ledger": [ { "type": "payout", "map": "aether-12", "checkpointKey": "day_3", "board": "blocks", "rank": 2, "amount": 4, "detail": "#2 Blocks Mined", "timestampMillis": 1756700000000 } ]
    },
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your top credits

player.top_credits:read

Read your Top Credit balances, ledger and the next payout checkpoint.

Request

Approved app key with player.top_credits:read.

Path param: serverScope. Current valid values are aether and celestial.

App-key callers must include x-cosmic-api-session-id for a live subject broker session.

Service and admin callers can read without a player subject.

Response

data.boards[]: id, name, gang, creditRanks and payouts[] with checkpointKey and byRank rows of rank and amount. Boards that pay no credits have an empty payouts list.

meta.snapshotName: top-credits. meta.cacheTtlMs: 60000.

Example response

{
  "data": {
    "boards": [
      { "id": "blocks", "name": "Blocks Mined", "gang": false, "creditRanks": 10,
        "payouts": [ { "checkpointKey": "day_3", "byRank": [ { "rank": 1, "amount": 6 }, { "rank": 2, "amount": 4 } ] } ] }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "source": "redis_runtime", "snapshotName": "top-credits", "serverScope": "aether", "cacheTtlMs": 60000 }
}

Required scope

Your custom sets

player.custom_sets:read

See the Death and Greed set pieces you wear, and your payday and death mark timers.

Request

Approved app key with player.custom_sets:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.customSets.sets[]: type, fullSet and pieces[] with role, primaryRoll, secondaryRoll, mystery and tier. Mystery pieces omit rolls.

data.customSets.payday and deathMark: active, remainingMillis, and the attacker name for a death mark.

Does not return roll ranges, hidden rolls on mystery pieces, or max-roll thresholds.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "customSets": {
      "sets": [
        { "type": "greed", "fullSet": true,
          "pieces": [ { "role": "helmet", "primaryRoll": 82, "secondaryRoll": 40, "mystery": false, "tier": 2 }, { "role": "chestplate", "mystery": true, "tier": 2 } ] }
      ],
      "payday": { "active": true, "remainingMillis": 42000 },
      "deathMark": { "active": false, "remainingMillis": 0, "attackerName": null }
    },
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your Ground Zero

player.ground_zero:read

Read your Ground Zero points, weekly upgrades and charm cooldowns while you are in the world.

Request

Approved app key with player.ground_zero:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Response

data.groundZero: resetRemainingMillis, points, satchelPoints, upgrades (weekId, weekRemainingMillis, owned ids) and charmCooldowns[].

Null while the player is outside Ground Zero. Use /world/groundzero for the reset countdown from anywhere.

Does not return special block positions, mule or merchant positions, other players' positions or points, boost weights, or charm prices.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "groundZero": {
      "resetRemainingMillis": 5400000,
      "points": 1830,
      "satchelPoints": 220,
      "upgrades": { "weekId": "2026-36", "weekRemainingMillis": 172800000, "owned": [ "haste_1", "extra_life" ] },
      "charmCooldowns": [ { "type": "luck", "remainingMillis": 600000 } ]
    },
    "serverTime": "2026-09-03T00:00:00.000Z"
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether" }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/library

player.library:read

Client mod payload

{
  "type": "action",
  "sessionId": "sess_...",
  "actionType": "library.read",
  "requestId": "req_...",
  "payload": { "ownerId": "00000000-0000-0000-0000-000000000000", "category": "books" }
}

Read a library

Returns the session player's own library, or the categories another player shares with them.

Required scope

Your library

player.library:readSensitive

Read your library, and libraries other players share with you in game.

Request

Approved app key with player.library:read.

Header: x-cosmic-api-session-id for the live broker session of the viewer. The viewer is always the session player and is never read from the request.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. The library owner. When it matches the session player you get your own library; otherwise you get what that owner shares with you.

Response

data.ownerId, ownerName and viewerIsOwner.

data.categories[]: only the categories the viewer can view, with the viewer's canView, canDeposit, canWithdraw and canViewLogs flags, entryCount and up to 64 entries of itemKey, material, displayName and count. Up to 7 categories.

data.unlockedMiscSlots: owner reads only.

A grantee gets exactly the categories /library <owner> would draw for them in game. Player grants and gang grants both count. Staff library permissions give nothing over the API.

Does not return unlock prices, who deposited an item, log rows, or the grant list.

502 with runtime_action_failed and reason library_forbidden when the owner shares nothing with the viewer.

504 when the game server does not complete the library read before the API timeout.

Client mods use the library.read broker action instead. Without a category it returns the hub with entryCount and no entries; with one it returns that category's entries.

Example response

{
  "data": {
    "ownerId": "00000000-0000-0000-0000-000000000000",
    "ownerName": "Steve",
    "viewerIsOwner": false,
    "categories": [
      { "id": "ores", "displayName": "Ores", "canView": true, "canDeposit": true, "canWithdraw": false, "canViewLogs": false, "entryCount": 2,
        "entries": [ { "itemKey": "ore:diamond", "displayName": "Diamond Ore", "material": "DIAMOND_ORE", "count": 4200 } ] }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether", "actionId": "act_...", "relationship": "library_grantee" }
}

Required scope

Your library

player.library:readSensitive

Read your library, and libraries other players share with you in game.

Request

Approved app key with player.library:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Fields

Under data.

viewerIdstring

The session player.

libraries[]object[]

One per library the viewer can open, shaped like the library read: ownerId, ownerName, viewerIsOwner and categories[] with their entries. The viewer's own library adds unlockedMiscSlots.

Response

Owners who share nothing with the viewer are left out.

Client mods use the library.list broker action, which returns the same list without entries.

502 with runtime_action_failed and reason library_unavailable when the library is off on that server.

504 when the game server does not complete the read before the API timeout.

Testing mode: an empty libraries list. No game read runs.

Example response

{
  "data": {
    "viewerId": "00000000-0000-0000-0000-000000000000",
    "libraries": [
      { "ownerId": "00000000-0000-0000-0000-000000000001", "ownerName": "Steve", "viewerIsOwner": false,
        "categories": [ { "id": "books", "displayName": "Books", "canView": true, "canDeposit": true, "canWithdraw": false, "canViewLogs": false, "entryCount": 12,
          "entries": [ { "itemKey": "book|fortune|SIMPLE|3|...", "displayName": "Fortune III", "material": "ENCHANTED_BOOK", "count": 40 } ] } ] }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether", "actionId": "act_..." }
}

Required scope

Your balances

player.wallet:read

Read your in-game balances.

Request

Approved app key with player.wallet:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Fields

Under data.wallet.

balancenumber

Money.

balanceRevisionnumber

Goes up with every balance write.

seasonalCosmicCoinsnumber

Seasonal Cosmic Coins.

itemFlipCreditsnumber

Item Flip credits.

giftCrednumber

Gift Cred.

bloodDiamondsnumber

Midas Blood Diamonds.

bloodDiamondsPeriodEndsAtISO 8601

When the current Blood Diamond period ends.

Response

Refreshed every 5 seconds. Subscribe to player.wallet.changed for changes as they happen.

Testing mode: the same shape with mock values.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "wallet": { "balance": 1250000.5, "balanceRevision": 812, "seasonalCosmicCoins": 340, "itemFlipCredits": 12, "giftCred": 5, "bloodDiamonds": 18, "bloodDiamondsPeriodEndsAt": "2026-10-12T00:00:00.000Z" }
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your progression

player.progression:read

Read your level, experience, prestige and skill tree.

Request

Approved app key with player.progression:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Fields

Under data.progression.

levelnumber

Mining level.

experiencenumber

Experience toward the next level.

experienceToNextLevelnumber

Experience still needed. 0 at the prestige's top level.

levelCapnumber

The highest level reachable today: the map's level cap, or the prestige's top level.

prestigenumber

Prestige.

prestigePerks[]{ id, unlocked }[]

level_101 to level_104 and prestige_4_level_100_meteor.

skillTreeobject

availablePoints, totalPoints, spentPoints and freeResetsRemaining (numbers), and perks[] of tree, key, level and maxLevel for each perk with a level.

Response

Refreshed every 5 seconds. Subscribe to player.progression.changed for changes as they happen.

Testing mode: the same shape with mock values.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "progression": {
      "level": 64, "experience": 18250.5, "experienceToNextLevel": 40000, "levelCap": 100, "prestige": 2,
      "prestigePerks": [ { "id": "level_101", "unlocked": true } ],
      "skillTree": { "availablePoints": 1, "totalPoints": 12, "spentPoints": 11, "freeResetsRemaining": 1,
        "perks": [ { "tree": "prospector", "key": "ore_duplication", "level": 3, "maxLevel": 3 } ] }
    }
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your state

player.state:read

Read your planet, world, zone, mine, combat tag, boosters, pickaxe energy and sidebar.

Request

Approved app key with player.state:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Online players only. Offline players return an empty value, same as every player.*:read scope.

Fields

Under data.state.

planetstring

aether or celestial.

worldstring

The world name.

dimensionstring

main, cells, or the name of the managed world.

zonestring | null

safezone, the tier zone the sidebar shows, or null.

regionsstring[]

The regions the player stands in, sorted.

mine{ region, ore } | null

The mine the player is in.

combatTag{ active, expiresAt }

expiresAt is null when not tagged.

boosters[]object[]

type, multiplier, expiresAt and paused. A paused booster has expiresAt null and remainingMs.

energyobject | null

current, max, chargePercent and pickaxeLevel for the held pickaxe. null when none is held.

sidebarobject

layout, compact, components[] of key, enabled and order, and values keyed by component.

Response

Refreshed every 5 seconds. Subscribe to player.state.changed and player.sidebar.changed for changes. Client mods can ask for a fresh copy with the player.state.read broker action.

Testing mode: the same shape with mock values.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "state": {
      "planet": "aether", "world": "prison", "dimension": "main", "zone": "diamond", "regions": [ "mine_diamond" ],
      "mine": { "region": "mine_diamond", "ore": "diamond" },
      "combatTag": { "active": false, "expiresAt": null },
      "boosters": [ { "type": "xp", "multiplier": 2, "expiresAt": "2026-10-11T01:00:00.000Z", "paused": false } ],
      "energy": { "current": 12500, "max": 50000, "chargePercent": 25, "pickaxeLevel": 42 },
      "sidebar": { "layout": "pickaxe", "compact": false,
        "components": [ { "key": "current_zone", "enabled": true, "order": 0 } ],
        "values": { "current_zone": { "zone": "diamond" } } }
    }
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether" }
}

Required scope

Your cell vaults

player.cell_vaults:readSensitive

Read the cell vaults you own or can open, one page at a time.

Request

Approved app key with player.cell_vaults:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Fields

Under data.vaults[].

cellIdstring

The cell the vault belongs to.

vaultNamestring

The vault's name.

owner{ uuid, name }

The vault owner.

world, x, y, zstring, number

Where the vault stands.

pages[].pagenumber

The page number to read.

pages[].name, color, iconMaterialstring

How the page looks in game.

pages[].locked / frozenboolean

Locked pages are owner-only. Frozen pages are past the gang's limit and withdraw-only.

pages[].filledSlotsnumber

Slots holding an item.

pages[].accessstring

The player's access: view, deposit, withdraw, manage or owner.

Response

502 with runtime_action_failed and reason cell_vaults_unavailable when cell vaults are off on that server.

504 when the game server does not complete the read before the API timeout.

Testing mode: an empty vaults list. No game read runs.

Example response

{
  "data": {
    "playerId": "00000000-0000-0000-0000-000000000000",
    "vaults": [
      { "cellId": "cell_12", "vaultName": "Main", "owner": { "uuid": "00000000-0000-0000-0000-000000000001", "name": "Steve" }, "world": "cells", "x": 120, "y": 64, "z": -40,
        "pages": [ { "page": 1, "name": "Gear", "color": "red", "iconMaterial": "CHEST", "locked": false, "frozen": false, "filledSlots": 18, "access": "withdraw" } ] }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether", "actionId": "act_..." }
}

Required scope

Your cell vaults

player.cell_vaults:readSensitive

Read the cell vaults you own or can open, one page at a time.

Request

Approved app key with player.cell_vaults:read.

Header: x-cosmic-api-session-id for the live broker session approved by this player.

Path param: serverScope. Current valid values are aether and celestial.

Path param: playerId. This must match the player attached to the live broker session.

Path params: cellId and page, from the cell vault list.

Fields

Under data.

cellId / pagestring / number

The page read.

accessstring

The player's access to it, as on the list.

items[]object[]

Non-empty slots. Item fields match the player inventory endpoint.

Response

Access follows the in-game rules: the owner, or a page grant. Locked pages are owner-only. The player does not need to stand at the vault.

400 with reason out_of_range when the page does not exist.

403 with reason no_access when the player holds no grant on the page.

404 with reason not_found when the vault does not exist.

409 with reason vault_breaking, combat_tagged or locked, the same refusals as in game.

504 when the game server does not complete the read before the API timeout.

Testing mode: an empty items list. No game read runs.

Example response

{
  "data": {
    "cellId": "cell_12",
    "page": 1,
    "access": "withdraw",
    "items": [
      { "slot": 0, "material": "DIAMOND_PICKAXE", "amount": 1, "cosmicItemId": "cosmic_pickaxe", "customData": { "item_level": 42 } }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether", "actionId": "act_..." }
}

Live world

Merchants, guards, and meteors near the live player.

GET/v1/cosmic-api/runtime/servers/:serverScope/merchants

server.merchants:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.merchant.spawned",
  "payload": {
    "id": "evt_...",
    "type": "server.merchant.spawned",
    "eventType": "server.merchant.spawned",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "merchant": {
        "id": "merchant_spawn",
        "world": "world",
        "x": 48,
        "y": 64,
        "z": 12,
        "state": "active"
      }
    }
  }
}

List active merchants

Returns the active merchant records from the Redis runtime merchant snapshot.

Required scope

Merchants

server.merchants:read

See active merchant records on your current server while you have a live session. This currently is not distance-filtered.

Request

Approved app key with server.merchants:read.

Path param: serverScope. Current valid values are aether and celestial.

App-key callers must include x-cosmic-api-session-id for a live subject broker session.

Service and admin callers can read without a player subject.

Response

data.merchants: pass-through merchant records from the runtime merchant snapshot.

Current merchant fixture fields are id, world, x, y, z, and state.

meta.source: redis_runtime.

meta.snapshotName: merchants.

meta.snapshotStatus and meta.snapshotUpdatedAt.

meta.relationship, meta.subjectSessionId, and meta.requiredScope for subject-bound app-key reads.

403 when an app key has the scope but does not provide a live subject session.

404 with runtime_live_unavailable when no Redis merchant snapshot is available.

Example response

{
  "data": {
    "merchants": [
      {
        "id": "merchant_spawn",
        "world": "world",
        "x": 48,
        "y": 64,
        "z": 12,
        "state": "active"
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "merchants",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 5000,
    "accessMode": "app_key",
    "relationship": "subject_bound",
    "subjectSessionId": "sess_...",
    "requiredScope": "server.merchants:read"
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/guards/nearby

server.guards:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.guards.snapshot.changed",
  "payload": {
    "id": "evt_...",
    "type": "server.guards.snapshot.changed",
    "eventType": "server.guards.snapshot.changed",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "reason": "snapshot_changed",
      "totalEntities": 12,
      "coreGuards": 8,
      "merchantGuards": 4
    }
  }
}

Read nearby guards

Returns controlled guard records near the live player's server-side location.

Required scope

Guards

server.guards:read

See controlled guard location and status near your live player. Player-bound reads use your server-side location and are capped by the backend.

Request

Approved app key with server.guards:read.

Path param: serverScope. Current valid values are aether and celestial.

Optional query: radius. App-key player sessions are capped to 128 blocks. Default is 96.

App-key callers must include x-cosmic-api-session-id for a live subject broker session.

For app-key callers, x, y, z, and world query values are ignored. The API uses the approved player's server-side location.

Service and admin callers must provide x and z. They may also provide y and world.

Response

data.origin: the origin used for the search. For client mods this is the server-side player location.

data.radius: the radius actually used after caps are applied.

data.guards[]: normalized public guard records inside the radius.

data.guards[].id and entityId: guard identifiers.

data.guards[].category: core_guard, cell_guard, merchant_guard, or guard when the snapshot did not provide a category.

data.guards[].state: current public state. Active guards are returned as active.

data.guards[].cellGuard: only present when the snapshot marks whether it is a cell guard.

data.guards[].merchantId, merchantType, and zone: only present for merchant guards.

data.guards[].world, x, y, z, and location: controlled location fields.

data.guards[].distanceBlocks: horizontal distance from the origin.

Does not return guard health, max health, owner names, spawn locations, cell room ids, targeting state, pathing state, damage internals, or anti-cheat internals.

meta.source: redis_runtime.

meta.snapshotName: guards.

meta.cacheTtlMs: 1000.

403 when an app key has the scope but does not provide a live subject session.

404 with runtime_live_unavailable when no Redis guards snapshot is available.

Example response

{
  "data": {
    "origin": {
      "x": 0,
      "y": 64,
      "z": 0,
      "world": "world",
      "source": "subject_player"
    },
    "radius": 96,
    "guards": [
      {
        "id": "guard_123",
        "entityId": 123,
        "category": "core_guard",
        "state": "active",
        "cellGuard": false,
        "world": "world",
        "x": 24,
        "y": 64,
        "z": 0,
        "location": {
          "world": "world",
          "x": 24,
          "y": 64,
          "z": 0
        },
        "distanceBlocks": 24
      }
    ]
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "guards",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 1000,
    "accessMode": "app_key",
    "relationship": "subject_bound",
    "subjectSessionId": "sess_...",
    "requiredScope": "server.guards:read",
    "tacticalOriginSource": "subject_player",
    "tacticalRadius": 96
  }
}

GET/v1/cosmic-api/runtime/servers/:serverScope/meteor

server.meteors:read

Client mod payload

{
  "type": "event",
  "event": "hook",
  "sessionId": "sess_...",
  "eventType": "server.meteor.landing.changed",
  "payload": {
    "id": "evt_...",
    "type": "server.meteor.landing.changed",
    "eventType": "server.meteor.landing.changed",
    "version": 1,
    "subjectType": "server",
    "serverScope": "aether",
    "occurredAt": "2026-06-04T00:00:00.000Z",
    "payload": {
      "meteor": {
        "id": "meteor_active",
        "world": "world",
        "x": 150,
        "y": 90,
        "z": -35,
        "state": "falling",
        "landAtMillis": 1780359300000,
        "landingAt": "2026-06-02T00:15:00.000Z"
      }
    }
  }
}

Read meteor state

Returns the current meteor record from the Redis runtime meteor snapshot.

Required scope

Meteors

server.meteors:read

See the current meteor record on your current server while you have a live session, including when the active meteor lands when available.

Request

Approved app key with server.meteors:read.

Path param: serverScope. Current valid values are aether and celestial.

App-key callers must include x-cosmic-api-session-id for a live subject broker session.

Service and admin callers can read without a player subject.

Response

data.meteor: meteor record from the runtime meteor snapshot.

data.meteor.landingAt: ISO timestamp for when the active meteor lands when a landing timestamp is available.

Current meteor fixture fields are id, world, x, y, z, state, landAtMillis, and landingAt.

meta.source: redis_runtime.

meta.snapshotName: meteor.

meta.snapshotStatus and meta.snapshotUpdatedAt.

meta.cacheTtlMs: 2500.

meta.relationship, meta.subjectSessionId, and meta.requiredScope for subject-bound app-key reads.

403 when an app key has the scope but does not provide a live subject session.

404 with runtime_live_unavailable when no Redis meteor snapshot is available.

Example response

{
  "data": {
    "meteor": {
      "id": "meteor_active",
      "world": "world",
      "x": 150,
      "y": 90,
      "z": -35,
      "state": "falling",
      "landAtMillis": 1780359300000,
      "landingAt": "2026-06-02T00:15:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_...",
    "asOf": "2026-06-04T00:00:00.000Z",
    "source": "redis_runtime",
    "snapshotName": "meteor",
    "snapshotStatus": "available",
    "snapshotUpdatedAt": "2026-06-02T00:00:00.000Z",
    "serverScope": "aether",
    "cacheTtlMs": 2500,
    "accessMode": "app_key",
    "relationship": "subject_bound",
    "subjectSessionId": "sess_...",
    "requiredScope": "server.meteors:read"
  }
}

Auction House

Recent sales and prices, per planet.

Required scope

Auction House history

market.history:read

Read recent Auction House sales and hourly prices for one item on each planet, up to the last 7 days.

Request

Approved app key with market.history:read.

Path param: serverScope. Current valid values are aether and celestial. Each planet has its own Auction House.

Query: itemId. The market item key or Cosmic item id, matched without case, as the in-game history search does. Unique items match by their Cosmic item id.

Optional query: hours, 1–168, default 168. Sales older than 7 days are not kept.

Optional query: limit, 1–200, default 50.

Fields

Under data.

planet / itemIdstring

What was read.

window{ from, to }

The window covered, as ISO 8601.

stats.count / volumenumber

Sales and units sold in the window.

stats.minUnitPrice, maxUnitPrice, avgUnitPrice, medianUnitPricestring | null

Unit prices. The average is weighted by units. null with no sales.

stats.lastSale{ unitPrice, at } | null

The newest sale.

hourly[]object[]

bucketStart, low, avg and high (strings), volume and listingCount (numbers). Hours without data are left out.

recent[]object[]

The newest limit sales: at, unitPrice, quantity, totalPrice, buyer and seller as { uuid, name }, and item. Item fields match the player inventory endpoint, without slot.

Response

Prices are decimal strings.

Stats cover at most the newest 5,000 sales in the window.

meta.cacheTtlMs: 60000.

400 with reason item_required when itemId is missing.

502 with runtime_action_failed and reason market_unavailable when the Auction House is off on that server.

Testing mode: zero counts, null prices and empty lists. No game read runs.

Example response

{
  "data": {
    "planet": "aether",
    "itemId": "cosmic_pickaxe",
    "window": { "from": "2026-10-04T00:00:00.000Z", "to": "2026-10-11T00:00:00.000Z" },
    "stats": { "count": 14, "volume": 14, "minUnitPrice": "900000", "maxUnitPrice": "1400000", "avgUnitPrice": "1100000", "medianUnitPrice": "1050000",
      "lastSale": { "unitPrice": "1000000", "at": "2026-10-10T22:14:00.000Z" } },
    "hourly": [ { "bucketStart": "2026-10-10T22:00:00.000Z", "low": "1000000", "avg": "1000000", "high": "1000000", "volume": 1, "listingCount": 6 } ],
    "recent": [
      { "at": "2026-10-10T22:14:00.000Z", "unitPrice": "1000000", "quantity": 1, "totalPrice": "1000000",
        "buyer": { "uuid": "00000000-0000-0000-0000-000000000001", "name": "Steve" },
        "seller": { "uuid": "00000000-0000-0000-0000-000000000002", "name": "Alex" },
        "item": { "material": "DIAMOND_PICKAXE", "amount": 1, "cosmicItemId": "cosmic_pickaxe", "customData": { "item_level": 42 } } }
    ]
  },
  "meta": { "requestId": "req_...", "asOf": "2026-10-11T00:00:00.000Z", "serverScope": "aether", "cacheTtlMs": 60000 }
}

API endpoints

Request basics

Mod registry

List registry mods

Mod registry

Read registry mod

Mod registry

Read grant requirements

Mod registry

Servers & status

GET/v1/cosmic-api/runtime/capabilitiesRead API capabilitiesReturns the API version, the planets, and a flag for each feature the API serves.

Read API capabilities

List servers

Server status

Read server status

Server status

Events & world state

List events

Events and world state

Read next event

Events and world state

Read one event

Events and world state

GET/v1/cosmic-api/runtime/servers/:serverScope/worldevents:readRead world stateReturns the weather, mine vault, Prison Break, Ground Zero reset and Midas state the whole server can see.

Read world state

Events and world state

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/worldevents:readRead your world stateReturns the player's own mine vault contribution and Prison Break points.

Read your world state

Events and world state

GET/v1/cosmic-api/runtime/servers/:serverScope/world/midasevents:readRead Midas stateReturns the Midas blood bankers and the Bloody Mary boss room.

Read Midas state

Events and world state

Player data

Read player inventory

Your inventory

Read one inventory slot

Your inventory

Read one private vault

Your private vaults

Read one private vault slot

Your private vaults

GET/v1/cosmic-api/runtime/servers/:serverScope/leaderboards/:categoryleaderboards:readRead a leaderboardReturns one /top board, 25 rows, with banned players and staff removed.

Read a leaderboard

Leaderboards

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/satchelsplayer.satchels:readRead player satchelsReturns satchel fill rows for the inventory and for every satchel backpack the player carries.

Read player satchels

Your satchels

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/emblemsplayer.emblems:readRead player emblemsReturns the player's equipped emblem, progress, login streak and recent unlocks.

Read player emblems

Your emblems

GET/v1/cosmic-api/runtime/servers/:serverScope/emblemsplayer.emblems:readRead the emblem catalogReturns every emblem definition with its tier requirements and perk lines.

Read the emblem catalog

Your emblems

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/top-creditsplayer.top_credits:readRead player top creditsReturns the same balances, ledger and next checkpoint /credits prints.

Read player top credits

Your top credits

GET/v1/cosmic-api/runtime/servers/:serverScope/top-credits/payoutsplayer.top_credits:readRead top credit payoutsReturns the payout table for every top board and checkpoint.

Read top credit payouts

Your top credits

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/custom-setsplayer.custom_sets:readRead player custom setsReturns the Death and Greed set pieces the player wears, and their payday and death mark timers.

Read player custom sets

Your custom sets

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/ground-zeroplayer.ground_zero:readRead player Ground Zero stateReturns the player's Ground Zero sidebar and menu values while they are in the world.

Read player Ground Zero state

Your Ground Zero

Read a library

Your library

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/librariesplayer.library:readList libraries you can openReturns the session player's own library and every library shared with them.

List libraries you can open

Your library

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/walletplayer.wallet:readRead player balancesReturns the player's balance and other currencies.

Read player balances

Your balances

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/progressionplayer.progression:readRead player progressionReturns the player's level, experience, prestige and skill tree.

Read player progression

Your progression

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/stateplayer.state:readRead player stateReturns where the player is, what is active on them, and their sidebar.

Read player state

Your state

GET/v1/cosmic-api/runtime/servers/:serverScope/players/:playerId/cell-vaultsplayer.cell_vaults:readList cell vaultsReturns the cell vaults the player owns or can open, with their pages.