Round-trip probe
No database, no allocations, cache-control: no-store.
- 200
- OK
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.
Errors 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.
The document itself is OpenAPI 3.1 at /api/openapi.json, for Scalar, Redoc, or a client generator. Boards you can put in your own page are on the developers page.
Liveness and site-wide counts.
No database, no allocations, cache-control: no-store.
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.
At most 50 named players; count is the untruncated total. Private profiles are excluded.
persistence_disabled).Finished games. A game is public once it ends and never before.
persistence_disabled).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.
persistence_disabled).persistence_disabled).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.
| Parameter | In | Type | |
|---|---|---|---|
roomIdrequired | path | string | Room id. |
not_found).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.
| Parameter | In | Type | |
|---|---|---|---|
roomIdrequired | path | string | Room id. |
game_not_public).not_found).| Parameter | In | Type | |
|---|---|---|---|
roomIdrequired | path | string | Room id. |
content-disposition: inline.game_not_publicnot_found).export_not_supported_for_variant| Parameter | In | Type | |
|---|---|---|---|
roomIdrequired | path | string | Room id. |
game_not_publicnot_found).export_not_supported_for_variantA 200 with { available: false, reason } when the seats do not resolve to a rated pair.
| Parameter | In | Type | |
|---|---|---|---|
roomIdrequired | path | string | Room id. |
not_found).persistence_disabled).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.
| Parameter | In | Type | |
|---|---|---|---|
variantrequired | path | string | A game spec id with a review route, e.g. xiangqi. |
roomIdrequired | path | string | Room id. |
not_found).The feeds Mistboard TV and /watch read.
| Parameter | In | Type | |
|---|---|---|---|
channel | query | one of top, xiangqi, banqi, jieqi, fortress-xiangqi, dark-xiangqi, duck-xiangqi, atomic-xiangqi, crazyhouse-xiangqi, dark-chess, jungle, jungle-flip, gomoku, engines (default top) | Which channel. The set is what /watch offers and can change as variants launch. |
curated | query | one of 0 | 0 lists the full feed without the 20-ply bar the Featured channel applies (what /games "Just finished" shows). |
unknown_watch_channelpersistence_disabled).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.
| Parameter | In | Type | |
|---|---|---|---|
channel | query | one of top, xiangqi, banqi, jieqi, fortress-xiangqi, dark-xiangqi, duck-xiangqi, atomic-xiangqi, crazyhouse-xiangqi, dark-chess, jungle, jungle-flip, gomoku, engines (default top) | Which channel. |
room | query | string | The room you are following. |
ply | query | integer (>= 0) | The ply you last rendered. |
unknown_watch_channelThe rating ladders.
| Parameter | In | Type | |
|---|---|---|---|
variant | query | string (default fog) | A rating pool: xiangqi, jieqi, banqi, fog (fog chess), dark_xiangqi, jungle, jungle_flip, fortress_xiangqi, … (underscores). A game spec id is accepted too. |
timeClass | query | one of bullet, blitz, rapid (default blitz) | Which clock class. |
limit | query | integer (1..500, default 100) | Rows. |
invalid_rating_time_classpersistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
timeClass | query | one of bullet, blitz, rapid (default blitz) | Which clock class. |
limit | query | integer (1..50, default 10) | Rows per ladder. |
invalid_rating_time_classpersistence_disabled).Public profiles.
Private profiles are 404. Signed-in viewers also get a relation field; anonymous callers get null.
| Parameter | In | Type | |
|---|---|---|---|
handlerequired | path | string | The player’s handle. |
tz | query | string | IANA time zone the streak days are counted on (default UTC). |
invalid_handlenot_found).persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
handlerequired | path | string | The player’s handle. |
offset | query | integer (>= 0, default 0) | Skip this many. |
limit | query | integer (1..50, default 15) | Page size. |
before | query | string | JSON [endedAt, roomId] from the last row. Lists strictly older games; overrides offset. |
variant | query | string | Rating pool, e.g. xiangqi, or casual activity spec ffq-banqi; unknown values list every variant. |
result | query | one of win, loss, draw | Result from this player’s seat. |
vs | query | string | Opponent handle (case-insensitive, exact). |
invalid_handle, invalid_result, invalid_opponent, invalid_beforenot_found).persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
handlerequired | path | string | The player’s handle. |
variantrequired | query | string | A rating pool (see the leaderboard). |
timeClass | query | one of bullet, blitz, rapid (default blitz) | Which clock class. |
invalid_handle, invalid_rating_variant or invalid_rating_time_classnot_found).persistence_disabled).Engines a player can be offered.
The one source that knows what a player is offered: each bot with the specs it can play right now.
persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
idrequired | path | string | Bot id. |
invalid_bot_idnot_found).persistence_disabled).The puzzle trainer.
Signed-in callers also get attemptedIds; anonymous callers get an empty list there.
| Parameter | In | Type | |
|---|---|---|---|
variant | query | one of xiangqi, jungle | Restrict to one variant; omit for all. |
motif | query | one of 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 | Restrict to a named xiangqi mating pattern. Intersects variant; omit or leave empty for all. |
theme | query | one of 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 | Restrict to any trainer tag: a mating pattern, mate-in-N, phase, goal or length. Intersects variant and motif. |
player | query | string | 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. |
invalid_variant, invalid_motif, invalid_theme| Parameter | In | Type | |
|---|---|---|---|
slot | query | one of homepage (default homepage) | The rotation slot. |
invalid_slot| Parameter | In | Type | |
|---|---|---|---|
idrequired | path | string | A puzzle id, or its short code. |
not_found).Public studies and their chapters.
| Parameter | In | Type | |
|---|---|---|---|
limit | query | integer (1..50, default 5) | Rows. |
q | query | string | Filter by name. |
persistence_disabled).Public and unlisted studies answer; a private study is a 404 of the same shape.
| Parameter | In | Type | |
|---|---|---|---|
idrequired | path | string | Study id: the segment after /study/. |
not_found).persistence_disabled).The opening explorer and tournament broadcasts.
| Parameter | In | Type | |
|---|---|---|---|
fenrequired | query | string | A standard xiangqi FEN, or just <placement> <r|b>. Only placement and side to move are read. |
invalid_positionpersistence_disabled).persistence_disabled)./api/xiangqi/broadcasts/{tourSlug}| Parameter | In | Type | |
|---|---|---|---|
tourSlugrequired | path | string | The tour slug. |
not_found).persistence_disabled)./api/xiangqi/broadcasts/{tourSlug}/rounds/{roundId}Append /events for a server-sent-events stream of the same payload (pollMs 250 to 30000, default 1500).
| Parameter | In | Type | |
|---|---|---|---|
tourSlugrequired | path | string | The tour slug. |
roundIdrequired | path | string | The round id. |
not_found).persistence_disabled)./api/xiangqi/broadcasts/boards/{boardId}Append /events for a server-sent-events stream, or /export for the moves as JSON.
| Parameter | In | Type | |
|---|---|---|---|
boardIdrequired | path | string | The board id. |
not_found).persistence_disabled).Forum reads.
persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
category | query | string | A category slug; omit for all. |
limit | query | integer (1..50, default 20) | Rows. |
offset | query | integer (0..10000, default 0) | Skip this many. |
persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
idrequired | path | string | Topic id. |
limit | query | integer (1..100) | Posts per page. |
offset | query | integer (0..10000, default 0) | Skip this many posts. |
not_found).persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
limit | query | integer (1..20, default 8) | Rows. |
persistence_disabled).A query shorter than 2 or longer than 120 characters returns an empty result, not an error.
| Parameter | In | Type | |
|---|---|---|---|
qrequired | query | string | Search text. |
limit | query | integer (1..50, default 20) | Rows. |
offset | query | integer (0..10000, default 0) | Skip this many. |
persistence_disabled).The coach directory.
Only published coaches who currently hold a verified title.
persistence_disabled).| Parameter | In | Type | |
|---|---|---|---|
handlerequired | path | string | The coach’s handle. |
coach_not_foundpersistence_disabled).oEmbed and this document.
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.
| Parameter | In | Type | |
|---|---|---|---|
urlrequired | query | string | The Mistboard URL to embed. |
maxwidth | query | integer | Clamped into the range the widget works in. |
format | query | one of json | Only json is offered. |
url_requirednot_embeddable (URL shape) or not_found (private, missing, or unfinished).unsupported_formatpersistence_disabled).