KUMODeck

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#

CallerHeaders
Player (a signed-in user of your app or game)X-Kumo-Key: pk_… + Authorization: Bearer <access token>
Public app dataX-Kumo-Key: pk_… only
Server / CLI / CIX-Kumo-Key: sk_…
Developer (dashboard)Authorization: Bearer kds_…

Errors always look like:

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

Limits show up in errors. A malformed body is 400 invalid_request with details.issues listing { path, message }. An item over a length, count or value limit also carries limit (the maximum), and the first one is repeated as details.limit. Read limits from there instead of hard-coding them.

Paging through lists. Lists that return nextCursor take limit (1–1000) and cursor. Pass the previous response's nextCursor back as cursor until it is null to read everything; treat the cursor as an opaque string (don't parse or build it). An out-of-range limit is 400 invalid_request with the maximum in details.limit. A broken cursor is 400 invalid_cursor on every list, with details.cursor set to malformed (changed or cut off) or other_list (the nextCursor of a different list): drop the cursor and start again from the first page. Leaving out limit keeps each list's default page size.

Rate limits. Too many requests get 429 rate_limited with a Retry-After header and details: { rule, retryAfter, limit, windowSeconds, scope, configurable }. scope: "game" means it's counted for this app only; configurable: true means you can raise or lower it with rateLimits in the config. Don't hard-code the numbers: read them here or from GET /v1/admin/rate-limits.

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#

MethodPathBody → Response
POST/v1/auth/guest{ displayName? } → session
POST/v1/auth/email/signup{ email, password (≥ 8), displayName? } → session
POST/v1/auth/email/login{ email, password } → session
POST/v1/auth/refresh{ refreshToken } → session (rotated). 401 = chain revoked, 409 refresh_race = another tab just rotated it
POST/v1/auth/logout{ refreshToken }
POST/v1/auth/link/email{ email, password } → { player } (guest keeps all data)
GET / PATCH/v1/players/me→ { player } / { displayName }

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:

MethodPathBody → Response
POST/v1/auth/email/verify{ token } — from the verification link
POST/v1/auth/email/resend{ redirectUrl? } (player)
POST/v1/auth/password/forgot{ email, redirectUrl? } — always 200
POST/v1/auth/password/reset{ token, password } — revokes every refresh token of the player
POST / GET/v1/auth/oauth/:provider/start:provider = google | discord | apple | x. { redirectUrl, challenge, mode? } → { url }. With a player Authorization header the provider is linked to that player. GET (with key=pk_… in the query) redirects, for plain links
GET / POST/v1/auth/oauth/:provider/callbackthe provider returns here; then redirects to <redirectUrl>#kumo_code=… (or #kumo_error=…)
POST/v1/auth/oauth/exchange{ code, verifier } → session (the code lasts 60 s, once)
GET/v1/players/me/identities→ { identities } (sign-in methods; guest not included)
DELETE/v1/players/me/identities/:provider{ refreshToken } (this device's) → { player }. Signs out every other device. 409 last_login_method = it is the last way to sign in (add another first)
GET/v1/players/me/exporteverything stored about the player (JSON)
DELETE/v1/players/me{ password } or { refreshToken } — irreversible

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)#

MethodPathNotes
GET/v1/gamedata/definitionsthe public part of your config. pk_ only
GET/v1/saves{ saves: [{ key, version, size, updatedAt }] }
GET/v1/saves/:key{ key, version, size, updatedAt, data } · 404 if missing
PUT/v1/saves/:key{ data, ifVersion? } · 409 version_conflict, 413 save_too_large (2 MB per slot, details.limit)
DELETE/v1/saves/:key?ifVersion=
GET/v1/stats{ stats: { key: value } } (all-time)
POST/v1/stats{ stats: { key: value } } (≤ 64 keys) → { stats: { key: { period: value } }, rejected, unlocked }
GET/v1/inventory{ currencies, items }
POST/v1/inventory/consume{ currencies?, items? } all-or-nothing · 409 insufficient (details.shortages)

Multiplayer#

MethodPathNotes
GET (WebSocket)/v1/realtimefirst frame { "t": "auth", "key": "pk_…", "token": "<access token>" } within 5 s
GET/v1/rooms?mode=&limit=&cursor=open public rooms { rooms: [{ id, code, mode, players, maxPlayers, metadata, createdAt }], nextCursor } (busiest first) · limit ≤ 1000 (default 100)

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

tFields
createmode, private?, maxPlayers?, metadata?, code?, hostOnlyState?
joinroomId or code
quickMatch / cancelMatchmode / —
leave, resume—, roomId
sendtype (≤ 64), data? (≤ 16 KB), to?: playerId[]
setState / setMyStatepatch (null deletes a key)
locklocked (host only)
signalpeer-to-peer rooms only: to: playerId, kind: offer | answer | candidate | restart, data? (≤ 8 KB), gen? — relayed to that one player
iceServerspeer-to-peer rooms only → { iceServers, iceTransportPolicy: 'relay' | 'all', expiresAt } · turn_unavailable

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.

tFieldsErrors
channelJoinchannelchannel_not_found, channel_forbidden, channel_banned, channel_full, player_required, too_many_channels
channelCreatechannel? (@…, made for you when left out), join?, send?, maxMembers?, voice? (true or { mode: 'sfu' })channel_exists, player_required, voice_too_large, feature_disabled (features.voice)
channelLeavechannel—
channelSendchannel, type (≤ 64), data?not_in_channel, muted, send_forbidden, payload_too_large, rate_limited
channelModeratechannel, op, playerId, seconds? — op: invite, uninvite, allowSend, disallowSend, mute, unmute, kick, ban, unbanowner_only
voiceJoin / voiceLeavechannel — voice calls; the SDK sends these and the call's other messages (voiceSignal; voicePublish, voiceAnswer, voiceSpeaking in a relay-server call) for youvoice_disabled, voice_suspended, voice_unavailable, feature_disabled, player_required, not_in_channel, rate_limited

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):

MethodPathNotes
PUT/v1/realtime/channels/:name@ names only: { join?, send?, open?, maxMembers?, allow?: playerId[], speakers?: playerId[], voice?: true | { mode?: 'p2p' | 'sfu', relayOnly? } } → settings, lists, members · 409 voice_in_use
GET/v1/realtime/channels/:namethe same, never message text · 404 channel_not_found
DELETE/v1/realtime/channels/:name{ deleted: true } (members get channel_closed deleted)
POST/v1/realtime/channels/:name/messages{ type, data? } → { delivered } (arrives with from: 'server') · 600 / minute per key
POST/v1/realtime/channels/:name/moderate{ op, playerId, seconds? } → {} · 300 / minute per key (with PUT / DELETE)

Your own iOS / Android app (player)#

MethodPathNotes
POST/v1/auth/oauth/:provider/nativeapple / google: { idToken, nonce, platform, link?, name? } → session + { provider, linked }
POST/v1/players/me/age-signalOS age signal ({ platform, status, lowerBound?, upperBound?, source?, supervised? }); only ever makes the age group stricter

Ads (player)#

MethodPathNotes
POST/v1/ads/opportunities{ format: rewarded | interstitial, placement, consent?, sessionAgeSeconds? } → { allowed: true, opportunity } or { allowed: false, reason, retryAfterSeconds? } (refusals are 200) · 400 unknown_placement
POST/v1/ads/opportunities/:id/complete{ token } → { applied, status, format, granted } · 403 invalid_ad_token, 409 opportunity_expired / completed_too_fast / server_confirmation_required
POST/v1/ads/opportunities/:id/cancel{ reason?: closed | no_fill | error }
GET/v1/ads/house?opportunityId=cross-promotion slot ({ promo: null } until available)
GET / POST/v1/ads/providers/:provider/callbackad network server-to-server confirmation (only for configured ad networks; some, e.g. AppLixir, call with GET)

