{ "openapi": "3.1.0", "info": { "title": "Triggair API", "version": "1.0.0", "description": "The Triggair game backend HTTP API. Most games use the @triggair/sdk client rather than raw HTTP; this spec is the underlying contract. See https://triggair.com/llms.txt for the agent guide." }, "servers": [ { "url": "https://api.triggair.com" } ], "components": { "securitySchemes": { "TriggairKey": { "type": "apiKey", "in": "header", "name": "X-Triggair-Key" }, "PlayerToken": { "type": "http", "scheme": "bearer", "description": "Anonymous player token from /v1/players/anonymous." }, "DevSession": { "type": "http", "scheme": "bearer", "description": "Developer Supabase session JWT." }, "OperatorSession": { "type": "http", "scheme": "bearer", "description": "Operator (admin) session JWT (AAL2)." } } }, "paths": { "/v1/players/anonymous": { "post": { "tags": [ "Players" ], "summary": "Mint an anonymous player token", "description": "Exchanges a stable device id for a 24h player token. The player is created on first use. This is what the SDK's tg.login() calls; every player-scoped call sends the returned token as `Authorization: Bearer`.", "security": [ { "TriggairKey": [] } ], "responses": { "200": { "description": "A banned account or device is refused with 403 player_banned.", "content": { "application/json": { "example": { "player_id": "p_1a2b3c", "token": "eyJ…", "expires_in": 86400 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "device_id": "a-stable-device-uuid", "turnstile_token": "optional-if-challenge-on" } } } } } }, "/v1/players/recover": { "post": { "tags": [ "Players" ], "summary": "Recover a player on a new device", "description": "Consumes a recovery code (from /v1/players/me/recovery-code) to rebind the same player to a new device, returning a fresh token.", "security": [ { "TriggairKey": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_1a2b3c", "token": "eyJ…", "expires_in": 86400 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "RECOVERY-CODE", "device_id": "new-device-uuid" } } } } } }, "/v1/players/me": { "get": { "tags": [ "Players" ], "summary": "Get the current player", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_1a2b3c", "display_name": null, "created_at": "2026-07-01T00:00:00Z" } } } } } }, "patch": { "tags": [ "Players" ], "summary": "Update the player's profile (e.g. display name)", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_1a2b3c", "display_name": "AceRunner" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "display_name": "AceRunner" } } } } } }, "/v1/players/me/recovery-code": { "post": { "tags": [ "Players" ], "summary": "Mint a cross-device recovery code", "description": "Returns a single-use code the player saves/shares once; redeem it later with /v1/players/recover on another device.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "code": "RECOVERY-CODE", "expires_at": "2026-08-01T00:00:00Z" } } } } } } }, "/v1/players/me/moderation": { "get": { "tags": [ "Players" ], "summary": "Get the caller's own ban/mute status", "description": "The player's active bans and restrictions (shadow actions are hidden from self-view).", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "banned": false, "restrictions": [] } } } } } } }, "/v1/saves": { "get": { "tags": [ "Saves" ], "summary": "List the player's save slots", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "saves": [ { "slot": "slot1", "version": 3, "updated_at": "2026-07-01T00:00:00Z" } ] } } } } } } }, "/v1/saves/{slot}": { "get": { "tags": [ "Saves" ], "summary": "Read a save slot", "parameters": [ { "name": "slot", "in": "path", "required": true, "description": "Slot name (game-defined).", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "slot": "slot1", "data": { "level": 4, "coins": 120 }, "version": 3 } } } } } }, "put": { "tags": [ "Saves" ], "summary": "Write a save slot", "description": "Last-write-wins by default. Send `If-Match: ` for optimistic concurrency — a stale version returns 409 save_conflict. Returns 201 on first write, 200 on update.", "parameters": [ { "name": "slot", "in": "path", "required": true, "description": "Slot name.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "slot": "slot1", "data": { "level": 5, "coins": 90 }, "version": 4 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": { "level": 5, "coins": 90 } } } } } }, "delete": { "tags": [ "Saves" ], "summary": "Delete a save slot", "parameters": [ { "name": "slot", "in": "path", "required": true, "description": "Slot name.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/leaderboards/{board}/scores": { "post": { "tags": [ "Leaderboards" ], "summary": "Submit a score", "description": "Submits a score to a configured board. The board's aggregation (best/last/sum) and period (all-time/daily/weekly) are set by the developer; the response reports the player's kept score for the current period.", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "best_score": 9000, "period_key": "2026-07" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "score": 9000 } } } } } }, "/v1/leaderboards/{board}/top": { "get": { "tags": [ "Leaderboards" ], "summary": "Read the top entries", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Max entries (default 10).", "schema": { "type": "integer" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "board": "high_scores", "period_key": "2026-07", "entries": [ { "rank": 1, "player_id": "p_9", "score": 12000 } ] } } } } } } }, "/v1/leaderboards/{board}/around-me": { "get": { "tags": [ "Leaderboards" ], "summary": "Read entries around the player", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "board": "high_scores", "period_key": "2026-07", "me": { "rank": 42, "score": 8000 }, "entries": [] } } } } } } }, "/v1/leaderboards/{board}/friends": { "get": { "tags": [ "Leaderboards" ], "summary": "Read the friends-only board", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "board": "high_scores", "period_key": "2026-07", "me": { "rank": 2, "score": 8000 }, "entries": [] } } } } } } }, "/v1/players/me/stats": { "get": { "tags": [ "Players" ], "summary": "Get the player's own stats", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "stats": [ { "key": "kills", "value": 12 } ] } } } } } }, "post": { "tags": [ "Players" ], "summary": "Update stats (set / increment)", "description": "Applies one or more stat operations atomically. Stats back leaderboards, achievements, and segment targeting.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "stats": [ { "key": "kills", "value": 13 } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "ops": [ { "key": "kills", "op": "increment", "value": 1 } ] } } } } } }, "/v1/players": { "get": { "tags": [ "Players" ], "summary": "Look up players (public fields)", "parameters": [ { "name": "ids", "in": "query", "required": false, "description": "Comma-separated player ids.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "players": [ { "player_id": "p_9", "display_name": "Rival" } ] } } } } } } }, "/v1/players/{id}": { "get": { "tags": [ "Players" ], "summary": "Get another player's public profile", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_9", "display_name": "Rival" } } } } } } }, "/v1/achievements": { "get": { "tags": [ "Achievements" ], "summary": "List achievements + the caller's progress", "description": "Definitions plus this player's progress; secret achievements are hidden until unlocked.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "achievements": [ { "key": "first_win", "unlocked": true, "progress": 1, "target": 1 } ] } } } } } } }, "/v1/achievements/{key}/progress": { "post": { "tags": [ "Achievements" ], "summary": "Report achievement progress", "description": "The server clamps progress, unlocks exactly once, and escrows any reward into the inbox. The client reports progress but never grants the reward.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Achievement key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "first_win", "unlocked": true, "progress": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "amount": 1 } } } } } }, "/v1/daily": { "get": { "tags": [ "Daily" ], "summary": "Get daily-reward status", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "claimable": true, "streak": 3, "next_claim_at": "2026-07-11T00:00:00Z" } } } } } } }, "/v1/daily/claim": { "post": { "tags": [ "Daily" ], "summary": "Claim today's reward", "description": "Server-day gated; the reward is escrowed into the inbox. Re-claiming the same day → 409 conflict.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "claimed": true, "streak": 4 } } } } } } }, "/v1/inbox": { "get": { "tags": [ "Inbox" ], "summary": "List inbox items", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max items.", "schema": { "type": "integer" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "id": "in_1", "kind": "reward", "claimable": true, "read": false } ] } } } } } } }, "/v1/inbox/{id}/read": { "post": { "tags": [ "Inbox" ], "summary": "Mark an inbox item read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbox item id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/inbox/{id}/claim": { "post": { "tags": [ "Inbox" ], "summary": "Claim an inbox item's reward", "description": "The single hardened grant path — exactly-once (idempotent per item). Grants currency, items, or stat rewards.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbox item id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "claimed": true, "granted": { "currency": [ { "code": "gold", "amount": 100 } ] } } } } } } } }, "/v1/friends": { "get": { "tags": [ "Social" ], "summary": "List friends", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "friends": [ { "player_id": "p_9", "display_name": "Rival", "state": "accepted" } ] } } } } } } }, "/v1/friends/requests": { "get": { "tags": [ "Social" ], "summary": "List incoming friend requests", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "requests": [ { "player_id": "p_7", "display_name": "Newcomer" } ] } } } } } } }, "/v1/friends/{id}": { "post": { "tags": [ "Social" ], "summary": "Send or accept a friend request", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The other player's id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "state": "pending" } } } } } }, "delete": { "tags": [ "Social" ], "summary": "Remove a friend / cancel a request", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The other player's id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/friends/{id}/block": { "post": { "tags": [ "Social" ], "summary": "Block a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The player to block.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "blocked": true } } } } } } }, "/v1/share": { "post": { "tags": [ "Social" ], "summary": "Mint a share / invite link", "description": "Creates a short code carrying an opaque context blob (a level, a challenge, a referral). Resolve it with GET /v1/share/:code on the recipient's device.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "code": "SH4RE", "expires_at": "2026-07-18T00:00:00Z" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "context": { "level": 7 }, "expires_in_seconds": 604800 } } } } } }, "/v1/share/{code}": { "get": { "tags": [ "Social" ], "summary": "Resolve a share link", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Share code.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "context": { "level": 7 }, "from": "p_1a2b3c" } } } } } } }, "/v1/moderate/check": { "post": { "tags": [ "Moderation" ], "summary": "Pre-check text before submit", "description": "Runs the same moderation the write paths use, so you can validate a chosen name/message without a round-trip failure. Stateless (writes nothing).", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "verdict": "mask", "masked_text": "player ****", "categories": [ "profanity" ], "severity": 2 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "surface": "username", "text": "player name to check" } } } } } }, "/v1/reports": { "post": { "tags": [ "Moderation" ], "summary": "Report a player / message / UGC", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "cr_1", "state": "open" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "target_type": "player", "target_id": "p_9", "reason": "harassment", "note": "optional" } } } } } }, "/v1/appeals": { "post": { "tags": [ "Moderation" ], "summary": "Appeal a ban", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ap_1", "state": "pending" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "ban_id": "bn_1", "body": "why the ban should be lifted" } } } } } }, "/v1/players/me/age": { "post": { "tags": [ "Compliance" ], "summary": "Set the player's age bracket", "description": "Neutral age screen. A birth year is mapped to a bracket and DISCARDED (no DOB stored). Returns the compliance view with the gated-feature map.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "bracket": "13_15", "consent_state": "pending", "gated": { "open_chat": true, "lootbox": true } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "birth_year": 2013 } } } } } }, "/v1/players/me/compliance": { "get": { "tags": [ "Compliance" ], "summary": "Get the compliance view (bracket + gated map)", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "bracket": "13_15", "consent_state": "pending", "gated": { "open_chat": true } } } } } } } }, "/v1/compliance/policy": { "get": { "tags": [ "Compliance" ], "summary": "Get the game's gate policy (pre-token)", "description": "pk-only so the client can pre-disable regulated UI before a player token exists.", "security": [ { "TriggairKey": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "gates": { "open_chat": "13_15", "lootbox": "adult" }, "coppa_mode": false, "default_jurisdiction": "US" } } } } } } }, "/v1/players/me/consent/request": { "post": { "tags": [ "Compliance" ], "summary": "Request parental consent (emails the parent)", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "pc_1", "state": "pending", "expires_at": "2026-07-24T00:00:00Z" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "parent_email": "parent@example.com" } } } } } }, "/v1/players/me/consent": { "get": { "tags": [ "Compliance" ], "summary": "Get the player's consent record", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "consent": { "id": "pc_1", "state": "pending" } } } } } } } }, "/v1/consent/{token}": { "get": { "tags": [ "Compliance" ], "summary": "Parent consent landing page (HTML)", "description": "The signed link a parent receives by email; renders Approve/Decline. No pk/token — the signed token IS the credential.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Signed consent token from the email.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Success." } } } }, "/v1/consent/{token}/decide": { "post": { "tags": [ "Compliance" ], "summary": "Record the parent's decision", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Signed consent token.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "state": "granted" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "grant": true, "note": "optional" } } } } } }, "/v1/crashes": { "post": { "tags": [ "Crashes" ], "summary": "Report a crash", "description": "Grouped server-side by a normalized-stack fingerprint into a handful of issues with a crash-free-users %.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "group_id": "cg_1" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "message": "TypeError: x is undefined", "stack": "at play (game.js:42)", "platform": "web", "appVersion": "1.4.0" } } } } } }, "/v1/rng/{stream}": { "get": { "tags": [ "RNG" ], "summary": "Deterministic server-seeded random values", "description": "A verifiable per-player, per-period stream — the same request returns the same values, so loot/crit rolls can't be client-forged.", "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "Stream name (e.g. 'loot').", "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "How many values.", "schema": { "type": "integer" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "stream": "loot", "period_key": "2026-07", "values": [ 0.42, 0.88 ] } } } } } } }, "/v1/realtime/rooms/{room}": { "get": { "tags": [ "Realtime" ], "summary": "Join a realtime room (WebSocket upgrade)", "description": "A WebSocket upgrade. Because a browser WS can't send headers, the pk + player token go in the query (?key=&token=). Presence + broadcast; chat is moderated in transit. Rooms named team: / match: require membership. Use tg.realtime.join(room) from the SDK.", "parameters": [ { "name": "room", "in": "path", "required": true, "description": "Room name; team:/match: prefixes enforce membership.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "description": "Publishable key (query, since a WS can't set headers).", "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "description": "Player token.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success." } } } }, "/v1/wallet": { "get": { "tags": [ "Economy" ], "summary": "Get all currency balances", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "balances": [ { "currency": "gold", "amount": 250 } ] } } } } } } }, "/v1/wallet/history": { "get": { "tags": [ "Economy" ], "summary": "Get currency transaction history", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max lines.", "schema": { "type": "integer" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "lines": [ { "currency": "gold", "delta": -100, "reason": "store_buy", "created_at": "2026-07-01T00:00:00Z" } ] } } } } } } }, "/v1/wallet/{currency}": { "get": { "tags": [ "Economy" ], "summary": "Get one currency's balance", "parameters": [ { "name": "currency", "in": "path", "required": true, "description": "Currency code.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "currency": "gold", "amount": 250 } } } } } } }, "/v1/stores": { "get": { "tags": [ "Economy" ], "summary": "List stores", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "stores": [ { "key": "main_store", "name": "Shop" } ] } } } } } } }, "/v1/stores/{key}": { "get": { "tags": [ "Economy" ], "summary": "Get a store's listings", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Store key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "main_store", "listings": [ { "id": "l_1", "item": "sword", "price": { "gold": 100 } } ] } } } } } } }, "/v1/stores/{key}/buy": { "post": { "tags": [ "Economy" ], "summary": "Buy a store listing", "description": "Server-authoritative price + balance check; idempotent (pass idem). Fails with insufficient_funds / out_of_stock / store_limit_reached.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Store key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "granted": { "items": [ { "item": "sword", "qty": 1 } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "listing_id": "l_1", "idem": "uuid" } } } } } }, "/v1/inventory": { "get": { "tags": [ "Economy" ], "summary": "List the player's inventory", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "item": "sword", "qty": 1, "equipped": true } ] } } } } } } }, "/v1/inventory/{item}/consume": { "post": { "tags": [ "Economy" ], "summary": "Consume an item", "parameters": [ { "name": "item", "in": "path", "required": true, "description": "Item id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "remaining": 0 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "qty": 1, "idem": "uuid" } } } } } }, "/v1/inventory/{item}/equip": { "post": { "tags": [ "Economy" ], "summary": "Equip an item", "parameters": [ { "name": "item", "in": "path", "required": true, "description": "Item id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "equipped": true } } } } } } }, "/v1/inventory/{item}/unequip": { "post": { "tags": [ "Economy" ], "summary": "Unequip an item", "parameters": [ { "name": "item", "in": "path", "required": true, "description": "Item id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "equipped": false } } } } } } }, "/v1/loot/{key}/odds": { "get": { "tags": [ "Economy" ], "summary": "Get a loot box's disclosed odds", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Loot box key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "bronze_box", "odds": [ { "item": "common", "weight": 0.9 }, { "item": "rare", "weight": 0.1 } ] } } } } } } }, "/v1/loot/{key}/open": { "post": { "tags": [ "Economy" ], "summary": "Open a loot box", "description": "Server-rolled (verifiable RNG), idempotent. loot_not_enabled if the box isn't configured; age-gated where required.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Loot box key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "rolled": [ { "item": "rare", "qty": 1 } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "idem": "uuid" } } } } } }, "/v1/energy": { "get": { "tags": [ "Economy" ], "summary": "List energy meters", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meters": [ { "meter": "stamina", "current": 4, "max": 5, "refill_at": "2026-07-10T01:00:00Z" } ] } } } } } } }, "/v1/energy/{meter}": { "get": { "tags": [ "Economy" ], "summary": "Get one energy meter", "parameters": [ { "name": "meter", "in": "path", "required": true, "description": "Meter name.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meter": "stamina", "current": 4, "max": 5 } } } } } } }, "/v1/energy/{meter}/spend": { "post": { "tags": [ "Economy" ], "summary": "Spend energy", "description": "out_of_energy if the balance is insufficient. Idempotent.", "parameters": [ { "name": "meter", "in": "path", "required": true, "description": "Meter name.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meter": "stamina", "current": 3 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "amount": 1, "idem": "uuid" } } } } } }, "/v1/energy/{meter}/refill": { "post": { "tags": [ "Economy" ], "summary": "Refill energy (e.g. with a currency)", "parameters": [ { "name": "meter", "in": "path", "required": true, "description": "Meter name.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meter": "stamina", "current": 5 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "idem": "uuid" } } } } } }, "/v1/teams": { "post": { "tags": [ "Teams" ], "summary": "Create a team", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "tm_1", "name": "Alpha Squad", "tag": "ALPHA" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Alpha Squad", "tag": "ALPHA", "privacy": "open" } } } } }, "get": { "tags": [ "Teams" ], "summary": "List / search teams", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search query.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "teams": [ { "id": "tm_1", "name": "Alpha Squad", "member_count": 4 } ] } } } } } } }, "/v1/teams/mine": { "get": { "tags": [ "Teams" ], "summary": "Get the caller's team", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "team": { "id": "tm_1", "role": "owner" } } } } } } } }, "/v1/teams/leaderboards/{board}": { "get": { "tags": [ "Teams" ], "summary": "Team leaderboard", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entries": [ { "team_id": "tm_1", "score": 5000 } ] } } } } } } }, "/v1/teams/{id}": { "get": { "tags": [ "Teams" ], "summary": "Get a team + members", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "tm_1", "name": "Alpha Squad", "members": [ { "player_id": "p_1", "role": "owner" } ] } } } } } } }, "/v1/teams/{id}/join": { "post": { "tags": [ "Teams" ], "summary": "Join a team (open teams)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "role": "member" } } } } } } }, "/v1/teams/{id}/leave": { "post": { "tags": [ "Teams" ], "summary": "Leave a team", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/members/{pid}/kick": { "post": { "tags": [ "Teams" ], "summary": "Kick a member (admin/owner)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Member player id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/members/{pid}/role": { "post": { "tags": [ "Teams" ], "summary": "Change a member's role", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Member player id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "role": "admin" } } } } } }, "/v1/teams/{id}/transfer": { "post": { "tags": [ "Teams" ], "summary": "Transfer ownership", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "to": "p_2" } } } } } }, "/v1/teams/{id}/disband": { "post": { "tags": [ "Teams" ], "summary": "Disband a team (owner)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/mine/invites": { "get": { "tags": [ "Teams" ], "summary": "List the caller's team invites", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "invites": [ { "id": "ti_1", "team_id": "tm_1" } ] } } } } } } }, "/v1/teams/{id}/invites": { "post": { "tags": [ "Teams" ], "summary": "Invite a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ti_1", "state": "pending" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "player_id": "p_7" } } } } } }, "/v1/teams/invites/{iid}/accept": { "post": { "tags": [ "Teams" ], "summary": "Accept an invite", "parameters": [ { "name": "iid", "in": "path", "required": true, "description": "Invite id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/invites/{iid}/reject": { "post": { "tags": [ "Teams" ], "summary": "Reject an invite", "parameters": [ { "name": "iid", "in": "path", "required": true, "description": "Invite id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/requests": { "post": { "tags": [ "Teams" ], "summary": "Request to join (closed teams)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "tr_1", "state": "pending" } } } } } }, "get": { "tags": [ "Teams" ], "summary": "List join requests (admin)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "requests": [ { "id": "tr_1", "player_id": "p_7" } ] } } } } } } }, "/v1/teams/{id}/requests/{rid}/approve": { "post": { "tags": [ "Teams" ], "summary": "Approve a join request", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "Request id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/requests/{rid}/reject": { "post": { "tags": [ "Teams" ], "summary": "Reject a join request", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "rid", "in": "path", "required": true, "description": "Request id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/members/{pid}/ban": { "post": { "tags": [ "Teams" ], "summary": "Ban a member from the team", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/members/{pid}/unban": { "post": { "tags": [ "Teams" ], "summary": "Unban a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/teams/{id}/bans": { "get": { "tags": [ "Teams" ], "summary": "List team bans", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "bans": [ { "player_id": "p_9" } ] } } } } } } }, "/v1/tournaments": { "get": { "tags": [ "Competition" ], "summary": "List tournaments", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "tournaments": [ { "id": "to_1", "title": "Weekend Cup", "state": "live" } ] } } } } } } }, "/v1/tournaments/mine": { "get": { "tags": [ "Competition" ], "summary": "Tournaments the player has joined", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "tournaments": [] } } } } } } }, "/v1/tournaments/{id}": { "get": { "tags": [ "Competition" ], "summary": "Get a tournament", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tournament id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "to_1", "title": "Weekend Cup", "starts_at": "2026-07-12T00:00:00Z" } } } } } } }, "/v1/tournaments/{id}/standings": { "get": { "tags": [ "Competition" ], "summary": "Get tournament standings", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tournament id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entries": [ { "rank": 1, "player_id": "p_9", "score": 12000 } ] } } } } } } }, "/v1/tournaments/{id}/join": { "post": { "tags": [ "Competition" ], "summary": "Join a tournament", "description": "tournament_not_open if entry is closed; may require an entry fee.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tournament id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/tournaments/{id}/me": { "get": { "tags": [ "Competition" ], "summary": "The player's tournament entry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tournament id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "rank": 42, "score": 8000 } } } } } } }, "/v1/leagues/{key}/join": { "post": { "tags": [ "Competition" ], "summary": "Join a league", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "League key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "division": "bronze", "tier": 3 } } } } } } }, "/v1/leagues/{key}/me": { "get": { "tags": [ "Competition" ], "summary": "The player's league standing", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "League key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "division": "bronze", "tier": 3, "rank": 5 } } } } } } }, "/v1/leagues/{key}/divisions/{tier}/top": { "get": { "tags": [ "Competition" ], "summary": "Top of a league division", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "League key.", "schema": { "type": "string" } }, { "name": "tier", "in": "path", "required": true, "description": "Division tier.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entries": [ { "rank": 1, "player_id": "p_9" } ] } } } } } } }, "/v1/boards/{board}/submit": { "post": { "tags": [ "Competition" ], "summary": "Submit to a keyed board (team / UGC / custom entity)", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Keyed board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "best_score": 5000 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "entity_id": "tm_1", "score": 5000 } } } } } }, "/v1/boards/{board}/top": { "get": { "tags": [ "Competition" ], "summary": "Top entries of a keyed board", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Keyed board key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entries": [ { "rank": 1, "entity_id": "tm_1", "score": 5000 } ] } } } } } } }, "/v1/boards/{board}/entries/{entity_id}": { "get": { "tags": [ "Competition" ], "summary": "One entity's keyed-board entry", "parameters": [ { "name": "board", "in": "path", "required": true, "description": "Keyed board key.", "schema": { "type": "string" } }, { "name": "entity_id", "in": "path", "required": true, "description": "Entity id (team/UGC/…).", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entity_id": "tm_1", "score": 5000, "rank": 1 } } } } } } }, "/v1/quests": { "get": { "tags": [ "Progression" ], "summary": "List quests + the caller's progress", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "quests": [ { "key": "daily_login", "progress": 1, "target": 1, "claimable": true } ] } } } } } } }, "/v1/quests/{key}/claim": { "post": { "tags": [ "Progression" ], "summary": "Claim a completed quest's reward", "description": "quest_not_complete if objectives aren't met; the reward is escrowed into the inbox.", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Quest key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "claimed": true } } } } } } }, "/v1/battle-pass/{season}": { "get": { "tags": [ "Progression" ], "summary": "Get battle-pass tiers + the caller's progress", "parameters": [ { "name": "season", "in": "path", "required": true, "description": "Season key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "season": "s1", "tier": 4, "xp": 1200, "premium": false } } } } } } }, "/v1/battle-pass/{season}/claim": { "post": { "tags": [ "Progression" ], "summary": "Claim a battle-pass tier reward", "description": "tier_not_earned if not reached; premium_required for a premium lane without the pass.", "parameters": [ { "name": "season", "in": "path", "required": true, "description": "Season key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "claimed": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "tier": 4, "lane": "free" } } } } } }, "/v1/progression": { "get": { "tags": [ "Progression" ], "summary": "Get XP / level curve progress", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "level": 7, "xp": 3400, "next_level_xp": 4000 } } } } } } }, "/v1/storage/{collection}": { "get": { "tags": [ "Storage" ], "summary": "List keys in the player's collection", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "keys": [ "settings", "deck" ] } } } } } } }, "/v1/storage/{collection}/{key}": { "get": { "tags": [ "Storage" ], "summary": "Read a collection entry", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "settings", "data": { "sfx": true }, "version": 2 } } } } } }, "put": { "tags": [ "Storage" ], "summary": "Write a collection entry", "description": "Optional If-Match for OCC (storage_conflict on a stale version).", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "settings", "version": 3 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": { "sfx": false } } } } } }, "delete": { "tags": [ "Storage" ], "summary": "Delete a collection entry", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/storage/{collection}/{key}/mutate": { "post": { "tags": [ "Storage" ], "summary": "Atomic server-side mutation of an entry", "description": "Apply structured ops (e.g. list append, counter add) server-side to avoid read-modify-write races.", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "deck", "version": 5 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "ops": [ { "op": "append", "path": "deck", "value": "card_9" } ] } } } } } }, "/v1/storage/shared/{collection}/{key}": { "get": { "tags": [ "Storage" ], "summary": "Read a shared (game-wide) entry", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "motd", "data": { "text": "Welcome!" } } } } } } }, "put": { "tags": [ "Storage" ], "summary": "Write a shared entry (per the collection's write policy)", "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "motd", "version": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": { "text": "Welcome!" } } } } } } }, "/v1/storage/team/{teamId}/{collection}": { "get": { "tags": [ "Storage" ], "summary": "List a team collection's keys (members only)", "parameters": [ { "name": "teamId", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "keys": [ "roster" ] } } } } } } }, "/v1/storage/team/{teamId}/{collection}/{key}": { "get": { "tags": [ "Storage" ], "summary": "Read a team entry", "parameters": [ { "name": "teamId", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "roster", "data": {} } } } } } }, "put": { "tags": [ "Storage" ], "summary": "Write a team entry (members only)", "parameters": [ { "name": "teamId", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "roster", "version": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": {} } } } } }, "delete": { "tags": [ "Storage" ], "summary": "Delete a team entry", "parameters": [ { "name": "teamId", "in": "path", "required": true, "description": "Team id.", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/ugc": { "get": { "tags": [ "UGC" ], "summary": "Browse published content", "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "e.g. top, new.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "id": "ug_1", "title": "My Level", "plays": 42, "rating": 4.5 } ] } } } } } }, "post": { "tags": [ "UGC" ], "summary": "Create a draft", "description": "Title/content are moderated. Publish it with POST /v1/ugc/:id/submit.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ug_1", "status": "draft" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "My Level", "data": { "grid": [] } } } } } } }, "/v1/ugc/mine": { "get": { "tags": [ "UGC" ], "summary": "List the caller's content", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "id": "ug_1", "title": "My Level", "status": "published" } ] } } } } } } }, "/v1/ugc/{id}": { "get": { "tags": [ "UGC" ], "summary": "Get a content item", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ug_1", "title": "My Level", "data": {}, "author": "p_1" } } } } } }, "patch": { "tags": [ "UGC" ], "summary": "Update a draft", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ug_1" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "My Level v2" } } } } }, "delete": { "tags": [ "UGC" ], "summary": "Delete content", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/ugc/{id}/submit": { "post": { "tags": [ "UGC" ], "summary": "Publish a draft", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ug_1", "status": "published" } } } } } } }, "/v1/ugc/{id}/play": { "post": { "tags": [ "UGC" ], "summary": "Record a play", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/ugc/{id}/lineage": { "get": { "tags": [ "UGC" ], "summary": "Get remix lineage (attribution)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ancestors": [ { "id": "ug_0", "author": "p_0" } ] } } } } } } }, "/v1/ugc/{id}/remix": { "post": { "tags": [ "UGC" ], "summary": "Remix content (forks with attribution)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Source content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "ug_2", "remixed_from": "ug_1" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "title": "My Remix" } } } } } }, "/v1/ugc/{id}/rate": { "post": { "tags": [ "UGC" ], "summary": "Rate content", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "rating": 4.6 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "rating": 5 } } } } } }, "/v1/ugc/{id}/like": { "post": { "tags": [ "UGC" ], "summary": "Like content", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "likes": 13 } } } } } }, "delete": { "tags": [ "UGC" ], "summary": "Unlike content", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Content id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "likes": 12 } } } } } } }, "/v1/async": { "post": { "tags": [ "Async" ], "summary": "Create a turn-based match", "description": "No realtime/Durable Object needed — turns are submitted over HTTP with server-enforced turn order + OCC.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "match": { "id": "am_1", "state": {}, "turn": "p_1a2b3c" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "chess", "opponents": [ "p_9" ] } } } } } }, "/v1/async/mine": { "get": { "tags": [ "Async" ], "summary": "List the player's active matches", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "matches": [ { "id": "am_1", "type": "chess", "turn": "p_9" } ] } } } } } } }, "/v1/async/{id}": { "get": { "tags": [ "Async" ], "summary": "Get a match (participants only)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "match": { "id": "am_1", "state": {}, "turn_number": 4 } } } } } } } }, "/v1/async/{id}/turn": { "post": { "tags": [ "Async" ], "summary": "Submit a turn", "description": "Rejected with not_your_turn out of order, or async_conflict on a stale version (send the version you read).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "match": { "id": "am_1", "turn_number": 5 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "state": { "board": [] }, "version": 4, "end": false } } } } } }, "/v1/async/{id}/forfeit": { "post": { "tags": [ "Async" ], "summary": "Forfeit a match", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Match id.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "match": { "id": "am_1", "status": "complete", "winner": "p_9" } } } } } } } }, "/v1/config": { "get": { "tags": [ "LiveOps" ], "summary": "Get the game's published config blob", "description": "The developer's key→value tuning blob (server-controlled, no client deploy to change).", "security": [ { "TriggairKey": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "config": { "spawn_rate": 1.5, "event_banner": "summer" }, "version": 12 } } } } } } }, "/v1/flags": { "get": { "tags": [ "LiveOps" ], "summary": "Get feature flags resolved for the player", "description": "Each flag resolves per the player's segments, with a break-glass kill switch honoured.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "flags": { "new_hud": true, "checkout_v2": "variant_b" } } } } } } } }, "/v1/flags/{key}": { "get": { "tags": [ "LiveOps" ], "summary": "Get one resolved flag value", "parameters": [ { "name": "key", "in": "path", "required": true, "description": "Flag key.", "schema": { "type": "string" } } ], "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "new_hud", "value": true } } } } } } }, "/v1/liveops/events/live": { "get": { "tags": [ "LiveOps" ], "summary": "Get currently-live events", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "events": [ { "key": "summer_fest", "ends_at": "2026-08-01T00:00:00Z" } ] } } } } } } }, "/v1/players/me/segments": { "get": { "tags": [ "LiveOps" ], "summary": "Get the player's segment memberships", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "segments": [ "whales", "new_players" ] } } } } } } }, "/v1/events": { "post": { "tags": [ "Analytics" ], "summary": "Ingest analytics events", "description": "Usually called via the SDK's durable outbox (tg.track), which coalesces + retries. Counts only — no per-player PII.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "accepted": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "events": [ { "name": "level_complete", "count": 1 } ] } } } } } }, "/v1/dev/games": { "post": { "tags": [ "Dev · Games" ], "summary": "Create a game", "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "g_1", "name": "Neon Drift", "tier": "shared", "env": "prod" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Neon Drift" } } } } }, "get": { "tags": [ "Dev · Games" ], "summary": "List your games", "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "games": [ { "id": "g_1", "name": "Neon Drift", "status": "active" } ] } } } } } } }, "/v1/dev/games/{id}": { "get": { "tags": [ "Dev · Games" ], "summary": "Get a game", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "g_1", "name": "Neon Drift", "allowed_origins": [ "https://mygame.com" ] } } } } } }, "patch": { "tags": [ "Dev · Games" ], "summary": "Update a game (name, CORS allowlist, pause)", "description": "Set allowed_origins (CORS) — an empty list is open to any origin. status paused takes the game offline.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "g_1", "allowed_origins": [ "https://mygame.com" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "allowed_origins": [ "https://mygame.com" ], "status": "active" } } } } }, "delete": { "tags": [ "Dev · Games" ], "summary": "Delete a game (and its keys/data)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/keys": { "post": { "tags": [ "Dev · Keys" ], "summary": "Issue an API key", "description": "The full secret is returned ONCE. tg_pk_ (publishable) is safe in clients; tg_sk_ (secret) is server-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "key_1", "prefix": "tg_pk_ab12", "key": "tg_pk_ab12…full-shown-once", "note": "Store this now — it won't be shown again." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "publishable" } } } } }, "get": { "tags": [ "Dev · Keys" ], "summary": "List key metadata (never the secret)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "keys": [ { "id": "key_1", "kind": "publishable", "prefix": "tg_pk_ab12", "last_used_at": "2026-07-01T00:00:00Z", "revoked_at": null } ] } } } } } } }, "/v1/dev/games/{id}/keys/{keyId}/rotate": { "post": { "tags": [ "Dev · Keys" ], "summary": "Rotate a key (revoke + mint a replacement)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "description": "Key id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "key_2", "key": "tg_pk_cd34…full-shown-once" } } } } } } }, "/v1/dev/games/{id}/keys/{keyId}": { "delete": { "tags": [ "Dev · Keys" ], "summary": "Revoke a key", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "description": "Key id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/leaderboards": { "get": { "tags": [ "Dev · Leaderboards" ], "summary": "List leaderboard definitions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "boards": [ { "board": "high_scores", "aggregation": "best", "period": "all_time" } ] } } } } } } }, "/v1/dev/games/{id}/leaderboards/{board}": { "put": { "tags": [ "Dev · Leaderboards" ], "summary": "Create / update a leaderboard", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "board": "high_scores" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "aggregation": "best", "period": "weekly", "higher_is_better": true } } } } }, "delete": { "tags": [ "Dev · Leaderboards" ], "summary": "Delete a leaderboard (scores cascade)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "board", "in": "path", "required": true, "description": "Board key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/boards": { "post": { "tags": [ "Dev · Leaderboards" ], "summary": "Create a keyed board (team/UGC/custom entity)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "board_key": "team_wars" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "board_key": "team_wars", "entity_type": "team", "aggregation": "sum", "period": "weekly" } } } } }, "get": { "tags": [ "Dev · Leaderboards" ], "summary": "List keyed boards", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "boards": [ { "board_key": "team_wars", "entity_type": "team" } ] } } } } } } }, "/v1/dev/games/{id}/boards/{board}": { "delete": { "tags": [ "Dev · Leaderboards" ], "summary": "Delete a keyed board", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "board", "in": "path", "required": true, "description": "Keyed board key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/economy/currencies": { "get": { "tags": [ "Dev · Economy" ], "summary": "List currencies", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "currencies": [ { "code": "gold", "name": "Gold" } ] } } } } } }, "post": { "tags": [ "Dev · Economy" ], "summary": "Create / upsert a currency", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "code": "gold" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "gold", "name": "Gold", "max": 999999 } } } } } }, "/v1/dev/games/{id}/economy/items": { "post": { "tags": [ "Dev · Economy" ], "summary": "Create / upsert an item", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "sword" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "sword", "name": "Sword", "stackable": false } } } } }, "get": { "tags": [ "Dev · Economy" ], "summary": "List items", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "key": "sword" } ] } } } } } } }, "/v1/dev/games/{id}/economy/stores": { "post": { "tags": [ "Dev · Economy" ], "summary": "Create / upsert a store", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "main_store" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "main_store", "listings": [ { "id": "l_1", "item": "sword", "price": { "gold": 100 } } ] } } } } }, "get": { "tags": [ "Dev · Economy" ], "summary": "List stores", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "stores": [ { "key": "main_store" } ] } } } } } } }, "/v1/dev/games/{id}/economy/loot": { "post": { "tags": [ "Dev · Economy" ], "summary": "Create / upsert a loot box (with odds)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "bronze_box" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "bronze_box", "drops": [ { "item": "common", "weight": 0.9 }, { "item": "rare", "weight": 0.1 } ] } } } } }, "get": { "tags": [ "Dev · Economy" ], "summary": "List loot boxes", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "loot": [ { "key": "bronze_box" } ] } } } } } } }, "/v1/dev/games/{id}/economy/energy": { "post": { "tags": [ "Dev · Economy" ], "summary": "Create / upsert an energy meter", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meter": "stamina" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "meter": "stamina", "max": 5, "refill_seconds": 600 } } } } }, "get": { "tags": [ "Dev · Economy" ], "summary": "List energy meters", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "meters": [ { "meter": "stamina", "max": 5 } ] } } } } } } }, "/v1/dev/games/{id}/economy/grant": { "post": { "tags": [ "Dev · Economy" ], "summary": "Grant currency/items to a player (support tool)", "description": "Escrows the grant into the player's inbox (the one hardened grant path). Idempotent.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "player_id": "p_9", "currency": [ { "code": "gold", "amount": 500 } ], "idem": "uuid" } } } } } }, "/v1/dev/games/{id}/economy/ledger": { "get": { "tags": [ "Dev · Economy" ], "summary": "Read the currency ledger", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "lines": [ { "player_id": "p_9", "currency": "gold", "delta": 500 } ] } } } } } } }, "/v1/dev/games/{id}/economy/players/{pid}/wallet": { "get": { "tags": [ "Dev · Economy" ], "summary": "Inspect a player's wallet", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "balances": [ { "currency": "gold", "amount": 500 } ] } } } } } } }, "/v1/dev/games/{id}/economy/players/{pid}/inventory": { "get": { "tags": [ "Dev · Economy" ], "summary": "Inspect a player's inventory", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "items": [ { "item": "sword", "qty": 1 } ] } } } } } } }, "/v1/dev/games/{id}/achievements": { "get": { "tags": [ "Dev · Progression" ], "summary": "List achievement definitions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "achievements": [ { "key": "first_win", "target": 1 } ] } } } } } } }, "/v1/dev/games/{id}/achievements/{key}": { "delete": { "tags": [ "Dev · Progression" ], "summary": "Delete an achievement", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Achievement key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } }, "put": { "tags": [ "Dev · Progression" ], "summary": "Create / update an achievement", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Achievement key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "first_win" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "First Win", "target": 1, "reward": { "stats": [ { "key": "gold", "amount": 50 } ] }, "secret": false } } } } } }, "/v1/dev/games/{id}/daily": { "get": { "tags": [ "Dev · Progression" ], "summary": "Get the daily-reward config", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "cycle_length": 7, "enabled": true } } } } } }, "put": { "tags": [ "Dev · Progression" ], "summary": "Set the daily-reward config", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "enabled": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "cycle_length": 7, "rewards": [ { "day": 1, "stats": [ { "key": "gold", "amount": 50 } ] } ] } } } } }, "delete": { "tags": [ "Dev · Progression" ], "summary": "Disable daily rewards", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/quests": { "post": { "tags": [ "Dev · Progression" ], "summary": "Create / upsert a quest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "win_3" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "win_3", "period": "weekly", "objectives": [ { "stat": "wins", "target": 3 } ] } } } } }, "get": { "tags": [ "Dev · Progression" ], "summary": "List quests", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "quests": [ { "key": "win_3" } ] } } } } } } }, "/v1/dev/games/{id}/battle-pass": { "post": { "tags": [ "Dev · Progression" ], "summary": "Create / upsert a battle-pass season", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "season": "s1" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "season": "s1", "starts_at": "2026-07-01T00:00:00Z", "tiers": [] } } } } }, "get": { "tags": [ "Dev · Progression" ], "summary": "List battle-pass seasons", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "seasons": [ { "season": "s1" } ] } } } } } } }, "/v1/dev/games/{id}/progression": { "post": { "tags": [ "Dev · Progression" ], "summary": "Set the XP / level curve", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "max_level": 50 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "xp_key": "xp", "base": 100, "growth": 1.5, "max_level": 50 } } } } }, "get": { "tags": [ "Dev · Progression" ], "summary": "Get the level curve", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "base": 100, "growth": 1.5, "max_level": 50 } } } } } } }, "/v1/dev/games/{id}/tournaments": { "post": { "tags": [ "Dev · Competition" ], "summary": "Schedule a tournament", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "to_1" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "weekend_cup", "board": "high_scores", "starts_at": "2026-07-12T00:00:00Z", "ends_at": "2026-07-14T00:00:00Z", "reward_table": [] } } } } }, "get": { "tags": [ "Dev · Competition" ], "summary": "List tournaments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "tournaments": [ { "id": "to_1", "state": "live" } ] } } } } } } }, "/v1/dev/games/{id}/tournaments/{tid}/finalize": { "post": { "tags": [ "Dev · Competition" ], "summary": "Force-finalize a tournament (pays prizes)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "tid", "in": "path", "required": true, "description": "Tournament id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "finalized": true } } } } } } }, "/v1/dev/games/{id}/leagues": { "post": { "tags": [ "Dev · Competition" ], "summary": "Create / upsert a league (tiered divisions)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "ranked" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "ranked", "divisions": [ "bronze", "silver", "gold" ] } } } } }, "get": { "tags": [ "Dev · Competition" ], "summary": "List leagues", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "leagues": [ { "key": "ranked" } ] } } } } } } }, "/v1/dev/games/{id}/leagues/{key}/advance": { "post": { "tags": [ "Dev · Competition" ], "summary": "Advance a league season (promotion/relegation)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "League key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "advanced": true, "season": 2 } } } } } } }, "/v1/dev/games/{id}/config": { "get": { "tags": [ "Dev · LiveOps" ], "summary": "Get the config blob", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "config": {}, "version": 12 } } } } } }, "put": { "tags": [ "Dev · LiveOps" ], "summary": "Replace the config blob", "description": "Whole-blob replace (≤64 KB); bumps config_version. Served to clients at GET /v1/config.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "version": 13 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "config": { "spawn_rate": 1.5 } } } } } } }, "/v1/dev/games/{id}/events": { "get": { "tags": [ "Dev · LiveOps" ], "summary": "Read remote-event counters", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "events": [ { "name": "level_complete", "count": 1240 } ] } } } } } } }, "/v1/dev/games/{id}/liveops/flags": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Create / upsert a feature flag", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "new_hud", "state": "on" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "new_hud", "type": "boolean", "default_value": true, "safe_value": false } } } } }, "get": { "tags": [ "Dev · LiveOps" ], "summary": "List feature flags", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "flags": [ { "key": "new_hud", "state": "on" } ] } } } } } } }, "/v1/dev/games/{id}/liveops/flags/{key}/kill": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Break-glass: kill / restore a flag", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Flag key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "new_hud", "state": "killed" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "on": true } } } } } }, "/v1/dev/games/{id}/liveops/segments": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Create / upsert a targeting segment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "sg_1", "key": "whales" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "whales", "definition": { "all": [ { "stat": "coins", "op": ">=", "value": 1000 } ] } } } } } }, "get": { "tags": [ "Dev · LiveOps" ], "summary": "List segments", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "segments": [ { "id": "sg_1", "key": "whales", "approx_size": 1200 } ] } } } } } } }, "/v1/dev/games/{id}/liveops/segments/{sid}": { "get": { "tags": [ "Dev · LiveOps" ], "summary": "Get a segment's rule definition", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Segment id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "definition": { "all": [ { "stat": "coins", "op": ">=", "value": 1000 } ] } } } } } } } }, "/v1/dev/games/{id}/liveops/segments/{sid}/materialize": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Materialize a segment's membership", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "sid", "in": "path", "required": true, "description": "Segment id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "size": 1200 } } } } } } }, "/v1/dev/games/{id}/liveops/code-campaigns": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Create a promo-code campaign", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "launch" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "launch", "reward": { "stats": [ { "key": "gold", "amount": 100 } ] }, "max_redemptions": 1000 } } } } }, "get": { "tags": [ "Dev · LiveOps" ], "summary": "List code campaigns", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "campaigns": [ { "key": "launch", "redeemed": 42 } ] } } } } } } }, "/v1/dev/games/{id}/liveops/code-campaigns/{cid}/redemptions": { "get": { "tags": [ "Dev · LiveOps" ], "summary": "List a campaign's redemptions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "cid", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "redemptions": [ { "player_id": "p_9", "at": "2026-07-01T00:00:00Z" } ] } } } } } } }, "/v1/dev/games/{id}/liveops/events": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Create / upsert a live event", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "summer_fest" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "summer_fest", "starts_at": "2026-07-01T00:00:00Z", "ends_at": "2026-08-01T00:00:00Z" } } } } }, "get": { "tags": [ "Dev · LiveOps" ], "summary": "List live events", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "events": [ { "key": "summer_fest" } ] } } } } } } }, "/v1/dev/games/{id}/moderation": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Set the moderation policy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "custom_terms": [ "voldemort" ], "allowlist": [ "scunthorpe" ] } } } } }, "get": { "tags": [ "Dev · Moderation" ], "summary": "Get the moderation policy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "customTerms": [ "voldemort" ], "allowlist": [ "scunthorpe" ] } } } } } } }, "/v1/dev/games/{id}/moderation/check": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Dry-run moderate a string", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "verdict": "allow" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "surface": "chat", "text": "test a string" } } } } } }, "/v1/dev/games/{id}/moderation/reports": { "get": { "tags": [ "Dev · Moderation" ], "summary": "List content reports (review queue)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "reports": [ { "id": "cr_1", "state": "open", "target_type": "player" } ] } } } } } } }, "/v1/dev/games/{id}/moderation/reports/{rp}": { "get": { "tags": [ "Dev · Moderation" ], "summary": "Get a report", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "rp", "in": "path", "required": true, "description": "Report id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "cr_1", "state": "open" } } } } } } }, "/v1/dev/games/{id}/moderation/reports/{rp}/assign": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Assign / resolve a report", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "rp", "in": "path", "required": true, "description": "Report id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "state": "actioned" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "resolution": "warn" } } } } } }, "/v1/dev/games/{id}/moderation/audit": { "get": { "tags": [ "Dev · Moderation" ], "summary": "Read the moderation audit feed", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "actions": [ { "action": "ban", "actor": "p_1", "target_id": "p_9" } ] } } } } } } }, "/v1/dev/games/{id}/moderation/players/{pid}": { "get": { "tags": [ "Dev · Moderation" ], "summary": "Get a player's moderation view", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_9", "reports_against": [], "actions": [] } } } } } } }, "/v1/dev/games/{id}/moderation/players/{pid}/ban": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Ban a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "banned": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "permanent", "scope": "account", "reason": "cheating" } } } } } }, "/v1/dev/games/{id}/moderation/players/{pid}/unban": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Unban a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "lifted": true } } } } } } }, "/v1/dev/games/{id}/moderation/players/{pid}/unmute": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Unmute a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "lifted": true } } } } } } }, "/v1/dev/games/{id}/moderation/appeals": { "get": { "tags": [ "Dev · Moderation" ], "summary": "List ban appeals; decide grants/denies", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "appeals": [ { "id": "ap_1", "state": "pending" } ] } } } } } } }, "/v1/dev/games/{id}/compliance": { "post": { "tags": [ "Dev · Compliance" ], "summary": "Set the age-gate / COPPA policy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "coppa_mode": false, "default_jurisdiction": "US", "gates": { "open_chat": "13_15", "lootbox": "adult" } } } } } }, "get": { "tags": [ "Dev · Compliance" ], "summary": "Get the compliance policy", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "coppa_mode": false, "gates": {} } } } } } } }, "/v1/dev/games/{id}/compliance/players/{pid}": { "get": { "tags": [ "Dev · Compliance" ], "summary": "Inspect a player's compliance state", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "bracket": "13_15", "consent_state": "granted" } } } } } } }, "/v1/dev/games/{id}/analytics/metrics": { "get": { "tags": [ "Dev · Analytics" ], "summary": "DAU/MAU/new-players/events by day", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "days": [ { "day": "2026-07-01", "dau": 1200, "mau": 8000, "new_players": 90 } ] } } } } } } }, "/v1/dev/games/{id}/analytics/retention": { "get": { "tags": [ "Dev · Analytics" ], "summary": "Cohort retention grid", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "cohorts": [ { "day": "2026-07-01", "d1": 0.42, "d7": 0.18 } ] } } } } } } }, "/v1/dev/games/{id}/analytics/sessions": { "get": { "tags": [ "Dev · Analytics" ], "summary": "Session counts + lengths", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "days": [ { "day": "2026-07-01", "sessions": 3400, "avg_ms": 480000 } ] } } } } } } }, "/v1/dev/games/{id}/analytics/economy": { "get": { "tags": [ "Dev · Analytics" ], "summary": "Per-currency sources/sinks/net (economy health)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "currencies": [ { "currency": "gold", "sources": 150, "sinks": 30, "net": 120 } ] } } } } } } }, "/v1/dev/games/{id}/analytics/funnels": { "post": { "tags": [ "Dev · Analytics" ], "summary": "Define a funnel (ordered event list)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "onboarding" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "onboarding", "steps": [ "install", "tutorial", "first_purchase" ] } } } } }, "get": { "tags": [ "Dev · Analytics" ], "summary": "List funnels + their results", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "funnels": [ { "key": "onboarding", "steps": [ { "event": "install", "reached": 1000 } ] } ] } } } } } } }, "/v1/dev/games/{id}/analytics/funnels/{key}": { "delete": { "tags": [ "Dev · Analytics" ], "summary": "Delete a funnel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Funnel key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/dev/games/{id}/analytics/crashes": { "get": { "tags": [ "Dev · Analytics" ], "summary": "List crash groups (open-first)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "groups": [ { "id": "cg_1", "title": "TypeError", "occurrences": 42, "status": "open" } ] } } } } } } }, "/v1/dev/games/{id}/analytics/rollup": { "post": { "tags": [ "Dev · Analytics" ], "summary": "Trigger an analytics rollup (manual)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } } } }, "/v1/dev/games/{id}/storage-collections": { "post": { "tags": [ "Dev · Storage" ], "summary": "Create / upsert a storage collection", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "decks" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "key": "decks", "scope": "player", "read": "owner", "write": "owner", "max_bytes": 65536 } } } } }, "get": { "tags": [ "Dev · Storage" ], "summary": "List storage collections", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "collections": [ { "key": "decks", "scope": "player" } ] } } } } } } }, "/v1/dev/games/{id}/inbox": { "post": { "tags": [ "Dev · Inbox" ], "summary": "Send an inbox message / announcement (optionally with a reward)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "sent": 8000 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "audience": "all", "kind": "announcement", "body": { "text": "Season 2 is live!" }, "rewards": { "stats": [ { "key": "gold", "amount": 100 } ] } } } } } } }, "/v1/dev/games/{id}/usage": { "get": { "tags": [ "Dev · Usage" ], "summary": "Get this month's usage vs quota", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "month": "2026-07", "players": 8000, "ops": { "saves": 320, "leaderboards": 145 } } } } } } } }, "/v1/dev/games/{id}/verify": { "post": { "tags": [ "Dev · Verify" ], "summary": "Run a server-side integration self-test", "description": "Live-probes player → save → leaderboard → CORS in-process and reports pass/fail per service with fixes.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "services": [ { "name": "saves", "status": "pass" } ] } } } } } } }, "/v1/codes/redeem": { "post": { "tags": [ "Economy" ], "summary": "Redeem a promo code", "description": "Grants the campaign reward into the inbox. code_invalid / code_expired / code_already_redeemed / code_campaign_exhausted on failure.", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "granted": { "stats": [ { "key": "gold", "amount": 100 } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "code": "LAUNCH2026" } } } } } }, "/v1/gifts": { "post": { "tags": [ "Economy" ], "summary": "Send a gift to another player", "description": "Delivers an item/currency gift into the recipient's inbox (subject to gifting limits).", "security": [ { "TriggairKey": [], "PlayerToken": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "to": "p_9", "item": "sword", "qty": 1, "idem": "uuid" } } } } } }, "/v1/dev/me": { "get": { "tags": [ "Dev · Games" ], "summary": "Get the developer account", "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "d_1", "email": "dev@studio.com" } } } } } } }, "/v1/dev/games/{id}/battle-pass/{season}/premium": { "post": { "tags": [ "Dev · Progression" ], "summary": "Configure a season's premium track", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "season", "in": "path", "required": true, "description": "Season key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "price": { "gold": 1000 } } } } } } }, "/v1/dev/games/{id}/liveops/code-campaigns/{cid}/generate": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Generate promo codes for a campaign", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "cid", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "codes": [ "ABCD-1234" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "count": 100 } } } } } }, "/v1/dev/games/{id}/liveops/segments/preview": { "post": { "tags": [ "Dev · LiveOps" ], "summary": "Preview a segment's size (dry-run)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "count": 1200 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "definition": { "all": [ { "stat": "coins", "op": ">=", "value": 1000 } ] } } } } } } }, "/v1/dev/games/{id}/moderation/players/{pid}/mute": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Mute / restrict a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "effect": "mute", "expires_at": "2026-07-15T00:00:00Z" } } } } } }, "/v1/dev/games/{id}/moderation/reports/{rp}/resolve": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Resolve a report (warn / dismiss / duplicate)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "rp", "in": "path", "required": true, "description": "Report id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "state": "actioned" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "resolution": "warn" } } } } } }, "/v1/dev/games/{id}/moderation/appeals/{ap}/decide": { "post": { "tags": [ "Dev · Moderation" ], "summary": "Decide a ban appeal (grant lifts the ban)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "ap", "in": "path", "required": true, "description": "Appeal id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "appeal": { "id": "ap_1", "state": "granted" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "grant": true, "note": "first offense" } } } } } }, "/v1/dev/games/{id}/analytics/crashes/{group}/daily": { "get": { "tags": [ "Dev · Analytics" ], "summary": "A crash group's daily rate + crash-free %", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "description": "Crash group id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "days": [ { "day": "2026-07-01", "occurrences": 12, "crash_free": 0.98 } ] } } } } } } }, "/v1/dev/games/{id}/analytics/crashes/{group}/status": { "post": { "tags": [ "Dev · Analytics" ], "summary": "Set a crash group's status (open/resolved/ignored)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "group", "in": "path", "required": true, "description": "Crash group id.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "status": "resolved" } } } } } }, "/v1/dev/games/{id}/analytics/funnels/{key}/results": { "get": { "tags": [ "Dev · Analytics" ], "summary": "A funnel's per-step results", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Funnel key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "steps": [ { "event": "install", "reached": 1000, "conversion": 1 }, { "event": "tutorial", "reached": 660, "conversion": 0.66 } ] } } } } } } }, "/v1/dev/games/{id}/storage/shared/{collection}/{key}": { "put": { "tags": [ "Dev · Storage" ], "summary": "Write a shared storage entry (developer)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "description": "Collection key.", "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "description": "Entry key.", "schema": { "type": "string" } } ], "security": [ { "DevSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "key": "motd", "version": 2 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "data": { "motd": "Season 2 is live!" } } } } } } }, "/v1/admin/me": { "get": { "tags": [ "Admin" ], "summary": "Get the signed-in operator", "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "op_1", "email": "ops@triggair.com", "role": "owner" } } } } } } }, "/v1/admin/developers": { "get": { "tags": [ "Admin" ], "summary": "List developers (cross-tenant)", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Offset.", "schema": { "type": "integer" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "developers": [ { "id": "d_1", "email": "dev@x.com", "plan": "indie", "games": 2, "mau": 8000 } ] } } } } } } }, "/v1/admin/developers/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a developer (subscription + games)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Developer id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "developer": { "id": "d_1", "email": "dev@x.com", "status": "active" }, "subscription": { "plan": "indie" }, "games": [] } } } } } } }, "/v1/admin/games": { "get": { "tags": [ "Admin" ], "summary": "List games (cross-tenant)", "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "games": [ { "id": "g_1", "name": "Neon Drift", "developer_id": "d_1", "players": 42 } ] } } } } } } }, "/v1/admin/games/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a game (metadata + key metadata + counts)", "description": "Key metadata only — never a hash/secret. Every operator read is audited.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "game": { "id": "g_1", "tier": "shared", "status": "active" }, "keys": [ { "prefix": "tg_pk_ab12", "kind": "publishable" } ], "players": 42, "ops": 525 } } } } } } }, "/v1/admin/audit": { "get": { "tags": [ "Admin" ], "summary": "Read the operator audit trail", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "entries": [ { "action": "developer.read", "actor_email": "ops@triggair.com", "created_at": "2026-07-01T00:00:00Z" } ] } } } } } } }, "/v1/admin/games/{id}/suspend": { "post": { "tags": [ "Admin" ], "summary": "Suspend a game (takes it dark at the edge)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "g_1", "status": "suspended" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "ToS abuse" } } } } } }, "/v1/admin/games/{id}/unsuspend": { "post": { "tags": [ "Admin" ], "summary": "Unsuspend a game", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "g_1", "status": "active" } } } } } } }, "/v1/admin/developers/{id}/suspend": { "post": { "tags": [ "Admin" ], "summary": "Suspend a developer (cascades to all their games)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Developer id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "d_1", "status": "suspended" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "reason": "account abuse" } } } } } }, "/v1/admin/developers/{id}/unsuspend": { "post": { "tags": [ "Admin" ], "summary": "Unsuspend a developer", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Developer id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "id": "d_1", "status": "active" } } } } } } }, "/v1/admin/games/{id}/keys/{keyId}/revoke": { "post": { "tags": [ "Admin" ], "summary": "Revoke a leaked key (incident lever)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "description": "Key id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "204 No Content.", "content": { "application/json": { "example": null } } } } } }, "/v1/admin/games/{id}/players/{pid}/moderation": { "get": { "tags": [ "Admin" ], "summary": "Cross-tenant player moderation view", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "player_id": "p_9", "reports_against": [], "actions": [] } } } } } } }, "/v1/admin/games/{id}/players/{pid}/ban": { "post": { "tags": [ "Admin" ], "summary": "Ban a player (cross-tenant)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "banned": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "kind": "permanent", "reason": "cheating" } } } } } }, "/v1/admin/games/{id}/players/{pid}/unban": { "post": { "tags": [ "Admin" ], "summary": "Unban a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "lifted": true } } } } } } }, "/v1/admin/games/{id}/players/{pid}/mute": { "post": { "tags": [ "Admin" ], "summary": "Mute a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "effect": "mute" } } } } } }, "/v1/admin/games/{id}/players/{pid}/unmute": { "post": { "tags": [ "Admin" ], "summary": "Unmute a player", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "description": "Player id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "ok": true, "lifted": true } } } } } } }, "/v1/admin/games/{id}/moderation/appeals": { "get": { "tags": [ "Admin" ], "summary": "List ban appeals (cross-tenant)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "appeals": [ { "id": "ap_1", "state": "pending" } ] } } } } } } }, "/v1/admin/games/{id}/moderation/appeals/{ap}/decide": { "post": { "tags": [ "Admin" ], "summary": "Decide a ban appeal", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id.", "schema": { "type": "string" } }, { "name": "ap", "in": "path", "required": true, "description": "Appeal id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "appeal": { "id": "ap_1", "state": "granted" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "grant": true } } } } } }, "/v1/admin/developers/{id}/impersonate": { "post": { "tags": [ "Admin" ], "summary": "Mint a developer impersonation token", "description": "Returns a session-lived token to act AS the developer (full read/write) on /v1/dev/*, for support. Audited.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Developer id.", "schema": { "type": "string" } } ], "security": [ { "OperatorSession": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "token": "eyJ…", "developer": { "id": "d_1", "email": "dev@x.com" }, "expires_at": "2026-07-11T00:00:00Z" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Docs & meta" ], "summary": "This OpenAPI 3.1 definition", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "openapi": "3.1.0" } } } } } } }, "/llms.txt": { "get": { "tags": [ "Docs & meta" ], "summary": "Agent index (concise integration guide)", "security": [], "responses": { "200": { "description": "Success." } } } }, "/llms-full.txt": { "get": { "tags": [ "Docs & meta" ], "summary": "Full agent integration guide", "security": [], "responses": { "200": { "description": "Success." } } } }, "/dropin": { "get": { "tags": [ "Docs & meta" ], "summary": "Copy-paste Drop-In prompt", "security": [], "responses": { "200": { "description": "Success." } } } }, "/docs/errors/{code}": { "get": { "tags": [ "Docs & meta" ], "summary": "Per-error-code fix doc", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Error code.", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Success." } } } }, "/status": { "get": { "tags": [ "Docs & meta" ], "summary": "Liveness + resolved game/env echo", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "status": "ok", "game_id": null, "env": "prod" } } } } } } }, "/healthz": { "get": { "tags": [ "Docs & meta" ], "summary": "Health check", "security": [], "responses": { "200": { "description": "Success." } } } }, "/time": { "get": { "tags": [ "Docs & meta" ], "summary": "Authoritative server time (for client clocks)", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "example": { "now": "2026-07-10T00:00:00Z", "epoch_ms": 1783000000000 } } } } } } } } }