REST API reference

The SDK and CLI are thin clients over this HTTP API. Use it directly from engines without a JavaScript SDK, from your own server, or from tools. Base URL: your API (https://api.kumodeck.com). All bodies are JSON.

Authentication#

Errors always look like:

{ "error": { "code": "version_conflict", "message": "…", "details": { "currentVersion": 7 } } }

In the API, the people who use your app are called players (/v1/players/…, playerId); this page keeps that name.

Any origin. The SDK works from an app or game hosted anywhere (KUMODeck hosting, your own server, itch.io, localhost): CORS is open and auth is header-based. To stop other sites from using your publishable key, list your origins in kumo.config.json → web.allowedOrigins (see config); browser requests from other origins then get 403 origin_not_allowed. Every module works on its own: use only saves, only multiplayer, only hosting, and so on.

Features are off until you turn them on (features in config). Calling a feature that is off from your app or a secret key returns 403 feature_disabled with details: { feature, configPath } (e.g. features.saves), before anything is read or written. Guest sign-in, token refresh, your own player profile and reading the config always work. A feature that is not offered right now answers 403 feature_unavailable, and it cannot be turned on.

Resources you do not own return 404, not 403, so their existence is not revealed. An expired access token returns 401 token_expired — refresh and retry. Endpoints that change balances accept an Idempotency-Key header (1–128 chars of A-Z a-z 0-9 _ . : -); a retry with the same key returns the first result without applying twice.

Players & auth#

A session is { player: { id, displayName, isGuest, createdAt, identities }, accessToken, expiresIn, refreshToken }. Access tokens last 15 minutes, refresh tokens 90 days (rotating).

Email verification, password reset, external sign-in and privacy:

redirectUrl must be allowed by auth.redirectUrls in your config (localhost in development and your KUMODeck-hosted URLs always are). A provider answers 404 provider_disabled until enabled in auth.providers, and 409 provider_not_configured while its credentials are missing (Google, Discord, Apple). See Authentication.

Game data (player)#

Multiplayer#

WebSocket requests carry an optional rid and get { t: "reply", rid, ok, data | error }:

Server events: welcome, room_joined (snapshot, always before the reply), player_joined, player_left, player_disconnected, player_reconnected, host_changed, state, player_state, message, locked, signal (peer-to-peer rooms), room_closed, warn. Close codes: 4001 unauthorized, 4002 token expired (refresh and reconnect), 4003 banned / forbidden, 4004 replaced by a newer connection, 4008 idle, 4029 rate-limit abuse.

Realtime channels#

Off until features.realtimeChannels is on (guide). Over the same /v1/realtime WebSocket (one connection: one multiplayer room plus up to 8 channels). Nothing is stored: messages are delivered and dropped. A connection without a player id sends { "t": "auth", "key": "pk_…", "anon": true } and may join only channels your server made open.

Server events: channel_joined (settings and members, always before the reply), channel_message (from = player id or 'server', at = server time), channel_player_joined, channel_player_left, channel_self (canSend, mutedUntil), channel_closed (reason). Voice: voice_state (members: [{ id, canSpeak }]), voice_signal, voice_sfu_offer (relay-server calls), voice_closed (time_limit, suspended, unavailable). channel_joined carries voice: { mode: 'p2p' | 'sfu', relayOnly } | null.

Your server (secret key only; not available to delegated tokens):

Your own iOS / Android app (player)#

Age group (player)#

Ban appeals (player)#

A player you banned can see the ban and appeal it once. You read and answer appeals as the developer (below); accepting an appeal lifts the ban. Appeals are part of banning, so they are always available.

POST /v1/stats also runs your integrity rules (integrity.stats in config: value ranges, submissions per minute, an optional signed webhook to your server). Rejected values come back in rejected with a reason.

Sharing on X (player / public)#

Every tool here is off until you turn it on in kumo.config.json → share (see config and the guide). A tool that is off answers 404 share_<tool>_disabled; the SDK treats that as "not used".

KUMODeck-hosted apps also serve the same card images from the app's own domain: /.card.png and /.card/<shareId>.png. Sign in with X uses the normal OAuth routes with :provider = x (see Authentication). It needs your own X app's credentials in the dashboard; without them POST /v1/auth/oauth/x/start answers 409 provider_not_configured. Sign-in is free (X does not charge for it), so today it is never refused for billing. If X ever starts charging, apps using KUMODeck's shared X app would get 402 x_signin_unavailable (details.continueAsGuest: true) while the balance is overdue — keep the player on their guest account in that case.

Server (secret key)#

:ref is a deployment id or a version number.

Functions (secret key or dashboard)#

Your own server code and database (guide). Off by default. Each path is available at /v1/admin/<path> with X-Kumo-Key: sk_… and at /v1/projects/:projectId/environments/:env/<path> with a developer session.

From your Functions code (secret key only): POST /v1/admin/players/verify-token { token } → { player: { id, displayName, banned } } (401 for a token from another environment). To ban from your code, POST /v1/admin/players/:playerId/ban · /unban (see Operating your game).

Developer (dashboard session)#

Hosting endpoints are also available to developers under /v1/projects/:projectId/environments/:env/….

Money (developer session)#

Your prepaid balance and usage. Developer session only (Authorization: Bearer kds_…); secret keys cannot read or move money. Amounts are integers in minor units (cents).

Operating your game (secret key or dashboard)#

Each of these is available at /v1/admin/<path> with X-Kumo-Key: sk_… (your server, CLI, MCP) and at /v1/projects/:projectId/environments/:env/<path> with a developer session. Changes are written to the audit log.