{ "openapi": "3.1.0", "info": { "title": "Multiplayer API", "version": "1.0.0", "summary": "Multiplayer API — make any game multiplayer, whatever the genre.", "description": "Multiplayer API (https://multiplayerapi.com) is a hosted multiplayer backend. The server does not simulate your game. It does three things:\n\n1. **It connects players** — accounts, matchmaking, WebRTC signaling.\n2. **It arbitrates what you ask it to arbitrate** — writes to shared state\n are validated against rules you declare in JSON.\n3. **It retains what must survive the match** — progression, items, leaderboards.\n\nEverything else — positions, animations, physics — flows directly between\nplayers via WebRTC. Once connections are established, the server only sees\none presence call every five seconds per player.\n\n## Getting started\n\n```bash\ncurl -X POST https://multiplayerapi.com/v1/games \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"My Game\",\"preset\":\"realtime_arena\"}'\n```\n\nThe response contains a public key, to place in the client, and a secret key\nshown only once, to keep on your server.\n\n## Authentication\n\n| Header | Content | Grants access to |\n|---|---|---|\n| `X-Mp-Key: mp_pk_...` | public key | player operations |\n| `X-Mp-Key: mp_sk_...` | secret key | everything, including privileged writes |\n| `Authorization: Bearer mp_at_...` | session token | identifies the player |\n\n## The three channels\n\nThe most structural choice in an integration.\n\n| | direct (`relay`) | state (`ops`) | events |\n|---|---|---|---|\n| Path | between players | server | server |\n| Delivery | best effort | guaranteed | guaranteed and ordered |\n| Survives reconnection | no | yes | no |\n| Server cost | zero in peer-to-peer | one write | one write |\n\nFor a shooter: position over the direct channel, health and score in state,\na rematch request as an event.\n\n## Cadence\n\n`/rt/sync` returns a `tick_ms` to respect: 100 ms while everything goes through\nthe server, 5000 ms once peer-to-peer is established. This is the API's main\ncost lever — syncing faster than advised multiplies load without helping the\nplayer.\n\nFull documentation for an agent: \n", "license": { "name": "MIT", "identifier": "MIT" }, "contact": { "url": "https://multiplayerapi.com" } }, "servers": [ { "url": "https://multiplayerapi.com/v1" } ], "tags": [ { "name": "Games", "description": "Create and configure a game" }, { "name": "Accounts", "description": "Players, sessions, profiles" }, { "name": "Rooms", "description": "Create, search, join, and leave" }, { "name": "Realtime", "description": "Game loop and peer-to-peer" }, { "name": "Progression", "description": "Counters, leaderboards, inventory" }, { "name": "Results", "description": "Match results and attestation" }, { "name": "Misc", "description": "Health, clock, config, batch" } ], "security": [ { "PublicKey": [] }, { "PublicKey": [], "PlayerToken": [] } ], "paths": { "/health": { "get": { "summary": "Service status", "security": [], "tags": [ "Misc" ], "responses": { "200": { "description": "Service available", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "time": { "type": "integer" } } } } } } } } }, "/time": { "get": { "summary": "Server clock", "description": "Estimates the offset between the player clock and the server clock. Essential when interpolating between peers: a client clock can drift by several minutes.", "security": [], "tags": [ "Misc" ], "parameters": [ { "name": "t", "in": "query", "schema": { "type": "string" }, "description": "Client timestamp, echoed as-is to measure round-trip latency" } ], "responses": { "200": { "description": "Timestamp", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "server_ms": { "type": "integer" }, "echo": { "type": [ "string", "null" ] } } } } } } } } }, "/config": { "get": { "summary": "Game configuration for the client", "tags": [ "Misc" ], "responses": { "200": { "description": "Configuration", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "config": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/presets": { "get": { "summary": "Rule presets", "security": [], "tags": [ "Misc" ], "responses": { "200": { "description": "Available presets", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "presets": { "type": "object", "additionalProperties": true } } } } } } } } }, "/batch": { "post": { "summary": "Batch multiple calls", "description": "Opening a request costs 0.60 ms of CPU, far more than the work it carries: batching five calls divides the cost by nearly five. Each sub-call is independent; one failure does not cancel the others.", "tags": [ "Misc" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "calls" ], "properties": { "calls": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "example": "me" }, "method": { "type": "string", "default": "GET", "enum": [ "GET", "POST", "PATCH", "PUT", "DELETE" ] }, "body": { "type": "object", "additionalProperties": true }, "query": { "type": "object", "additionalProperties": true } } } } } } } } }, "responses": { "200": { "description": "Responses in request order", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/games": { "post": { "summary": "Create a game", "description": "Intended path for an agent: no UI, no prior account. The secret key is shown only at this moment.", "security": [], "tags": [ "Games" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "My Game" }, "preset": { "type": "string", "enum": [ "turn_based", "realtime_arena", "coop", "strict" ] }, "origins": { "type": "array", "items": { "type": "string" }, "description": "Empty allows all origins: convenient for development" } } } } } }, "responses": { "201": { "description": "Game created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "game": { "type": "object", "additionalProperties": true }, "secret_key": { "type": "string" }, "claim_code": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/guest": { "post": { "summary": "Instant guest account", "description": "The player enters the game without a form and can upgrade the account later without losing anything. This is almost always the right choice.\n\nThrottled by address: 30 accounts in a row, then one every 20 s. A guest left 60 days without logging in is deleted along with its inventory and stats; an account upgraded via /auth/upgrade is kept.", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "display_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/register": { "post": { "summary": "Register", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string", "minLength": 8 }, "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/login": { "post": { "summary": "Log in", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Session opened", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/upgrade": { "post": { "summary": "Upgrade a guest account", "description": "Progression, items, and scores are preserved.", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string", "minLength": 8 }, "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Account upgraded", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/recover": { "post": { "summary": "Reset token (secret key)", "description": "The API sends no email: it generates the proof; your server delivers it to the player by whatever means you choose.\n\nThe response is identical whether the account exists or not: your server does not need to know to send a message, and staying silent prevents a leaked secret key from becoming an account directory. The token stops working as soon as the password changes, so it is single-use.", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "identifier" ], "properties": { "identifier": { "type": "string", "description": "Username or email address" }, "ttl": { "type": "integer", "description": "Validity duration in seconds (300 to 86400, default 3600)" } } } } } }, "responses": { "200": { "description": "Token issued, or unknown account", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "sent": { "type": "boolean" }, "reset_token": { "type": "string" }, "expires": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/reset": { "post": { "summary": "Set a new password", "description": "All account sessions are invalidated: a takeover must be complete.", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "reset_token", "password" ], "properties": { "reset_token": { "type": "string" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "Password changed", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/auth/refresh": { "post": { "summary": "Refresh session", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "New session", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "session": { "$ref": "#/components/schemas/Session" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "summary": "Player profile", "tags": [ "Accounts" ], "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "summary": "Update profile", "tags": [ "Accounts" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "display_name": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rooms": { "get": { "summary": "Search rooms", "description": "Metadata filters are free-form: ?meta.map=desert. The API assigns no meaning to these keys.", "tags": [ "Rooms" ], "parameters": [ { "name": "mode", "in": "query", "schema": { "type": "string" } }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "min_free", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Joinable rooms", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/Room" } }, "count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Create a room", "tags": [ "Rooms" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "mode": { "type": "string" }, "region": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "default": "public" }, "max_players": { "type": "integer", "default": 8 }, "meta": { "type": "object", "additionalProperties": true, "description": "Free-form metadata, filterable when searching" }, "state": { "type": "object", "additionalProperties": true, "description": "Initial room state" } } } } } }, "responses": { "201": { "description": "Room created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "room": { "$ref": "#/components/schemas/Room" }, "me": { "$ref": "#/components/schemas/Member" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "ice_servers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tick_ms": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rooms/quickmatch": { "post": { "summary": "Join or create in one call", "description": "The call to prefer: one round trip and the player is in the game. Add join_only to fail instead of creating.", "tags": [ "Rooms" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "mode": { "type": "string" }, "region": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "member_meta": { "type": "object", "additionalProperties": true }, "max_players": { "type": "integer", "default": 8 }, "join_only": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Room joined or created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "room": { "$ref": "#/components/schemas/Room" }, "me": { "$ref": "#/components/schemas/Member" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "created": { "type": "boolean" }, "tick_ms": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rooms/{ref}/join": { "post": { "summary": "Join by code or ID", "description": "role=spectator joins as a spectator only: not counted toward capacity, no write or signaling rights, and even in a locked room. The game must allow this via max_spectators in its configuration.", "tags": [ "Rooms" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Six-character code or rm_... identifier" } ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "member_meta": { "type": "object", "additionalProperties": true }, "role": { "type": "string", "enum": [ "player", "spectator" ], "default": "player" } } } } } }, "responses": { "200": { "description": "Room joined", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "room": { "$ref": "#/components/schemas/Room" }, "me": { "$ref": "#/components/schemas/Member" }, "rejoined": { "type": "boolean" } } } } } }, "409": { "description": "Room full, locked, ended, or spectators not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rooms/{ref}/leave": { "post": { "summary": "Leave a room", "tags": [ "Rooms" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Left successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "left": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rt/sync": { "post": { "summary": "Game loop", "description": "The single loop call. It carries state writes, events, WebRTC signaling, and relayed packets, and reports everything the client has not seen.\n\nRespect tick_ms: cadence goes from 100 ms to 5000 ms once peer-to-peer is established, and that is the API's main cost lever. It also widens when the room grows, and when a tick carried nothing — no relayed packet, write, or delta.", "tags": [ "Realtime" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "room" ], "properties": { "room": { "type": "string", "description": "Room ID or code" }, "since": { "type": "integer", "description": "Last seq received; the server returns only what follows" }, "transport": { "type": "string", "enum": [ "unknown", "p2p", "mixed", "relay" ], "description": "Direct connection state as seen by the client. 'mixed' when only some peers are reachable directly." }, "ops": { "type": "array", "items": { "$ref": "#/components/schemas/StateOp" } }, "events": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "to": { "type": "string", "description": "Single recipient" } } } }, "signals": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string" }, "kind": { "type": "string", "enum": [ "offer", "answer", "ice", "bye" ] }, "data": { "type": "object", "additionalProperties": true } } } }, "relay": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Omitted for a broadcast" }, "data": { "type": "string", "description": "base64 for binary data" } } } }, "atomic": { "type": "boolean", "description": "Require all-or-nothing on state operations" }, "state": { "type": "boolean", "description": "Request full state in the response" } } } } } }, "responses": { "200": { "description": "Room state since `since`", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "seq": { "type": "integer" }, "room_seq": { "type": "integer" }, "tick_ms": { "type": "integer", "description": "Recommended cadence for the next call" }, "log": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "signals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "relay": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "state": { "type": "object", "additionalProperties": true, "description": "Present during resynchronization" }, "resync": { "type": "boolean", "description": "The client was too far behind: full state replaces deltas" }, "applied": { "type": "integer" }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "server_ms": { "type": "integer" } } } } } }, "403": { "description": "A spectator cannot write anything", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The player is not in this room", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/rt/ice": { "get": { "summary": "ICE servers", "description": "Re-fetch before the ttl expiry: a game that declares TURN distributes ephemeral credentials, and a long match must be able to obtain new ones before opening more connections. SDKs handle this automatically.", "tags": [ "Realtime" ], "responses": { "200": { "description": "ICE configuration", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "ice_servers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "ttl": { "type": "integer", "description": "Seconds before the list must be re-fetched" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/stats": { "post": { "summary": "Increment counters", "description": "Every key goes through the game rules. An undeclared stat requires attestation by default, preventing a client from granting itself whatever it wants.", "tags": [ "Progression" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "stats" ], "properties": { "stats": { "type": "object", "additionalProperties": true, "description": "Key to increment, e.g. {\"kills\": 1}" }, "fresh": { "type": "boolean", "description": "Return up-to-date counters" } } } } } }, "responses": { "200": { "description": "Result per key", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "applied": { "type": "object", "additionalProperties": true }, "skipped": { "type": "object", "additionalProperties": true, "description": "Key to rejection reason" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/stats/{account}": { "get": { "summary": "Read counters", "tags": [ "Progression" ], "parameters": [ { "name": "account", "in": "path", "required": true, "schema": { "type": "string" }, "description": "`me` or an account identifier" }, { "name": "fresh", "in": "query", "schema": { "type": "boolean" }, "description": "Force pending batched increments to be applied" } ], "responses": { "200": { "description": "Counters", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "stats": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/leaderboards/{board}": { "get": { "summary": "View a leaderboard", "tags": [ "Progression" ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "all", "daily", "weekly", "monthly" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "ascending", "in": "query", "schema": { "type": "boolean" }, "description": "For a leaderboard where the lowest score wins" } ], "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "entries": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "integer" }, "me": { "type": [ "object", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Submit a score", "tags": [ "Progression" ], "parameters": [ { "name": "board", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "score" ], "properties": { "score": { "type": "number" }, "mode": { "type": "string", "enum": [ "best", "last", "sum", "min" ], "default": "best" }, "periods": { "type": "array", "items": { "type": "string", "enum": [ "all", "daily", "weekly", "monthly" ] } }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Score recorded", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "results": { "type": "object", "additionalProperties": true }, "rank": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/inventory": { "get": { "summary": "Player inventory", "tags": [ "Progression" ], "responses": { "200": { "description": "Owned items", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "equipped": { "type": "object", "additionalProperties": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Grant an item", "description": "Secret key only: without this, the game economy would be at the mercy of the first modified client.", "tags": [ "Progression" ], "security": [ { "SecretKey": [] } ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_id", "item_id" ], "properties": { "account_id": { "type": "string" }, "item_id": { "type": "string" }, "qty": { "type": "integer", "default": 1 }, "meta": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Inventory updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches": { "get": { "summary": "Match history", "tags": [ "Results" ], "responses": { "200": { "description": "Finished matches", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Submit a result", "description": "The host submits the result; rewards are granted only once attested by other players. An isolated host therefore cannot grant itself anything.", "tags": [ "Results" ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [ "room" ], "properties": { "room": { "type": "string" }, "result": { "type": "object", "additionalProperties": true, "description": "Free-form description, not interpreted by the API" }, "rewards": { "type": "object", "additionalProperties": true, "description": "By account identifier: { stats, scores }" }, "close": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Result submitted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "match": { "$ref": "#/components/schemas/Match" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/matches/{id}/attest": { "post": { "summary": "Attest a result", "description": "Counterweight to host authority. A majority disagreement cancels rewards and opens a report.", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": null, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "agree": { "type": "boolean", "default": true }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Signature recorded", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true }, "match": { "$ref": "#/components/schemas/Match" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "PublicKey": { "type": "apiKey", "in": "header", "name": "X-Mp-Key", "description": "Game public key (mp_pk_...). Intended for the client." }, "SecretKey": { "type": "apiKey", "in": "header", "name": "X-Mp-Key", "description": "Secret key (mp_sk_...). Must never leave your server." }, "PlayerToken": { "type": "http", "scheme": "bearer", "description": "Player session token obtained via /auth/*." } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable code, intended for automated handling", "example": "room_full" }, "message": { "type": "string", "description": "Human-readable message, intended for the developer" }, "details": { "type": "object", "additionalProperties": true, "description": "Additional context depending on the code" } } } } }, "Account": { "type": "object", "properties": { "id": { "type": "string", "example": "ac_0ms9t127ufuv1Tpo42WMW" }, "username": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "is_guest": { "type": "boolean", "description": "A guest account can be upgraded without losing progression" }, "data": { "type": "object", "additionalProperties": true, "description": "Free-form player save data" }, "data_version": { "type": "integer", "description": "Send back on the next write to detect conflicts" }, "created": { "type": "integer" }, "last_seen": { "type": "integer" } } }, "Session": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Place in Authorization: Bearer. Two-hour lifetime." }, "refresh_token": { "type": "string", "description": "Thirty-day lifetime." }, "expires": { "type": "integer" } } }, "Room": { "type": "object", "properties": { "id": { "type": "string", "example": "rm_0ms9t12ctu5klJS491mST" }, "code": { "type": "string", "description": "Short code, easy to tell a friend", "example": "B2K2D3" }, "name": { "type": [ "string", "null" ] }, "mode": { "type": [ "string", "null" ], "description": "Free-form: meaning is defined by your game" }, "region": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "phase": { "type": "string", "enum": [ "lobby", "playing", "ended" ] }, "locked": { "type": "boolean" }, "host_id": { "type": [ "string", "null" ], "description": "Automatic handoff to the longest-present player if the host leaves" }, "max_players": { "type": "integer" }, "player_count": { "type": "integer" }, "transport": { "type": "string", "enum": [ "unknown", "p2p", "mixed", "relay" ], "description": "Determines the recommended cadence for the client" }, "meta": { "type": "object", "additionalProperties": true, "description": "Free-form metadata, filterable when searching" }, "state": { "type": "object", "additionalProperties": true, "description": "Shared state document (members only)" }, "seq": { "type": "integer", "description": "Logical clock of the room" }, "version": { "type": "integer", "description": "seq value at the last state modification" }, "created": { "type": "integer" } } }, "Member": { "type": "object", "properties": { "account_id": { "type": "string" }, "peer_id": { "type": "string", "description": "Renewed on each reconnection" }, "name": { "type": "string" }, "is_host": { "type": "boolean" }, "role": { "type": "string", "enum": [ "player", "spectator" ], "description": "A spectator reads the room but cannot write to it" }, "transport": { "type": "string", "enum": [ "unknown", "p2p", "mixed", "relay" ] }, "meta": { "type": "object", "additionalProperties": true }, "joined": { "type": "integer" }, "last_seen": { "type": "integer" } } }, "StateOp": { "type": "object", "required": [ "op", "path" ], "properties": { "op": { "type": "string", "enum": [ "set", "inc", "push", "del", "setnx", "cas" ] }, "path": { "type": "string", "description": "Dotted path. $me is replaced by the caller's identifier.", "example": "players.$me.hp" }, "value": { "description": "Value to write, depending on the operation" }, "expect": { "description": "For cas: expected value before write" } } }, "LogEntry": { "type": "object", "properties": { "seq": { "type": "integer" }, "kind": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "1 state, 2 event, 3 presence" }, "sender": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": true } } }, "Match": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "mode": { "type": [ "string", "null" ] }, "players": { "type": "integer" }, "verdict": { "type": "string", "enum": [ "pending", "confirmed", "disputed", "unconfirmed", "solo" ], "description": "Rewards are granted only on confirmed, or on solo for what does not require attestation" }, "reporter": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "additionalProperties": true }, "granted": { "type": "object", "additionalProperties": true, "description": "Breakdown of what was granted and what was rejected" }, "confirmations": { "type": "object", "properties": { "needed": { "type": "integer" }, "agree": { "type": "integer" }, "disagree": { "type": "integer" }, "deadline": { "type": "integer" } } } } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid key or session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests. The Retry-After header indicates the delay in seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }