{"openapi":"3.1.0","info":{"title":"Mistboard API","version":"0.1.0","description":"The public read API behind mistboard.com: games, watch feeds, puzzles, studies, ratings, the xiangqi opening explorer, and the forum. Everything here answers to an anonymous GET with no key. It is version 0: field names are stable in practice but not yet promised, and anything not listed here is not public.\n\nErrors are `{ \"error\": \"<code>\" }` with the codes named per route. There is no CORS header, so call it from a server or a same-origin page. Please keep polling gentle: the watch feeds cache for seconds, and nothing here is meant to be hit more than about once a second."},"servers":[{"url":"https://mistboard.com"}],"tags":[{"name":"Site","description":"Liveness and site-wide counts."},{"name":"Games","description":"Finished games. A game is public once it ends and never before."},{"name":"Watch","description":"The feeds Mistboard TV and /watch read."},{"name":"Ratings","description":"The rating ladders."},{"name":"Players","description":"Public profiles."},{"name":"Bots","description":"Engines a player can be offered."},{"name":"Puzzles","description":"The puzzle trainer."},{"name":"Studies","description":"Public studies and their chapters."},{"name":"Xiangqi","description":"The opening explorer and tournament broadcasts."},{"name":"Forum","description":"Forum reads."},{"name":"Coaches","description":"The coach directory."},{"name":"Embeds","description":"oEmbed and this document."}],"paths":{"/api/ping":{"get":{"tags":["Site"],"summary":"Round-trip probe","description":"No database, no allocations, `cache-control: no-store`.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"now":{"type":"integer","description":"Server time, ms since epoch."},"lagMs":{"type":"number","description":"Event-loop lag on the server."}}}}}}}}},"/api/live-stats":{"get":{"tags":["Site"],"summary":"How many people are playing and online","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"playing":{"type":"integer"},"online":{"type":"integer"},"playingBySpec":{"type":"object","description":"Live games in play per game spec id with at least one person seated; zero entries are omitted.","additionalProperties":{"type":"integer"}},"totalCompletedGames":{"type":["integer","null"],"description":"Counted completed games, as on /api/stats/public; refreshed at most every 30 seconds. Null without a database."},"last30dCompletedGames":{"type":["integer","null"],"description":"Counted games completed in the last 30 days; same cache."}}}}}}}}},"/api/play/variant-order":{"get":{"tags":["Site"],"summary":"Variants ordered by recent play","description":"Game spec ids ordered by counted human games that ended in the last 28 days, most first; ties in the canonical order. Cached for six hours. Empty without a database.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"windowDays":{"type":"integer"},"computedAt":{"type":"string","format":"date-time"}}}}}}}}},"/api/players/online":{"get":{"tags":["Site"],"summary":"Players online now","description":"At most 50 named players; `count` is the untruncated total. Private profiles are excluded.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"players":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"},"title":{"type":["string","null"]},"rating":{"type":["object","null"]},"playing":{"type":"boolean"},"champions":{"type":"array","description":"Current champion ladders for a linkable human account; never internal account ids.","items":{"type":"object","required":["variant","timeClass"],"additionalProperties":false,"properties":{"variant":{"type":"string"},"timeClass":{"type":"string","enum":["bullet","blitz","rapid","correspondence"]}}}}}}},"count":{"type":"integer"},"anonymousOnline":{"type":"integer"}}}}}}}}},"/api/stats/public":{"get":{"tags":["Site"],"summary":"Site-wide game statistics","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"totalCompletedGames":{"type":"integer"},"last30dCompletedGames":{"type":"integer"},"publicGames":{"type":"integer"},"accounts":{"type":"integer"},"weeklyCompletedGames":{"type":"array","items":{"type":"object"}},"weeklyByVariant":{"type":"array","items":{"type":"object"}},"weeklyByPlay":{"type":"array","items":{"type":"object","required":["weekStart","vsBot","casualLive","ratedLive","casualCorrespondence","ratedCorrespondence"],"properties":{"weekStart":{"type":"string","format":"date"},"vsBot":{"type":"integer","minimum":0},"casualLive":{"type":"integer","minimum":0},"ratedLive":{"type":"integer","minimum":0},"casualCorrespondence":{"type":"integer","minimum":0},"ratedCorrespondence":{"type":"integer","minimum":0}}}},"modeTotals":{"type":"object"},"variantTotals":{"type":"array","items":{"type":"object"}},"dailyCompletedGames":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/recent":{"get":{"tags":["Games"],"summary":"The ten most recent public games","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/GameRecord"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/showcase":{"get":{"tags":["Games"],"summary":"Curated recent games across variants","description":"The pool the homepage board draws from: substantial finished games, interleaved across variants for breadth, not sorted by recency. Each entry also carries `delayedAir` (boolean): true for fog variants that can never be shown live, which the homepage board replays after they end, at their recorded pace.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/GameRecord"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/eve-games/recent":{"get":{"tags":["Games"],"summary":"Recent engine-versus-engine games","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/GameRecord"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/{roomId}":{"get":{"tags":["Games"],"summary":"One finished game","description":"A room id: the last segment of a game’s review URL. This route matches the raw request line, so it takes no query string at all. A game still in progress is 404 until it finishes.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"game":{"allOf":[{"$ref":"#/components/schemas/GameRecord"},{"type":"object","properties":{"players":{"type":"array","items":{"$ref":"#/components/schemas/PostgamePlayer"}}}}]}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/{roomId}/events":{"get":{"tags":["Games"],"summary":"The event log of a finished game","description":"The replay source of truth. A room id: the last segment of a game’s review URL. This route matches the raw request line, so it takes no query string at all. Fog games answer 403 until they finish: hidden information is never served early.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object"}}}}}}},"403":{"description":"The game is not public yet (`game_not_public`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/{roomId}/export.pgn":{"get":{"tags":["Games"],"summary":"A finished game as PGN","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"The PGN text, `content-disposition: inline`.","content":{"application/x-chess-pgn":{"schema":{"type":"string"}}}},"403":{"description":"`game_not_public`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"`export_not_supported_for_variant`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/{roomId}/export.json":{"get":{"tags":["Games"],"summary":"A finished game as JSON","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"The export document.","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"`game_not_public`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"`export_not_supported_for_variant`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/games/{roomId}/crosstable":{"get":{"tags":["Games"],"summary":"Head-to-head record of the two players","description":"A 200 with `{ available: false, reason }` when the seats do not resolve to a rated pair.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/{variant}/games/{roomId}":{"get":{"tags":["Games"],"summary":"A finished game with its per-ply views","description":"The postgame payload the review pages render: the game envelope, the final view, and every position of the game. One route per variant: `/api/xiangqi/games/{roomId}`, `/api/banqi/games/{roomId}`, `/api/jieqi/games/{roomId}`, `/api/dark-xiangqi/games/{roomId}`, and so on for every variant with a game route. Finished games only; a variant mismatch is a 404. `/api/three-kingdoms-banqi/games/{roomId}` (an admin-only playtest) answers only an admin session; anyone else gets the same 404 as an unknown game.","parameters":[{"name":"variant","in":"path","required":true,"schema":{"type":"string"},"description":"A game spec id with a review route, e.g. `xiangqi`."},{"name":"roomId","in":"path","required":true,"schema":{"type":"string"},"description":"Room id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"game":{"$ref":"#/components/schemas/PostgameGame"},"state":{"type":"object"},"timeline":{"type":"array","items":{"type":"object"}},"view":{"type":"object","description":"The final position."},"history":{"type":"array","items":{"type":"object","properties":{"ply":{"type":"integer"},"view":{"type":"object"}}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/watch":{"get":{"tags":["Watch"],"summary":"A watch channel: its finished games and the rail","parameters":[{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["top","xiangqi","banqi","jieqi","fortress-xiangqi","dark-xiangqi","duck-xiangqi","atomic-xiangqi","crazyhouse-xiangqi","dark-chess","jungle","jungle-flip","gomoku","engines"],"default":"top"},"description":"Which channel. The set is what /watch offers and can change as variants launch."},{"name":"curated","in":"query","required":false,"schema":{"type":"string","enum":["0"]},"description":"`0` lists the full feed without the 20-ply bar the Featured channel applies (what /games \"Just finished\" shows)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"activeChannel":{"type":"string"},"channels":{"type":"array","items":{"type":"object"}},"now":{"type":"string","format":"date-time"},"unlockLimit":{"type":"integer"},"sealedCount":{"type":"integer","description":"Games still sealed (recently finished, not yet public)."},"unlocked":{"type":"array","items":{"$ref":"#/components/schemas/GameRecord"}}}}}}},"404":{"description":"`unknown_watch_channel`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/watch/live":{"get":{"tags":["Watch"],"summary":"The featured live game of a channel","description":"What Mistboard TV follows. `featured` is null when nothing is live. Pass `room` and `ply` for the game you are already showing and the payload is omitted while the position is unchanged. Fog games are never featured.","parameters":[{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["top","xiangqi","banqi","jieqi","fortress-xiangqi","dark-xiangqi","duck-xiangqi","atomic-xiangqi","crazyhouse-xiangqi","dark-chess","jungle","jungle-flip","gomoku","engines"],"default":"top"},"description":"Which channel."},{"name":"room","in":"query","required":false,"schema":{"type":"string"},"description":"The room you are following."},{"name":"ply","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"The ply you last rendered."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string"},"featured":{"type":["object","null"],"properties":{"roomId":{"type":"string"},"gameSpecId":{"type":"string"},"ply":{"type":"integer"},"players":{"type":"array","items":{"type":"object"}},"payload":{"type":"object","description":"The postgame-shaped live payload."}}},"now":{"type":"string","format":"date-time"}}}}}},"404":{"description":"`unknown_watch_channel`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard":{"get":{"tags":["Ratings"],"summary":"One rating ladder","parameters":[{"name":"variant","in":"query","required":false,"schema":{"type":"string","default":"fog"},"description":"A rating pool: `xiangqi`, `jieqi`, `banqi`, `fog` (fog chess), `dark_xiangqi`, `jungle`, `jungle_flip`, `fortress_xiangqi`, … (underscores). A game spec id is accepted too."},{"name":"timeClass","in":"query","required":false,"schema":{"type":"string","enum":["bullet","blitz","rapid"],"default":"blitz"},"description":"Which clock class."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Rows."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"leaderboard":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"}},"bucket":{"type":"object","properties":{"variant":{"type":"string"},"timeClass":{"type":"string"}}},"timeClasses":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"`invalid_rating_time_class`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard/summary":{"get":{"tags":["Ratings"],"summary":"The top of every ladder, plus active players","parameters":[{"name":"timeClass","in":"query","required":false,"schema":{"type":"string","enum":["bullet","blitz","rapid"],"default":"blitz"},"description":"Which clock class."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Rows per ladder."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"timeClass":{"type":"string"},"ladders":{"type":"array","items":{"type":"object","properties":{"variant":{"type":"string"},"leaderboard":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardEntry"}}}}},"activePlayers":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"`invalid_rating_time_class`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users/{handle}/profile":{"get":{"tags":["Players"],"summary":"A player’s public profile","description":"Private profiles are 404. Signed-in viewers also get a `relation` field; anonymous callers get null.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The player’s handle."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone the streak days are counted on (default UTC)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"profile":{"type":"object","properties":{"user":{"type":"object","properties":{"champions":{"type":"array","description":"Current champion ladders for a linkable human account; never internal account ids.","items":{"type":"object","required":["variant","timeClass"],"additionalProperties":false,"properties":{"variant":{"type":"string"},"timeClass":{"type":"string","enum":["bullet","blitz","rapid","correspondence"]}}}}}},"ratings":{"type":"array","items":{"type":"object"}},"activity":{"type":"array","items":{"type":"object","properties":{"variant":{"type":"string","enum":["ffq-banqi"]},"totalGamesPlayed":{"type":"integer"},"wins":{"type":"integer"},"draws":{"type":"integer"},"losses":{"type":"integer"}}}},"puzzleRatings":{"type":"array","items":{"type":"object"}},"puzzleStreak":{"$ref":"#/components/schemas/PlayStreak"},"games":{"type":"array","items":{"type":"object"}},"gamesTotal":{"type":"integer"}}}}}}}},"400":{"description":"`invalid_handle`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users/{handle}/games":{"get":{"tags":["Players"],"summary":"A player’s public games, paged","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The player’s handle."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Skip this many."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":15},"description":"Page size."},{"name":"before","in":"query","required":false,"schema":{"type":"string"},"description":"JSON [endedAt, roomId] from the last row. Lists strictly older games; overrides offset."},{"name":"variant","in":"query","required":false,"schema":{"type":"string"},"description":"Rating pool, e.g. `xiangqi`, or casual activity spec `ffq-banqi`; unknown values list every variant."},{"name":"result","in":"query","required":false,"schema":{"type":"string","enum":["win","loss","draw"]},"description":"Result from this player’s seat."},{"name":"vs","in":"query","required":false,"schema":{"type":"string"},"description":"Opponent handle (case-insensitive, exact)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"games":{"type":"array","items":{"type":"object"}},"total":{"type":"integer","description":"Games matching the filters."}}}}}},"400":{"description":"`invalid_handle`, `invalid_result`, `invalid_opponent`, `invalid_before`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/users/{handle}/rating-history":{"get":{"tags":["Players"],"summary":"A player’s rating over time in one pool","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The player’s handle."},{"name":"variant","in":"query","required":true,"schema":{"type":"string"},"description":"A rating pool (see the leaderboard)."},{"name":"timeClass","in":"query","required":false,"schema":{"type":"string","enum":["bullet","blitz","rapid"],"default":"blitz"},"description":"Which clock class."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"history":{"type":"object","properties":{"variant":{"type":"string"},"timeClass":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"roomId":{"type":"string"},"endedAt":{"type":"string","format":"date-time"},"ratingBefore":{"type":"integer"},"ratingAfter":{"type":"integer"}}}}}}}}}}},"400":{"description":"`invalid_handle`, `invalid_rating_variant` or `invalid_rating_time_class`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bots":{"get":{"tags":["Bots"],"summary":"Every bot a player can be offered","description":"The one source that knows what a player is offered: each bot with the specs it can play right now.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"bots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"bio":{"type":"string"},"activeEngineId":{"type":"string"},"defaultGameSpecId":{"type":"string"},"supportedGameSpecIds":{"type":"array","items":{"type":"string"}},"rating":{"type":["object","null"]},"playOptions":{"type":"array","items":{"type":"object","properties":{"gameSpecId":{"type":"string"},"engineId":{"type":"string"},"playable":{"type":"boolean"}}}}}}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bots/{id}":{"get":{"tags":["Bots"],"summary":"One bot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Bot id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"bot":{"type":"object"}}}}}},"400":{"description":"`invalid_bot_id`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/engines/playable":{"get":{"tags":["Bots"],"summary":"Engines available for fog chess play","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"familyName":{"type":"string"},"kind":{"type":"string"}}}}}}}}}}}},"/api/puzzles":{"get":{"tags":["Puzzles"],"summary":"The puzzle list","description":"Signed-in callers also get `attemptedIds`; anonymous callers get an empty list there.","parameters":[{"name":"variant","in":"query","required":false,"schema":{"type":"string","enum":["xiangqi","jungle"]},"description":"Restrict to one variant; omit for all."},{"name":"motif","in":"query","required":false,"schema":{"type":"string","enum":["bai-lian-jiang","men-gong","men-sha","chen-ya-jun","chong-pao","ma-hou-pao","tian-di-pao","kong-tou-pao","tie-men-shuan","wo-cao-ma","gua-jiao-ma","ba-jiao-ma","diao-yu-ma","gao-diao-ma","ba-huang-ma","shuang-ju-cuo","da-dan-chuan-xin","xiao-dao-wan-xin","ju-pao-chou-sha","er-gui-pai-men","song-fo-gui-dian","lao-zu-sou-shan","shuang-zhao-jiang"]},"description":"Restrict to a named xiangqi mating pattern. Intersects variant; omit or leave empty for all."},{"name":"theme","in":"query","required":false,"schema":{"type":"string","enum":["bai-lian-jiang","men-gong","men-sha","chen-ya-jun","chong-pao","ma-hou-pao","tian-di-pao","kong-tou-pao","tie-men-shuan","wo-cao-ma","gua-jiao-ma","ba-jiao-ma","diao-yu-ma","gao-diao-ma","ba-huang-ma","shuang-ju-cuo","da-dan-chuan-xin","xiao-dao-wan-xin","ju-pao-chou-sha","er-gui-pai-men","song-fo-gui-dian","lao-zu-sou-shan","shuang-zhao-jiang","matein1","matein2","matein3","matein4","opening","middlegame","endgame","checkmate","winning","one-move","short","long","very-long"]},"description":"Restrict to any trainer tag: a mating pattern, mate-in-N, phase, goal or length. Intersects variant and motif."},{"name":"player","in":"query","required":false,"schema":{"type":"string"},"description":"Canonical player slug. Matches an explicit player:<slug> provenance tag and intersects variant, motif and theme. Unknown slugs return an empty list; omit or leave empty for all."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"puzzles":{"type":"array","items":{"$ref":"#/components/schemas/PuzzleSummary"}},"attemptedIds":{"type":"array","items":{"type":"string"}},"themes":{"type":"array","description":"All classified themes and counts for the discoverable variant pool, before the theme filter.","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hanzi":{"type":"string"},"pinyin":{"type":"string"},"literal":{"type":"string"},"gloss":{"type":"string"},"tier":{"type":"string"},"count":{"type":"integer","minimum":0}}}},"tagCounts":{"type":"object","description":"Puzzles per trainer tag (every tag, zeros included) in the discoverable variant pool, before the motif and theme filters.","additionalProperties":{"type":"integer","minimum":0}}}}}}},"400":{"description":"`invalid_variant`, `invalid_motif`, `invalid_theme`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/puzzles/daily":{"get":{"tags":["Puzzles"],"summary":"Today’s puzzle","parameters":[{"name":"slot","in":"query","required":false,"schema":{"type":"string","enum":["homepage"],"default":"homepage"},"description":"The rotation slot."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"daily":{"type":"object","properties":{"day":{"type":"string","description":"YYYY-MM-DD"},"persisted":{"type":"boolean"},"selectedAt":{"type":["string","null"]},"slot":{"type":"string"},"source":{"type":"string"}}},"puzzle":{"$ref":"#/components/schemas/PuzzleDetail"}}}}}},"400":{"description":"`invalid_slot`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/puzzles/{id}":{"get":{"tags":["Puzzles"],"summary":"One puzzle","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"A puzzle id, or its short code."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"puzzle":{"$ref":"#/components/schemas/PuzzleDetail"}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/studies/public":{"get":{"tags":["Studies"],"summary":"Public studies","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":5},"description":"Rows."},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":2},"description":"Filter by name."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"studies":{"type":"array","items":{"$ref":"#/components/schemas/StudySummary"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/studies/{id}":{"get":{"tags":["Studies"],"summary":"One study with its chapters","description":"Public and unlisted studies answer; a private study is a 404 of the same shape.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Study id: the segment after `/study/`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"study":{"$ref":"#/components/schemas/StudySummary"},"chapters":{"type":"array","items":{"$ref":"#/components/schemas/Chapter"}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/xiangqi/explorer":{"get":{"tags":["Xiangqi"],"summary":"Opening explorer: what was played from a position","parameters":[{"name":"fen","in":"query","required":true,"schema":{"type":"string","maxLength":120},"description":"A standard xiangqi FEN, or just `<placement> <r|b>`. Only placement and side to move are read."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"position":{"type":"string"},"total":{"type":"integer"},"moves":{"type":"array","items":{"$ref":"#/components/schemas/ExplorerMove"}},"opening":{"type":["string","null"]},"topGames":{"type":"array","items":{"type":"object"},"maxItems":8},"build":{"type":["object","null"]}}}}}},"400":{"description":"`invalid_position`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/xiangqi/broadcasts":{"get":{"tags":["Xiangqi"],"summary":"Broadcast tournaments","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tours":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/xiangqi/broadcasts/{tourSlug}":{"get":{"tags":["Xiangqi"],"summary":"One tournament and its rounds","parameters":[{"name":"tourSlug","in":"path","required":true,"schema":{"type":"string"},"description":"The tour slug."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tour":{"type":"object"},"rounds":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/xiangqi/broadcasts/{tourSlug}/rounds/{roundId}":{"get":{"tags":["Xiangqi"],"summary":"One round and its boards","description":"Append `/events` for a server-sent-events stream of the same payload (`pollMs` 250 to 30000, default 1500).","parameters":[{"name":"tourSlug","in":"path","required":true,"schema":{"type":"string"},"description":"The tour slug."},{"name":"roundId","in":"path","required":true,"schema":{"type":"string"},"description":"The round id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tour":{"type":"object"},"round":{"type":"object"},"boards":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/xiangqi/broadcasts/boards/{boardId}":{"get":{"tags":["Xiangqi"],"summary":"One broadcast board, replayable","description":"Append `/events` for a server-sent-events stream, or `/export` for the moves as JSON.","parameters":[{"name":"boardId","in":"path","required":true,"schema":{"type":"string"},"description":"The board id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"board":{"type":"object"},"state":{"type":"object"},"timeline":{"type":"array","items":{"type":"object"}},"history":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/forum/categories":{"get":{"tags":["Forum"],"summary":"Forum categories","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/forum/topics":{"get":{"tags":["Forum"],"summary":"Topics, newest activity first","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"A category slug; omit for all."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Rows."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"description":"Skip this many."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"topics":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/forum/topics/{id}":{"get":{"tags":["Forum"],"summary":"One topic with its posts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Topic id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Posts per page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"description":"Skip this many posts."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"object"}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/forum/latest-posts":{"get":{"tags":["Forum"],"summary":"The latest posts across the forum","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":8},"description":"Rows."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/forum/search":{"get":{"tags":["Forum"],"summary":"Search posts","description":"A query shorter than 2 or longer than 120 characters returns an empty result, not an error.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120},"description":"Search text."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Rows."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0},"description":"Skip this many."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/coaches":{"get":{"tags":["Coaches"],"summary":"The coach directory","description":"Only published coaches who currently hold a verified title.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"coaches":{"type":"array","items":{"type":"object"}}}}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/coaches/{handle}":{"get":{"tags":["Coaches"],"summary":"One coach","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The coach’s handle."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"coach":{"type":"object"}}}}}},"404":{"description":"`coach_not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/oembed":{"get":{"tags":["Embeds"],"summary":"oEmbed provider for studies and games","description":"Turn a Mistboard link into an embeddable frame. Accepts a study chapter permalink, a game review permalink, or either embed path. See /developers for the frames themselves.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"The Mistboard URL to embed."},{"name":"maxwidth","in":"query","required":false,"schema":{"type":"integer"},"description":"Clamped into the range the widget works in."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Only `json` is offered."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OEmbed"}}}},"400":{"description":"`url_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_embeddable` (URL shape) or `not_found` (private, missing, or unfinished).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"`unsupported_format`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The database is unavailable (`persistence_disabled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/openapi.json":{"get":{"tags":["Embeds"],"summary":"This document","responses":{"200":{"description":"The OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"A snake_case code."}},"required":["error"]},"GameRecord":{"type":"object","description":"A finished game as the site lists it.","properties":{"roomId":{"type":"string"},"variant":{"type":"string","description":"A game spec id, e.g. `xiangqi`, `dark-chess`."},"mode":{"type":"string","enum":["pvp","pve","eve","imported","manual"]},"result":{"type":"string","description":"`red-wins`, `black-wins`, `white-wins`, `draw`, …"},"termination":{"type":"string"},"plyCount":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"whiteName":{"type":["string","null"],"description":"First seat (red in xiangqi)."},"blackName":{"type":["string","null"]},"corpusId":{"type":["string","null"]},"rated":{"type":"boolean"},"visibility":{"type":"string"},"timeControl":{"type":["object","null"]},"initialMs":{"type":["integer","null"]},"incrementMs":{"type":["integer","null"]},"participants":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"champions":{"type":"array","description":"Current champion ladders for a linkable human account; never internal account ids.","items":{"type":"object","required":["variant","timeClass"],"additionalProperties":false,"properties":{"variant":{"type":"string"},"timeClass":{"type":"string","enum":["bullet","blitz","rapid","correspondence"]}}}}}}}},"required":["roomId","variant","result","termination","plyCount"]},"PostgamePlayer":{"type":"object","properties":{"color":{"type":"string","description":"Seat token: `white` (first mover) or `black`."},"name":{"type":"string","description":"`Anonymous` for a seat its owner made private."},"rating":{"type":["integer","null"]},"kind":{"type":"string","enum":["account","guest","engine"]},"handle":{"type":["string","null"]},"botId":{"type":["string","null"]},"title":{"type":["string","null"]},"flair":{"type":["string","null"]},"champions":{"type":"array","description":"Current champion ladders for a linkable human account; never internal account ids.","items":{"type":"object","required":["variant","timeClass"],"additionalProperties":false,"properties":{"variant":{"type":"string"},"timeClass":{"type":"string","enum":["bullet","blitz","rapid","correspondence"]}}}}}},"PostgameGame":{"type":"object","description":"The finished-game envelope every per-variant postgame route shares.","properties":{"roomId":{"type":"string"},"variant":{"type":"string"},"mode":{"type":"string"},"result":{"type":"string"},"termination":{"type":"string"},"plyCount":{"type":"integer"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time"},"rated":{"type":"boolean"},"visibility":{"type":"string"},"initialMs":{"type":["integer","null"]},"incrementMs":{"type":["integer","null"]},"players":{"type":"array","items":{"$ref":"#/components/schemas/PostgamePlayer"}}}},"LeaderboardEntry":{"type":"object","properties":{"rank":{"type":"integer"},"handle":{"type":"string"},"displayName":{"type":"string"},"title":{"type":["string","null"]},"champions":{"type":"array","description":"Current champion ladders for a linkable human account; never internal account ids.","items":{"type":"object","required":["variant","timeClass"],"additionalProperties":false,"properties":{"variant":{"type":"string"},"timeClass":{"type":"string","enum":["bullet","blitz","rapid","correspondence"]}}}},"eloRating":{"type":"integer"},"gamesPlayed":{"type":"integer"},"provisional":{"type":"boolean"}}},"PuzzleSummary":{"type":"object","properties":{"id":{"type":"string"},"variant":{"type":"string","enum":["xiangqi","fortress-xiangqi","jungle"]},"title":{"type":"string"},"sideToMove":{"type":["string","null"],"enum":["red","black",null]},"goal":{"type":"object","properties":{"type":{"type":"string","enum":["checkmate","win","winning-advantage"]},"winner":{"type":"string"},"centipawns":{"type":"integer"}}},"themes":{"type":"array","items":{"type":"string"}},"motifs":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"},"description":"Trainer tags derived at load: kill patterns plus mate-in-N, phase, goal and length, followed by any stored player:<slug> provenance tags."},"solutionPlyCount":{"type":"integer"},"rating":{"type":"integer"},"ratingProvisional":{"type":"boolean"}}},"PuzzleDetail":{"allOf":[{"$ref":"#/components/schemas/PuzzleSummary"},{"type":"object","properties":{"initial":{"type":"object","description":"The variant’s full game state at the puzzle start."},"sourceGame":{"type":"object","description":"Attribution for mined puzzles."}}}],"description":"The solution is never included; it is revealed by a solving action."},"StudySummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"visibility":{"type":"string","enum":["public","unlisted"]},"featuredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"owner":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"}}},"chapterCount":{"type":"integer"},"chapterNames":{"type":"array","items":{"type":"string"}},"likeCount":{"type":"integer"}}},"Chapter":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"variant":{"type":"string"},"orientation":{"type":"string"},"root":{"type":"object","description":"The move tree: nested `children` of `{ uci, annotations }`."},"tags":{"type":"object"},"version":{"type":"integer"}}},"ExplorerMove":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"games":{"type":"integer"},"redWins":{"type":"integer"},"blackWins":{"type":"integer"},"draws":{"type":"integer"},"unknowns":{"type":"integer"}}},"OEmbed":{"type":"object","properties":{"type":{"type":"string","const":"rich"},"version":{"type":"string","const":"1.0"},"provider_name":{"type":"string"},"provider_url":{"type":"string"},"title":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"html":{"type":"string","description":"An `<iframe>` element."}}},"PlayStreak":{"type":"object","properties":{"current":{"type":"integer","description":"Days in the run that is still alive."},"best":{"type":"integer","description":"Longest run ever."},"lastPlayedDay":{"type":"string","nullable":true,"description":"YYYY-MM-DD of the last counted game on the requested calendar."},"today":{"type":"string","description":"YYYY-MM-DD the streak was computed for."}}}}}}