Rewards come from ads.rewards in your config, never from the client. The age group (below) decides child-directed and personalized treatment. Developers: GET /v1/projects/:projectId/ads/summary?from=&to=. /ads.txt is served by KUMODeck on the hosting domain (on your own domain, the ads.txt you deploy while ads are off — Hosting guide, Custom domains).

Age group (player)#

MethodPathNotes
GET/v1/social/profile{ ageBand, declaredAgeBand, capabilities }
PUT/v1/social/age{ band: child | teen | adult } (players can only make it stricter: 403 age_change_not_allowed)

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.

MethodPathNotes
GET/v1/players/me/sanctionsthe player's own bans (public note only)
POST/v1/players/me/sanctions/:sanctionId/appeal{ message } → 201 · one appeal per ban
POST/v1/auth/appeal{ refreshToken, sanctionId?, message } — for banned players (the refresh token revoked by the ban proves identity; without sanctionId, the ban that revoked the token)

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".

MethodPathAuthNotes
POST/v1/share/linksplayer{ kind: plain | score | challenge, score?, showName? } → 201 { link, imageUrl, post: { text, hashtags, via } }.
GET/v1/share/links/:shareIdpk_{ link: { id, kind, score, displayName, createdAt } } — restore a challenge on the receiving side
POST/v1/share/visitspk_ (+ player if signed in){ shareId, landed } — counted once per player per day (share.tracking)
GET/v1/share/images/:label/card.png · …/:shareId.pngnone1200×600 PNG card (share.images). :label = your slug, or <slug>--dev for development. Cached; unknown ids are 404
GET/v1/share/tags?ks=pk_ or sk_{ html, tags, image, defaultImage, shareImageTemplate } — <meta> tags for your page's <head> (read it on each request for a card per share). The image URLs are the published app's for either key, so the same tags work in the test app and the published app. If card images are off for this key's app but on in the other app, the tags come from the other app's settings (configFrom, configFallback: true); off in both → 404 share_images_disabled
GET/v1/players/me/x-profile · PUT { visible }playerthe player's X handle / name / avatar and whether they allow showing it (default: not shown)
GET/v1/players/x-profiles?ids=a,bpk_{ profiles: { [playerId]: { username, name, avatarUrl } } } — only players who opted in (max 100 ids)
POST/v1/auth/transferplayer→ 201 { code, expiresIn: 600 } — one-time code to continue as the same player in another browser (share.inAppBrowser)
POST/v1/auth/transfer/redeempk_{ code } → session

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)#

MethodPathNotes
GET / PUT/v1/configread / push master data for the key's environment
GET/v1/admin/rate-limitsrate limits you can change for the key's environment: { environment, version, rules: [{ name, per, default: { limit, windowSeconds }, effective: { limit, windowSeconds } | null, override }] } (effective: null = removed). Change them with rateLimits in the config
GET/v1/admin/featuresevery feature with { key, title, configPath, source, enabled } (also at /v1/projects/:projectId/environments/:env/features)
GET/v1/admin/players/:playerId/inventory?limit=&cursor=read only: { currencies, items, ledger, nextCursor } of a player in the key's environment (ledger = the changes, newest first; 100 per page by default, limit ≤ 1000, older ones with cursor) · 403 feature_disabled when inventory is off · 404 player_not_found
POST/v1/deployments{ files: [{ path, sha256, size }], message? } → { deploymentId, version, missing, missingBytes }
PUT/v1/blobs/:sha256raw bytes of one missing file (≤ 100 MB)
POST/v1/deployments/:ref/finalize{ activate?: true, allowSecretLike?: false } · 409 blobs_missing · warnings lists skipped _headers / _redirects lines (line, limit) · 422 secret_like_content when a text file contains a saved key, a known secret-key shape or key-like random text (details.findings: path, line, kind, what in plain words, secretName for a saved key, first characters only; why). allowSecretLike: true publishes anyway and records it on the version (secretLikeAllowed)
POST/v1/deployments/:ref/activateswitch the live version (rollback / promote)
GET/v1/deployments?limit=&cursor= · /v1/deployments/:ref · /v1/hostinghistory, newest first: { deployments, nextCursor } (pass nextCursor back as cursor for older versions; null = no more), one version (with manifest), live URLs

