API endpoints
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.
Backend apps send their approved app key.
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.
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.
504 — the game server didn't complete a scoped read before the API timeout.
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.
{
"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.
Mod registry
registry:readRead public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.
Approved app key with registry:read.
Optional query: category.
Optional query: server.
Optional query: page.
Optional query: pageSize.
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.
{
"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"
}
}Mod registry
registry:readRead public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.
Approved app key with registry:read.
Path param: slug. This can match id, appId, appPublicId, clientId, modId, or slug.
data.mod: the public mod record.
404 when the mod is private, unapproved, or missing.
meta.requestId and meta.asOf.
{
"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"
}
}Mod registry
registry:readRead public mod registry listings, mod details, and grant requirements. This does not include live server state, inventories, warp counts, or outpost status.
Approved app key with registry:read.
Path param: slug. This can match id, appId, appPublicId, clientId, modId, or slug.
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.
{
"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
The public server list and per-server online state.
Server status
server.status:readSee 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.
Approved app key with server.status:read.
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.
{
"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
}
}Server status
server.status:readSee 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.
Approved app key with server.status:read.
Path param: serverScope. Current valid values are aether and celestial.
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.
{
"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 and Ground Zero state.
Events and world state
events:readRead the public events schedule, plus weather, mine vault raids, Prison Break and Ground Zero reset state. Also reads your own mine vault contribution and Prison Break points.
Approved app key with events:read.
Path param: serverScope. Current valid values are aether and celestial.
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.
{
"data": {
"events": [
{
"id": "event_meteor",
"name": "Meteor",
"startsAt": "2026-06-02T01:00:00.000Z"
}
]
},
"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
}
}Events and world state
events:readRead the public events schedule, plus weather, mine vault raids, Prison Break and Ground Zero reset state. Also reads your own mine vault contribution and Prison Break points.
Approved app key with events:read.
Path param: serverScope. Current valid values are aether and celestial.
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.
{
"data": {
"nextEvent": {
"id": "event_meteor",
"name": "Meteor",
"startsAt": "2026-06-02T01:00:00.000Z"
},
"events": [
{
"id": "event_meteor",
"name": "Meteor",
"startsAt": "2026-06-02T01:00:00.000Z"
}
]
},
"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
}
}Events and world state
events:readRead the public events schedule, plus weather, mine vault raids, Prison Break and Ground Zero reset state. Also reads your own mine vault contribution and Prison Break points.
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.
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.
{
"data": {
"event": {
"id": "event_meteor",
"name": "Meteor",
"startsAt": "2026-06-02T01:00:00.000Z"
}
},
"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
}
}Events and world state
events:readRead the public events schedule, plus weather, mine vault raids, Prison Break and Ground Zero reset state. Also reads your own mine vault contribution and Prison Break points.
Approved app key with events:read.
Path param: serverScope. Current valid values are aether and celestial.
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.
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.
{
"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
}
}Events and world state
events:readRead the public events schedule, plus weather, mine vault raids, Prison Break and Ground Zero reset state. Also reads your own mine vault contribution and Prison Break points.
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.
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.
{
"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" }
}Player data
Reads for the approved player, plus the leaderboards and catalogs they draw from.
Your inventory
player.inventory:readSensitiveRead the item type, amount, Cosmic item id, and approved custom data for items in your inventory.
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.
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.
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.
{
"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_..."
}
}Your inventory
player.inventory:readSensitiveRead the item type, amount, Cosmic item id, and approved custom data for items in your inventory.
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.
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.
{
"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_..."
}
}Your private vaults
player.private_vaults:readSensitiveRead the item type, amount, Cosmic item id, and approved custom data for one private vault page at a time.
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.
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.
{
"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_..."
}
}Your private vaults
player.private_vaults:readSensitiveRead the item type, amount, Cosmic item id, and approved custom data for one private vault page at a time.
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.
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.
{
"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_..."
}
}Leaderboards
leaderboards:readRead public leaderboard standings for every /top board.
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.
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.
{
"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 }
}Your satchels
player.satchels:readRead your satchel fill amounts and the satchels stored in your backpacks.
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.
data.satchels[]: satchels held directly in the inventory. Rows carry slot, type (Cosmic item id), 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 bagId, level, usedSlots, capacity, energy, maxEnergy and storedSatchels[] (same row shape as data.satchels, plus the slot inside the backpack).
Does not return other players' backpacks, level-up odds or wormhole session internals.
{
"data": {
"playerId": "00000000-0000-0000-0000-000000000000",
"satchels": [
{ "slot": 3, "type": "ore_satchel", "name": "Ore Satchel", "amount": 1, "level": 2, "energy": 80, "maxEnergy": 200, "ore": "diamond", "refined": false, "tier": "regular", "count": 1240, "capacity": 5000 }
],
"satchelBackpacks": [
{ "bagId": "00000000-0000-0000-0000-000000000001", "level": 2, "usedSlots": 4, "capacity": 10, "energy": 120, "maxEnergy": 300,
"storedSatchels": [ { "slot": 0, "type": "ore_satchel", "name": "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" }
}Your emblems
player.emblems:readSee your equipped emblem, emblem progress, login streak and recent unlocks.
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.
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.
{
"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" }
}Your emblems
player.emblems:readSee your equipped emblem, emblem progress, login streak and recent unlocks.
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.
data.emblems[]: id, displayName, symbol, category, perkType and tiers[] with requirement and perkLine.
meta.snapshotName: emblems. meta.cacheTtlMs: 60000.
{
"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 }
}Your top credits
player.top_credits:readRead your Top Credit balances, ledger and the next payout checkpoint.
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.
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.
{
"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" }
}Your top credits
player.top_credits:readRead your Top Credit balances, ledger and the next payout checkpoint.
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.
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.
{
"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 }
}Your custom sets
player.custom_sets:readSee the Death and Greed set pieces you wear, and your payday and death mark timers.
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.
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.
{
"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" }
}Your Ground Zero
player.ground_zero:readRead your Ground Zero points, weekly upgrades and charm cooldowns while you are in the world.
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.
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.
{
"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" }
}Your library
player.library:readSensitiveRead your library, and libraries other players share with you in game.
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.
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, 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.
{
"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", "count": 4200 } ] }
]
},
"meta": { "requestId": "req_...", "asOf": "2026-09-03T00:00:00.000Z", "serverScope": "aether", "actionId": "act_...", "relationship": "library_grantee" }
}Live world
Merchants, guards, and meteors near the live player.
Merchants
server.merchants:readSee active merchant records on your current server while you have a live session. This currently is not distance-filtered.
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.
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.
{
"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"
}
}Guards
server.guards:readSee controlled guard location and status near your live player. Player-bound reads use your server-side location and are capped by the backend.
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.
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.
{
"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
}
}Meteors
server.meteors:readSee the current meteor record on your current server while you have a live session, including when the active meteor lands when available.
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.
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.
{
"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"
}
}