{ "openapi": "3.1.0", "info": { "title": "ChipClock API", "version": "1.0.0", "description": "REST API for ChipClock — multi-tenant poker tournament management, designed so an AI agent can run a tournament end-to-end on behalf of a human.\n\n**Start here:** `POST /api/quickstart` returns a trial organization, a demo tournament, and an admin-role API key in a single call. Store the `api_key` value from the response — it is shown exactly once. Then follow `next_actions[0]` to start the clock.\n\n**Authentication.** All endpoints except `/api/quickstart`, `/api/health`, and the public read endpoints require `Authorization: Bearer `. Keys are org-scoped; requests to a different org's URLs return 404.\n\n**Agent-friendly conventions.**\n- Every error response includes `code`, `hint`, `doc_url`, and `next_actions` fields to guide the next call.\n- Mutating endpoints accept `Idempotency-Key` header — identical requests within 24h replay the cached response.\n- Rate-limit responses (429) include a `Retry-After` header.\n- List endpoints return `{ data: [...], next_cursor, total }`; single-resource endpoints return the resource directly.\n\n**See also:** `/llms.txt` for a short reference and `/llms-full.txt` for fully worked agent workflows.", "contact": { "name": "ChipClock", "url": "https://chipclock.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "http://localhost:3000", "description": "Current server" }, { "url": "https://chipclock.com", "description": "Production" } ], "security": [ { "apiKey": [] }, { "cookieAuth": [] } ], "paths": { "/api/health": { "get": { "tags": [ "System" ], "summary": "Liveness probe", "description": "Returns 200 if the service is alive. Does not check database connectivity. Use for uptime monitoring.", "operationId": "get__api_health", "responses": { "200": { "description": "Service is alive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ts": { "type": "string" } }, "required": [ "ok", "ts" ] } } } } }, "security": [] } }, "/api/live-tournament": { "get": { "tags": [ "Public" ], "summary": "Live tournament snapshot", "description": "Single-request snapshot of all live tournament state — clock, blinds, players, eliminations, prize pool, table stats. Designed for polling (recommended interval: 5s). Private sessions return 404.", "operationId": "get__api_live_tournament", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tournament snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveTournament" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Session not found, or session is private.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/clock": { "get": { "tags": [ "Public" ], "summary": "Public clock state", "description": "Read-only clock state for a session. Private sessions return 404. Use `effective_remaining` for the drift-corrected time — don't derive from `time_remaining_seconds` alone.", "operationId": "get__api_clock", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Clock state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockState" } } } }, "404": { "description": "Session not found, or session is private.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/public-table-assignments": { "get": { "tags": [ "Public" ], "summary": "Public table assignments", "description": "Who's sitting at which table and seat. Private sessions return 404.", "operationId": "get__api_public_table_assignments", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Table assignments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Session not found, or session is private.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/public-player-requests": { "get": { "tags": [ "Public" ], "summary": "List player self-service requests", "description": "Pending rebuy/re-seat/chip-count requests submitted by players via their companion page. Visible to the host UI.", "operationId": "get__api_public_player_requests", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Player requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] }, "post": { "tags": [ "Public" ], "summary": "Submit a player self-service request", "description": "Requires a valid PIN for the `rosterPlayerId`. Use this when a player wants to request a rebuy, re-seat, or other self-service action.", "operationId": "post__api_public_player_requests", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "rosterPlayerId", "pin", "kind" ], "properties": { "sessionId": { "type": "string", "format": "uuid" }, "rosterPlayerId": { "type": "string", "format": "uuid" }, "pin": { "type": "string", "pattern": "^\\d{4}$" }, "kind": { "type": "string", "enum": [ "rebuy", "reseat", "addon", "chip-count" ] }, "note": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Request created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid PIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/public-player-pin": { "post": { "tags": [ "Public" ], "summary": "Set or verify a player PIN", "description": "Action `set` requires nickname match (prevents PIN-spraying). Action `verify` checks a 4-digit PIN against a roster player. Rate-limited per player+IP.", "operationId": "post__api_public_player_pin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "rosterPlayerId", "pin" ], "properties": { "action": { "type": "string", "enum": [ "set", "verify" ] }, "rosterPlayerId": { "type": "string", "format": "uuid" }, "pin": { "type": "string", "pattern": "^\\d{4}$" }, "nickname": { "type": "string", "description": "Required when action is `set`." } } } } } }, "responses": { "200": { "description": "PIN accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Invalid PIN or nickname mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/public-feed": { "get": { "tags": [ "Public" ], "summary": "Public activity feed", "description": "Chronological stream of tournament events (eliminations, rebuys, level advances). Useful for a live commentary agent.", "operationId": "get__api_public_feed", "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Activity feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/public-season-standings": { "get": { "tags": [ "Public" ], "summary": "Public season standings", "description": "Leaderboard for a season — points, wins, ITM percentage.", "operationId": "get__api_public_season_standings", "parameters": [ { "name": "seasonId", "in": "query", "required": true, "description": "UUID of the season.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Standings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } }, "/api/orgs/{slug}/clock": { "get": { "tags": [ "Clock" ], "summary": "Read authenticated clock state", "description": "Same shape as public clock but requires org membership and returns 403 for non-members.", "operationId": "get__api_orgs__slug__clock", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Clock state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockState" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Clock" ], "summary": "Control the clock", "description": "Start, pause, resume, advance, rewind, or adjust the tournament clock. Requires the `canControlClock` permission. Returns 409 if session is already in the target state. Rate-limited to 30 req/min per IP.", "operationId": "post__api_orgs__slug__clock", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockAction" } } } }, "responses": { "200": { "description": "Clock state after the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockState" } } } }, "400": { "description": "Invalid input — check the `hint` for which parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "You don't have `canControlClock` permission for this session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Session or clock not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List tournaments", "description": "List sessions for this org, newest first. Filter by `status` (active/paused/completed/cancelled).", "operationId": "get__api_orgs__slug__sessions", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ] } } ], "responses": { "200": { "description": "Session list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Create a tournament", "description": "Creates a new tournament session. Most fields optional — sensible defaults apply (15-level blind structure, 20-min levels).", "operationId": "post__api_orgs__slug__sessions", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}": { "get": { "tags": [ "Sessions" ], "summary": "Get a tournament", "description": "Full session detail including blind structure and payout structure.", "operationId": "get__api_orgs__slug__sessions__id_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Sessions" ], "summary": "Update a tournament", "description": "Partial update. Only fields present in the body are changed.", "operationId": "put__api_orgs__slug__sessions__id_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Delete a tournament", "description": "Hard delete. Cascades to check-ins, eliminations, clock state, table assignments. Irreversible.", "operationId": "delete__api_orgs__slug__sessions__id_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/clone": { "post": { "tags": [ "Sessions" ], "summary": "Clone a tournament for re-run", "description": "Creates a new session copying blinds, payouts, and configuration. Does NOT copy check-ins, eliminations, or results.", "operationId": "post__api_orgs__slug__sessions__id__clone", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Cloned session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/check-in": { "get": { "tags": [ "Sessions" ], "summary": "List check-ins", "description": "All check-ins for this session.", "operationId": "get__api_orgs__slug__sessions__id__check_in", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Check-ins.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckIn" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Check a player in", "description": "Creates a check-in row linking a roster player to this session. Optionally seats the player if `seat_on_pay` is enabled.", "operationId": "post__api_orgs__slug__sessions__id__check_in", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rosterPlayerId" ], "properties": { "rosterPlayerId": { "type": "string", "format": "uuid" }, "payment_status": { "type": "string", "enum": [ "pending", "paid", "refunded" ], "default": "pending" } } } } } }, "responses": { "201": { "description": "Check-in created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIn" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/participants": { "get": { "tags": [ "Sessions" ], "summary": "List session participants", "description": "All players checked in to this session with their elimination status.", "operationId": "get__api_orgs__slug__sessions__id__participants", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Participants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/rebuys": { "get": { "tags": [ "Sessions" ], "summary": "List rebuys/addons", "description": "All rebuy and addon events for this session.", "operationId": "get__api_orgs__slug__sessions__id__rebuys", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rebuys/addons.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Record a rebuy or addon", "description": "Increments the player's rebuy or addon count. Blocked if past `rebuy_cutoff_level` or `addon_cutoff_level`.", "operationId": "post__api_orgs__slug__sessions__id__rebuys", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rosterPlayerId", "kind" ], "properties": { "rosterPlayerId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "rebuy", "addon" ] } } } } } }, "responses": { "201": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Past cutoff level — rebuys/addons no longer allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/results": { "get": { "tags": [ "Sessions" ], "summary": "Get tournament results", "description": "Final standings with payouts.", "operationId": "get__api_orgs__slug__sessions__id__results", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Results.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Finalize tournament", "description": "Marks the session `completed` and writes the payout results based on elimination order.", "operationId": "post__api_orgs__slug__sessions__id__results", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Results saved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/notify": { "post": { "tags": [ "Sessions" ], "summary": "Send tournament notifications", "description": "Sends reminder emails to RSVP'd players. Rate-limited to 3/min.", "operationId": "post__api_orgs__slug__sessions__id__notify", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Notifications queued.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/managers": { "get": { "tags": [ "Sessions" ], "summary": "List session managers", "description": "Members delegated manager permissions for this specific session.", "operationId": "get__api_orgs__slug__sessions__id__managers", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session managers.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Add a session manager", "description": "Grants per-session manager permissions. Body accepts granular permission flags.", "operationId": "post__api_orgs__slug__sessions__id__managers", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Manager added.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Remove a session manager", "description": "Revokes per-session manager permissions.", "operationId": "delete__api_orgs__slug__sessions__id__managers", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Manager removed." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/player-requests": { "get": { "tags": [ "Sessions" ], "summary": "List player requests (host view)", "description": "Pending player self-service requests for the host to approve or reject.", "operationId": "get__api_orgs__slug__sessions__id__player_requests", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Player requests.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Approve/reject a player request", "description": "Resolve a pending player self-service request.", "operationId": "post__api_orgs__slug__sessions__id__player_requests", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Resolved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/sessions/{id}/rsvp": { "get": { "tags": [ "Sessions" ], "summary": "List RSVPs", "description": "Players who have RSVP'd yes/no/maybe for this session.", "operationId": "get__api_orgs__slug__sessions__id__rsvp", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "RSVPs.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Update RSVP status", "description": "Host-side update of a player's RSVP status.", "operationId": "post__api_orgs__slug__sessions__id__rsvp", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "id", "in": "path", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/players": { "get": { "tags": [ "Players" ], "summary": "List roster players", "description": "All players in this org's roster.", "operationId": "get__api_orgs__slug__players", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Roster.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RosterPlayer" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Players" ], "summary": "Add a roster player", "description": "Create a new player in this org's roster.", "operationId": "post__api_orgs__slug__players", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlayer" } } } }, "responses": { "201": { "description": "Player created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RosterPlayer" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Nickname already exists in this org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/players/{playerId}": { "get": { "tags": [ "Players" ], "summary": "Get a roster player", "description": "Single player detail including stats across sessions.", "operationId": "get__api_orgs__slug__players__playerId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "playerId", "in": "path", "required": true, "description": "Roster player UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Player.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RosterPlayer" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Players" ], "summary": "Update a roster player", "description": "Partial update of nickname/email/phone/pin.", "operationId": "put__api_orgs__slug__players__playerId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "playerId", "in": "path", "required": true, "description": "Roster player UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RosterPlayer" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Players" ], "summary": "Delete a roster player", "description": "Removes the player from the roster. Fails if player has any session participation.", "operationId": "delete__api_orgs__slug__players__playerId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "playerId", "in": "path", "required": true, "description": "Roster player UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Player has session history and cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/eliminations": { "get": { "tags": [ "Eliminations" ], "summary": "List eliminations", "description": "Eliminations for a specific session, newest first.", "operationId": "get__api_orgs__slug__eliminations", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Eliminations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Elimination" } } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Eliminations" ], "summary": "Record an elimination", "description": "Records that a player busted from the tournament. Assigns next available position. Optionally records who eliminated them.", "operationId": "post__api_orgs__slug__eliminations", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordElimination" } } } }, "responses": { "201": { "description": "Elimination recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Elimination" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Player already eliminated in this session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/table-assignments": { "get": { "tags": [ "Tables" ], "summary": "List table assignments", "description": "Seat assignments for a specific session.", "operationId": "get__api_orgs__slug__table_assignments", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Table assignments.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Tables" ], "summary": "Assign seats", "description": "Create or update seat assignments. Supports bulk assignment for table balancing.", "operationId": "post__api_orgs__slug__table_assignments", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Assignments saved.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Tables" ], "summary": "Clear seat assignments", "description": "Removes all seat assignments for a session — use before re-balancing.", "operationId": "delete__api_orgs__slug__table_assignments", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "sessionId", "in": "query", "required": true, "description": "UUID of the game session (tournament).", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Cleared." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs": { "get": { "tags": [ "Organizations" ], "summary": "List user's organizations", "description": "All orgs the authenticated user is a member of.", "operationId": "get__api_orgs", "responses": { "200": { "description": "Orgs.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Organizations" ], "summary": "Create an organization", "description": "Creates a new org with the current user as owner. Rate-limited to 5/min per IP.", "operationId": "post__api_orgs", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "responses": { "201": { "description": "Org created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Slug already taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/members": { "get": { "tags": [ "Organizations" ], "summary": "List org members", "description": "All members of this org. Non-admins receive redacted email addresses (PII protection).", "operationId": "get__api_orgs__slug__members", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Members.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Organizations" ], "summary": "Remove org member", "description": "Admin-only. Cannot remove the owner.", "operationId": "delete__api_orgs__slug__members", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/settings": { "get": { "tags": [ "Organizations" ], "summary": "Get org settings", "description": "Non-Stripe settings only — billing data is retrieved via Stripe Portal.", "operationId": "get__api_orgs__slug__settings", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Settings.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Organizations" ], "summary": "Update org settings", "description": "Admin-only.", "operationId": "put__api_orgs__slug__settings", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/invites": { "get": { "tags": [ "Organizations" ], "summary": "List invites", "description": "Outstanding invite tokens for this org.", "operationId": "get__api_orgs__slug__invites", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Invites.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Organizations" ], "summary": "Create an invite", "description": "Generates a 128-bit crypto-random token with a 72-hour expiry.", "operationId": "post__api_orgs__slug__invites", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Invite created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Organizations" ], "summary": "Revoke an invite", "description": "Immediately invalidates an outstanding invite token.", "operationId": "delete__api_orgs__slug__invites", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "204": { "description": "Revoked." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/setups": { "get": { "tags": [ "Templates" ], "summary": "List tournament templates", "description": "Reusable tournament configurations.", "operationId": "get__api_orgs__slug__setups", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Setups.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Templates" ], "summary": "Create a template", "description": "Save the current tournament configuration as a reusable template.", "operationId": "post__api_orgs__slug__setups", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/setups/{setupId}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "description": "Single tournament template.", "operationId": "get__api_orgs__slug__setups__setupId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "setupId", "in": "path", "required": true, "description": "Template UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Templates" ], "summary": "Update a template", "description": "Partial update of a tournament template.", "operationId": "put__api_orgs__slug__setups__setupId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "setupId", "in": "path", "required": true, "description": "Template UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "description": "Removes a tournament template.", "operationId": "delete__api_orgs__slug__setups__setupId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "setupId", "in": "path", "required": true, "description": "Template UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/leaderboard": { "get": { "tags": [ "Stats" ], "summary": "Org leaderboard", "description": "Aggregated stats across all sessions — wins, points, ITM percentage, best finish.", "operationId": "get__api_orgs__slug__leaderboard", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Leaderboard.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/seasons": { "get": { "tags": [ "Seasons" ], "summary": "List seasons", "description": "All seasons for this org.", "operationId": "get__api_orgs__slug__seasons", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Seasons.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Seasons" ], "summary": "Create a season", "description": "Group sessions into a season for standings.", "operationId": "post__api_orgs__slug__seasons", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Season created.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/seasons/{seasonId}": { "get": { "tags": [ "Seasons" ], "summary": "Get a season", "description": "Season detail.", "operationId": "get__api_orgs__slug__seasons__seasonId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "seasonId", "in": "path", "required": true, "description": "Season UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Season.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "Seasons" ], "summary": "Update a season", "description": "Partial update.", "operationId": "put__api_orgs__slug__seasons__seasonId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "seasonId", "in": "path", "required": true, "description": "Season UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Seasons" ], "summary": "Delete a season", "description": "Removes the season. Does not delete member sessions.", "operationId": "delete__api_orgs__slug__seasons__seasonId_", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "seasonId", "in": "path", "required": true, "description": "Season UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/seasons/{seasonId}/standings": { "get": { "tags": [ "Seasons" ], "summary": "Season standings", "description": "Points leaderboard for a season.", "operationId": "get__api_orgs__slug__seasons__seasonId__standings", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "seasonId", "in": "path", "required": true, "description": "Season UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Standings.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/recommend": { "post": { "tags": [ "AI" ], "summary": "AI recommendation", "description": "Ask an AI assistant for tournament recommendations (buy-in sizing, blind structure, payout curves). Powered by Claude. Rate-limited to 5/min per IP.", "operationId": "post__api_orgs__slug__recommend", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 2000, "description": "Freeform natural-language question about tournament configuration." }, "context": { "type": "object", "description": "Optional: current session config to anchor the recommendation." } } } } } }, "responses": { "200": { "description": "Recommendation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recommendation": { "type": "string" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "AI service unavailable (misconfigured or provider outage).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/billing/checkout": { "post": { "tags": [ "Billing" ], "summary": "Create Stripe Checkout session", "description": "Owner-only. Creates a Stripe Checkout session for upgrading to a paid tier. Rate-limited to 5/min.", "operationId": "post__api_orgs__slug__billing_checkout", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Checkout URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/billing/portal": { "post": { "tags": [ "Billing" ], "summary": "Create Stripe Customer Portal session", "description": "Owner-only. Creates a Stripe Customer Portal session for billing management.", "operationId": "post__api_orgs__slug__billing_portal", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "Portal URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/orgs/{slug}/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "List active (non-revoked) agent API keys for this org. Admin/owner only. The response never includes the plaintext key — only the prefix for display.", "operationId": "get__api_orgs__slug__api_keys", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "responses": { "200": { "description": "API keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "manager", "player" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "display": { "type": "string", "description": "e.g. 'ck_live_abc1...'" } } } }, "total": { "type": "integer" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create a new API key", "description": "Generates a fresh agent API key and returns the plaintext ONCE. Save it immediately — it cannot be recovered. Use in subsequent requests as `Authorization: Bearer `. A key cannot grant a role higher than its creator's role.", "operationId": "post__api_orgs__slug__api_keys", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any random string (UUID recommended). Identical requests with the same key within 24 hours return the original response — safe to retry on network failure.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for this key (e.g., 'Zapier integration')." }, "role": { "type": "string", "enum": [ "owner", "admin", "manager", "player" ], "default": "manager", "description": "Effective role for this key. Cannot exceed creator's role." }, "scopes": { "type": "array", "items": { "type": "string" }, "maxItems": 32, "description": "Reserved for future use — per-resource grants like 'clock:write'. Currently the role determines permissions." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650, "nullable": true, "description": "Days until expiry. Null or omitted = no expiry." } } } } } }, "responses": { "201": { "description": "Key created. The `token` field is shown ONCE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "role": { "type": "string" }, "token": { "type": "string", "description": "The plaintext key (shown only on creation). Save it now." }, "_warning": { "type": "string" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key", "description": "Immediately revokes the key. Revoked keys cannot authenticate. Admin/owner only.", "operationId": "delete__api_orgs__slug__api_keys", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug (URL-friendly identifier).", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyId" ], "properties": { "keyId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input. Response `hint` may describe which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but lacks permission for this org or action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found (may also indicate no access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. Check `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. Safe to retry with Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/quickstart": { "post": { "tags": [ "Public" ], "summary": "Create a trial org, session, and API key in one request", "description": "One-call provisioning for agents. Creates a ghost-owned trial organization, a demo tournament with the default 15-level blind structure, a clock row, and an admin-role API key. The `api_key` value is returned in plaintext exactly once — agents must persist it before any follow-up call.\n\nTrial orgs auto-expire 7 days after creation; a daily Vercel Cron deletes them and their ghost owners. The API key expires 1 day after the org so cleanup produces 404s instead of 401s during the grace window.\n\n**Not idempotent** — retrying after a network timeout creates a second trial org. `hints.retry_safety` in the response re-states this so the caller does not blind-retry.\n\n**Rate limit**: 5 requests per hour per IP (advisory; serverless evasion documented in `/llms-full.txt`).\n\nAfter this call, agents typically proceed to `POST /api/orgs/{org_slug}/clock` with `{\"sessionId\":\"{session_id}\",\"action\":\"start\"}` using the returned `api_key`.", "operationId": "post__api_quickstart", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Optional contact email for the trial. Advisory; not verified." }, "org_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the trial org. Becomes the slug prefix; random suffix appended." }, "session_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name for the auto-created demo session. Defaults to \"Demo Tournament\"." } } } } } }, "responses": { "201": { "description": "Trial provisioned. Store `api_key` immediately — it will not be shown again.", "content": { "application/json": { "schema": { "type": "object", "required": [ "org_slug", "api_key", "api_key_prefix", "session_id", "expires_at", "next_actions" ], "properties": { "org_slug": { "type": "string", "description": "Use in every follow-up URL: /api/orgs/{org_slug}/..." }, "api_key": { "type": "string", "description": "Plaintext Bearer token — shown ONCE. Format: ck_live_<43-char-base64url>." }, "api_key_prefix": { "type": "string", "description": "First 8 chars of the raw token (after the ck_live_ prefix). Safe to log." }, "session_id": { "type": "string", "format": "uuid", "description": "UUID of the auto-created demo tournament." }, "session_url": { "type": "string", "format": "uri" }, "clock_url": { "type": "string", "format": "uri" }, "openapi_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO-8601. Trial org is deleted after this instant (1-day grace)." }, "hints": { "type": "object", "properties": { "start_clock": { "type": "string" }, "add_player": { "type": "string" }, "check_in": { "type": "string" }, "retry_safety": { "type": "string" } } }, "next_actions": { "type": "array", "items": { "type": "object", "required": [ "rel", "href" ], "properties": { "rel": { "type": "string" }, "href": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] } } } }, "_warning": { "type": "string" } } } } } }, "400": { "description": "Invalid input (bad email, oversize org_name, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Hourly cap hit. Retry-After header present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Slug generator exhausted after 5 retries. Retry or pass a different org_name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [] } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message (legacy — prefer error.code)" }, "code": { "description": "Machine-readable error code, e.g. `session_not_found`", "type": "string" }, "message": { "description": "Human-readable error message", "type": "string" }, "hint": { "description": "Guidance for how to recover — often points to the right next call", "type": "string" }, "doc_url": { "description": "Link to documentation for this error", "type": "string", "format": "uri" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "rel": { "type": "string", "description": "Relation name, e.g. `retry`, `resume`, `verify-pin`" }, "href": { "type": "string", "description": "URL or path to call next" }, "method": { "type": "string", "enum": [ "GET", "POST", "PATCH", "PUT", "DELETE" ] } }, "required": [ "rel", "href" ], "additionalProperties": false } } }, "required": [ "error" ], "additionalProperties": false, "id": "ErrorEnvelope", "description": "Standard error shape returned by all endpoints on non-2xx responses." }, "ClockState": { "type": "object", "properties": { "game_session_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "org_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "current_level": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "time_remaining_seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "is_running": { "type": "boolean" }, "is_paused": { "type": "boolean" }, "pause_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_updated_at": { "type": "string", "description": "ISO 8601 timestamp used for drift-corrected client-side timing" }, "effective_remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Server-computed remaining seconds, drift-corrected from last_updated_at" } }, "required": [ "game_session_id", "org_id", "current_level", "time_remaining_seconds", "is_running", "is_paused", "pause_message", "last_updated_at", "effective_remaining" ], "additionalProperties": false, "id": "ClockState" }, "ClockAction": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "action": { "type": "string", "enum": [ "start", "pause", "resume", "next-level", "prev-level", "set-level", "adjust-time" ], "description": "Clock action to perform. `set-level` requires `level`; `adjust-time` requires `adjustSeconds`." }, "pauseMessage": { "description": "Optional message shown on the clock when paused (e.g. 'Break — 10 minutes')", "type": "string", "maxLength": 200 }, "level": { "description": "Required when action is `set-level`", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "adjustSeconds": { "description": "Required when action is `adjust-time`. Positive or negative. Clamped to non-negative remaining time.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "sessionId", "action" ], "additionalProperties": false, "id": "ClockAction" }, "SessionStatus": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ], "id": "SessionStatus" }, "Session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "org_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "$ref": "#/$defs/SessionStatus" }, "buy_in_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "starting_stack": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "level_duration_minutes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "is_private": { "type": "boolean" }, "seat_on_pay": { "type": "boolean" }, "blinds_config": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false } }, "payout_structure": { "anyOf": [ { "type": "object", "properties": { "positions": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "maximum": 1000 }, "percentage": { "default": 0, "type": "number", "minimum": 0, "maximum": 100 }, "amount": { "type": "number", "minimum": 0 } }, "required": [ "position", "percentage" ], "additionalProperties": false } } }, "required": [ "positions" ], "additionalProperties": false }, { "type": "null" } ] }, "rebuy_allowed": { "type": "boolean" }, "rebuy_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "addon_allowed": { "type": "boolean" }, "addon_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "org_id", "name", "status", "buy_in_amount", "starting_stack", "level_duration_minutes", "is_private", "seat_on_pay", "blinds_config", "payout_structure", "rebuy_allowed", "rebuy_price", "addon_allowed", "addon_price", "started_at", "created_at", "updated_at" ], "additionalProperties": false, "id": "Session", "$defs": { "SessionStatus": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ], "id": "SessionStatus" } } }, "LiveTournament": { "type": "object", "properties": { "sessionStatus": { "$ref": "#/$defs/SessionStatus" }, "checkedIn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "eliminated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clockState": { "anyOf": [ { "type": "object", "properties": { "currentLevel": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "timeRemaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isRunning": { "type": "boolean" }, "isPaused": { "type": "boolean" }, "pauseMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastUpdatedAt": { "type": "string" } }, "required": [ "currentLevel", "timeRemaining", "isRunning", "isPaused", "pauseMessage", "lastUpdatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "blinds": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false } }, "currentBlind": { "anyOf": [ { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false }, { "type": "null" } ] }, "nextBlind": { "anyOf": [ { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false }, { "type": "null" } ] }, "prizePool": { "type": "number" }, "totalRebuys": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalAddons": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recentEliminations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "nickname": { "type": "string" }, "eliminated_by_nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "eliminated_at": { "type": "string" } }, "required": [ "id", "nickname", "eliminated_by_nickname", "position", "eliminated_at" ], "additionalProperties": false } }, "tableStats": { "type": "array", "items": { "type": "object", "properties": { "table_number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "player_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "table_number", "player_count" ], "additionalProperties": false } }, "buyInAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startingStack": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payoutStructure": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "percentage": { "type": "number" } }, "required": [ "position", "percentage" ], "additionalProperties": false } }, "seatOnPay": { "type": "boolean" } }, "required": [ "sessionStatus", "checkedIn", "remaining", "eliminated", "clockState", "blinds", "currentBlind", "nextBlind", "prizePool", "totalRebuys", "totalAddons", "recentEliminations", "tableStats", "buyInAmount", "startingStack", "startedAt", "payoutStructure", "seatOnPay" ], "additionalProperties": false, "id": "LiveTournament", "description": "Complete snapshot of a live tournament — clock, players, blinds, tables, prize pool.", "$defs": { "SessionStatus": { "type": "string", "enum": [ "active", "paused", "completed", "cancelled" ], "id": "SessionStatus" } } }, "RosterPlayer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "org_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "nickname": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } }, "required": [ "id", "org_id", "nickname", "created_at" ], "additionalProperties": false, "id": "RosterPlayer" }, "CreatePlayer": { "type": "object", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 50 }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] } }, "required": [ "nickname" ], "additionalProperties": false, "id": "CreatePlayer" }, "Elimination": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "game_session_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "roster_player_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eliminated_by_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "eliminated_at": { "type": "string" } }, "required": [ "id", "game_session_id", "roster_player_id", "eliminated_by_id", "position", "eliminated_at" ], "additionalProperties": false, "id": "Elimination" }, "RecordElimination": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "rosterPlayerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "eliminatedById": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "sessionId", "rosterPlayerId" ], "additionalProperties": false, "id": "RecordElimination" }, "CheckIn": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "game_session_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "roster_player_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "payment_status": { "type": "string", "enum": [ "pending", "paid", "refunded" ] }, "rebuy_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "addon_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "checked_in_at": { "type": "string" } }, "required": [ "id", "game_session_id", "roster_player_id", "payment_status", "rebuy_count", "addon_count", "checked_in_at" ], "additionalProperties": false, "id": "CheckIn" }, "BlindLevel": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false }, "BlindsConfig": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "minimum": 1, "maximum": 200 }, "small_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "big_blind": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "ante": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 600 }, "is_break": { "type": "boolean" } }, "required": [ "level", "small_blind", "big_blind" ], "additionalProperties": false } }, "PayoutStructure": { "type": "object", "properties": { "positions": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 1, "maximum": 1000 }, "percentage": { "default": 0, "type": "number", "minimum": 0, "maximum": 100 }, "amount": { "type": "number", "minimum": 0 } }, "required": [ "position", "percentage" ], "additionalProperties": false } } }, "required": [ "positions" ], "additionalProperties": false } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ck_live_*", "description": "Agent API key. Issue from `/orgs/{slug}/settings/api-keys`. Include as `Authorization: Bearer ck_live_`. Scoped per organization with granular permissions." }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "Supabase session cookie. Set by the web UI login flow. Not suitable for agents." } } }, "tags": [ { "name": "System", "description": "Health and meta endpoints. Use `/api/health` for uptime monitoring — it does not check DB connectivity." }, { "name": "Public", "description": "No-auth endpoints. Most are gated by session UUID — private sessions return 404. Start here with `POST /api/quickstart` for agent bootstrap." }, { "name": "Clock", "description": "Tournament clock control. Use `next-level` with `force: true` behind a confirm dialog on UIs — that bypasses the 2-second cooldown that protects against two devices racing." }, { "name": "Sessions", "description": "Tournament CRUD + lifecycle. Creating a session always creates a matching `clock_state` row — never write to `clock_state` directly." }, { "name": "Players", "description": "Org roster management. Roster is per-org, not per-session. A `check_in` row joins a roster player to a specific tournament." }, { "name": "Eliminations", "description": "Busting players from a tournament. `eliminated_by_id` is optional — omit it for walk-away busts. Always includes a `session_events` audit entry." }, { "name": "Tables", "description": "Seating and table balancing. Enable `seat_on_pay` on the session to have the server auto-seat players at check-in." }, { "name": "Organizations", "description": "Tenant administration. Most org-level settings are behind admin role. API keys cannot manage other keys — rotate via the web UI." }, { "name": "Templates", "description": "Reusable tournament configurations. Share via short code; import by code creates a local copy so edits don't propagate." }, { "name": "Stats", "description": "Leaderboards and analytics. Season standings and per-player stats are read-only — the writes happen implicitly when eliminations + results are recorded." }, { "name": "Seasons", "description": "Grouping tournaments across time. A session belongs to at most one season (via `season_id`). Best-of-N scoring configured per-season." }, { "name": "AI", "description": "Claude-powered recommendations. Rate-limited 5/min. Prompt-driven — returns natural-language suggestions, not structured data." }, { "name": "Billing", "description": "Stripe Checkout and Customer Portal. Agent keys cannot initiate checkout — billing is a web-UI action." }, { "name": "API Keys", "description": "Agent API key management — create, list, revoke. Cannot be invoked via a Bearer key (prevents key-rotation loops); use the web UI." } ] }