: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.

Method<path>Notes
GETfunctions{ enabled, suspended, limits, limitRanges, deployed, version, url, crons, durableObjects, resources, secrets } (secret names only). limitRanges gives { min, max, default } for cpuMs and subRequests
POSTfunctions/enable · functions/disableenable: { cpuMs?, subRequests? } · 402 prepaid_required without prepaid credit · disable keeps code and data
PUTfunctions/limits{ cpuMs? (1–300000), subRequests? (0–10000000), app?: { cpuMs?, subRequests? } } (app = the server-rendered app). Out of range: 400 with details.limit. The response's limits / appLimits show the value in effect, requested, cpuMsCap (from your prepaid balance) and requiredBalance The allowed range is limitRanges from GET functions.
POSTfunctions/deployments{ mainModule, modules: [{ name, type, content (base64) } or { name, type, sha256, size }], bindings, vars, crons, compatibilityDate?, message? } → 201 { version, queues, … }. A queue binding may carry settings: { maxBatchSize (1–100), maxBatchTimeout (0–60 s), maxRetries (0–100), deadLetterQueue (another queue binding), messageRetentionPeriod (60–1,209,600 s) }; defaults 10 / 5 / 3 / none / 14 days; an out-of-range value is a 400 whose issues[] carry limit. Usually sent by kumodeck functions deploy
GETfunctions/deployments?limit=&cursor=history, newest first: { deployments, nextCursor }
POSTfunctions/uploadsFor bundles too big to send inline (inline base64 contents total at most 15 MB). { modules: [{ sha256, size }] } → 201 { uploadId, missing, missingBytes, totalBytes, expiresAt, limitBytes }. The whole bundle may be up to 64 MiB uncompressed (the Cloudflare Workers limit; 413 functions_bundle_too_large with details.limitBytes). PUT each missing file, then deploy with { name, type, sha256, size } modules. There is no cap on the number of modules; names up to 1,024 characters
PUTfunctions/blobs/:sha256raw bytes of one file listed in a pending upload (expires after 1 hour; 409 blob_not_expected otherwise). The sha256 and size are verified
DELETEfunctions?purge=trueremove the code; purge also deletes databases, KV, files and queues
GET / PUT / DELETEfunctions/secrets · functions/secrets/:namevalues go straight to the runtime and are never stored or returned; PUT keeps only a one-way fingerprint (HMAC) so publishing can stop a page that contains the same text, deleted with the key
POSTfunctions/db/:binding/query · functions/db/:binding/migrate{ sql, params? } · { migrations: [{ name, sql }] } → { applied, failed, skipped }

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)#

MethodPath
POST/v1/developers/signup · /login · /logout · GET /v1/developers/meaccount (me includes hasPassword). signup takes an optional inviteCode (signupRequiresInvite in GET /v1/platform/info says whether one is required; when it is and none is sent: 400 invite_code_required, details.signupUrl). An invalid code creates no account: 400 invalid_invite_code / 409 invite_code_used / invite_limit_reached; codes with a limited number of people and an end date also return 409 invite_code_used_up / invite_code_expired
POST/v1/developers/me/invite-code{ code } → { credited: 500, currency: "usd", pending } — invite credit (usage fees only; it cannot be refunded or withdrawn), added once the email is confirmed (pending: true until then). Developer session only (not MCP). 409 already_redeemed (one per account)
POST/v1/developers/oauth/:provider/start · /v1/developers/oauth/exchangeexchange takes an optional inviteCode for a new account (when signupRequiresInvite is true and none is sent: 400 invite_code_required, no account made; an existing account signs in without it and gets invite: { ignored: true } if one is sent). Google / GitHub sign-in, adding a method (intent: "link") and re-confirming (intent: "reauth"), with PKCE. Providers the server has turned on: oauthProviders in GET /v1/platform/info
GET / DELETE / POST/v1/developers/me/identities · /me/identities/:provider · /me/passwordsign-in methods: list · remove (needs password or reauthToken; the last one cannot be removed) · set or change the password
POST/v1/developers/password/forgot · /password/reset/account · /password/resetforgotten password: { email } sends a reset link (always 200) · { token } → { email }, the account the link is for, so the page can show it and a password manager can save the new password under it (does not use up the link) · { token, password } sets the new password and signs out every session. The link's token goes in the request body, never in the URL. An invalid, expired or used link: 400 invalid_token
GET / POST/v1/projectslist / create (returns every key in plain text once)
GET / DELETE/v1/projects/:projectId
PATCH/v1/projects/:projectId{ name } (1–80 characters) → { project, previousName, changed }. Renames the project (its name is in the subject and sender of emails to users); the slug does not change. 400 name_reserved for names that look like KUMODeck or its staff (also on create); 429 after 20 renames an hour
POST/v1/projects/:projectId/environments/:env/keysnew key · DELETE /v1/projects/:projectId/keys/:keyId revokes
GET / PUT/v1/projects/:projectId/environments/:env/configmaster data
GET…/environments/:env/overviewplayers, daily actives (14 days), config version, keys
GET…/environments/:env/players?q=&cursor=&limit= · …/players/:playerIdsearch / detail
POST…/environments/:env/players/:playerId/ban · /unbanban closes live connections immediately
GET…/environments/:env/realtimeread-only view of live rooms
GET/v1/projects/:projectId/audit?limit=&before=&env=audit log

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).

MethodPathNotes
GET/v1/money/prepaid · /v1/money/prepaid/ledger?limit=&cursor={ balance, owed, invite, topUpLimits, topUpFee } · { entries, nextCursor }. topUpLimits: { min, max } for one top-up, in cents. invite: { granted, remaining, pending } or null (remaining is part of balance) topUpFee: { bps, fixed } card fee for a top-up (from the fee table).
POST/v1/money/prepaid/checkout{ amount (cents, $0.50–$10,000; the maximum can be raised per account; out of range → 400 invalid_amount with details.limit/min/max), successUrl, cancelUrl } + Idempotency-Key → Stripe Checkout (3D Secure); GET /v1/money/prepaid/checkouts/:id to poll
GET/v1/money/usage?period=YYYY-MM&refresh=usage cost by component (micro-USD) and what was charged (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.

Method<path>Notes
PUTplayers/:playerId/age{ band } — correct a player's age group (e.g. after a parent's confirmation)
POSTplayers/:playerId/ban · players/:playerId/unban{ reason? (≤ 500), durationHours? (> 0, ≤ 8784; secret key only, leave out = until unban) } → { player: { id, banned, bannedAt, banReason, revokedSessions, banExpiresAt } }. Closes live connections at once; 404 player_not_found. Always available (no feature switch); a ban set anywhere can be lifted from anywhere
GETappeals?status=&limit=&cursor= · POST appeals/:appealId/resolveban appeals from your players (oldest first: { appeals, nextCursor }) · { accept, response? } — accepting lifts the ban. Always available
GETintegrity/webhook-secretthe key your stats webhook verifies
GETshare/stats?from=&to=&shareId=&limit=&cursor=visits, new players, plays per share link (UTC days, default last 30 days, max 366). More links than limit: pass nextCursor back as cursor (totals and byDay are the same on every page)
POSTshare/links{ label } → 201 { link, url, query } — a tracked link for your own post
GETshare/tags?ks=same as /v1/share/tags (used by kumodeck share tags)