API

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.

Site

Liveness and site-wide counts.

GET/api/pingTry it

Round-trip probe

No database, no allocations, cache-control: no-store.

200
OK
GET/api/live-statsTry it

How many people are playing and online

200
OK
GET/api/play/variant-orderTry it

Variants ordered by recent play

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.

200
OK
GET/api/players/onlineTry it

Players online now

At most 50 named players; count is the untruncated total. Private profiles are excluded.

200
OK
GET/api/stats/publicTry it

Site-wide game statistics

200
OK
503
The database is unavailable (persistence_disabled).

Games

Finished games. A game is public once it ends and never before.

GET/api/games/recentTry it

The ten most recent public games

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/games/showcaseTry it

Curated recent games across variants

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.

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/eve-games/recentTry it

Recent engine-versus-engine games

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/games/{roomId}Try it

One finished game

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.

ParameterInType
roomIdrequiredpathstringRoom id.
200
OK
404
Not found (not_found).
GET/api/games/{roomId}/eventsTry it

The event log of a finished game

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.

ParameterInType
roomIdrequiredpathstringRoom id.
200
OK
403
The game is not public yet (game_not_public).
404
Not found (not_found).
GET/api/games/{roomId}/export.pgnTry it

A finished game as PGN

ParameterInType
roomIdrequiredpathstringRoom id.
200
The PGN text, content-disposition: inline.
403
game_not_public
404
Not found (not_found).
501
export_not_supported_for_variant
GET/api/games/{roomId}/export.jsonTry it

A finished game as JSON

ParameterInType
roomIdrequiredpathstringRoom id.
200
The export document.
403
game_not_public
404
Not found (not_found).
501
export_not_supported_for_variant
GET/api/games/{roomId}/crosstableTry it

Head-to-head record of the two players

A 200 with { available: false, reason } when the seats do not resolve to a rated pair.

ParameterInType
roomIdrequiredpathstringRoom id.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/{variant}/games/{roomId}Try it

A finished game with its per-ply views

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.

ParameterInType
variantrequiredpathstringA game spec id with a review route, e.g. xiangqi.
roomIdrequiredpathstringRoom id.
200
OK
404
Not found (not_found).

Watch

The feeds Mistboard TV and /watch read.

GET/api/watchTry it

A watch channel: its finished games and the rail

ParameterInType
channelqueryone 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.
curatedqueryone of 00 lists the full feed without the 20-ply bar the Featured channel applies (what /games "Just finished" shows).
200
OK
404
unknown_watch_channel
503
The database is unavailable (persistence_disabled).
GET/api/watch/liveTry it

The featured live game of a channel

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.

ParameterInType
channelqueryone 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.
roomquerystringThe room you are following.
plyqueryinteger (>= 0)The ply you last rendered.
200
OK
404
unknown_watch_channel

Ratings

The rating ladders.

GET/api/leaderboardTry it

One rating ladder

ParameterInType
variantquerystring (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.
timeClassqueryone of bullet, blitz, rapid (default blitz)Which clock class.
limitqueryinteger (1..500, default 100)Rows.
200
OK
400
invalid_rating_time_class
503
The database is unavailable (persistence_disabled).
GET/api/leaderboard/summaryTry it

The top of every ladder, plus active players

ParameterInType
timeClassqueryone of bullet, blitz, rapid (default blitz)Which clock class.
limitqueryinteger (1..50, default 10)Rows per ladder.
200
OK
400
invalid_rating_time_class
503
The database is unavailable (persistence_disabled).

Players

Public profiles.

GET/api/users/{handle}/profileTry it

A player’s public profile

Private profiles are 404. Signed-in viewers also get a relation field; anonymous callers get null.

ParameterInType
handlerequiredpathstringThe player’s handle.
tzquerystringIANA time zone the streak days are counted on (default UTC).
200
OK
400
invalid_handle
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/users/{handle}/gamesTry it

A player’s public games, paged

ParameterInType
handlerequiredpathstringThe player’s handle.
offsetqueryinteger (>= 0, default 0)Skip this many.
limitqueryinteger (1..50, default 15)Page size.
beforequerystringJSON [endedAt, roomId] from the last row. Lists strictly older games; overrides offset.
variantquerystringRating pool, e.g. xiangqi, or casual activity spec ffq-banqi; unknown values list every variant.
resultqueryone of win, loss, drawResult from this player’s seat.
vsquerystringOpponent handle (case-insensitive, exact).
200
OK
400
invalid_handle, invalid_result, invalid_opponent, invalid_before
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/users/{handle}/rating-historyTry it

A player’s rating over time in one pool

ParameterInType
handlerequiredpathstringThe player’s handle.
variantrequiredquerystringA rating pool (see the leaderboard).
timeClassqueryone of bullet, blitz, rapid (default blitz)Which clock class.
200
OK
400
invalid_handle, invalid_rating_variant or invalid_rating_time_class
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).

Bots

Engines a player can be offered.

GET/api/botsTry it

Every bot 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.

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/bots/{id}Try it

One bot

ParameterInType
idrequiredpathstringBot id.
200
OK
400
invalid_bot_id
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/engines/playableTry it

Engines available for fog chess play

200
OK

Puzzles

The puzzle trainer.

GET/api/puzzlesTry it

The puzzle list

Signed-in callers also get attemptedIds; anonymous callers get an empty list there.

ParameterInType
variantqueryone of xiangqi, jungleRestrict to one variant; omit for all.
motifqueryone 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-jiangRestrict to a named xiangqi mating pattern. Intersects variant; omit or leave empty for all.
themequeryone 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-longRestrict to any trainer tag: a mating pattern, mate-in-N, phase, goal or length. Intersects variant and motif.
playerquerystringCanonical 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.
200
OK
400
invalid_variant, invalid_motif, invalid_theme
GET/api/puzzles/dailyTry it

Today’s puzzle

ParameterInType
slotqueryone of homepage (default homepage)The rotation slot.
200
OK
400
invalid_slot
GET/api/puzzles/{id}Try it

One puzzle

ParameterInType
idrequiredpathstringA puzzle id, or its short code.
200
OK
404
Not found (not_found).

Studies

Public studies and their chapters.

GET/api/studies/publicTry it

Public studies

ParameterInType
limitqueryinteger (1..50, default 5)Rows.
qquerystringFilter by name.
200
OK
503
The database is unavailable (persistence_disabled).
GET/api/studies/{id}Try it

One study with its chapters

Public and unlisted studies answer; a private study is a 404 of the same shape.

ParameterInType
idrequiredpathstringStudy id: the segment after /study/.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).

Xiangqi

The opening explorer and tournament broadcasts.

GET/api/xiangqi/explorerTry it

Opening explorer: what was played from a position

ParameterInType
fenrequiredquerystringA standard xiangqi FEN, or just <placement> <r|b>. Only placement and side to move are read.
200
OK
400
invalid_position
503
The database is unavailable (persistence_disabled).
GET/api/xiangqi/broadcastsTry it

Broadcast tournaments

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/xiangqi/broadcasts/{tourSlug}

One tournament and its rounds

ParameterInType
tourSlugrequiredpathstringThe tour slug.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/xiangqi/broadcasts/{tourSlug}/rounds/{roundId}

One round and its boards

Append /events for a server-sent-events stream of the same payload (pollMs 250 to 30000, default 1500).

ParameterInType
tourSlugrequiredpathstringThe tour slug.
roundIdrequiredpathstringThe round id.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/xiangqi/broadcasts/boards/{boardId}

One broadcast board, replayable

Append /events for a server-sent-events stream, or /export for the moves as JSON.

ParameterInType
boardIdrequiredpathstringThe board id.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).

Forum

Forum reads.

GET/api/forum/categoriesTry it

Forum categories

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/forum/topicsTry it

Topics, newest activity first

ParameterInType
categoryquerystringA category slug; omit for all.
limitqueryinteger (1..50, default 20)Rows.
offsetqueryinteger (0..10000, default 0)Skip this many.
200
OK
503
The database is unavailable (persistence_disabled).
GET/api/forum/topics/{id}Try it

One topic with its posts

ParameterInType
idrequiredpathstringTopic id.
limitqueryinteger (1..100)Posts per page.
offsetqueryinteger (0..10000, default 0)Skip this many posts.
200
OK
404
Not found (not_found).
503
The database is unavailable (persistence_disabled).
GET/api/forum/latest-postsTry it

The latest posts across the forum

ParameterInType
limitqueryinteger (1..20, default 8)Rows.
200
OK
503
The database is unavailable (persistence_disabled).

Coaches

The coach directory.

GET/api/coachesTry it

The coach directory

Only published coaches who currently hold a verified title.

200
OK
503
The database is unavailable (persistence_disabled).
GET/api/coaches/{handle}Try it

One coach

ParameterInType
handlerequiredpathstringThe coach’s handle.
200
OK
404
coach_not_found
503
The database is unavailable (persistence_disabled).

Embeds

oEmbed and this document.

GET/api/oembedTry it

oEmbed provider for studies and games

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.

ParameterInType
urlrequiredquerystringThe Mistboard URL to embed.
maxwidthqueryintegerClamped into the range the widget works in.
formatqueryone of jsonOnly json is offered.
200
OK
400
url_required
404
not_embeddable (URL shape) or not_found (private, missing, or unfinished).
501
unsupported_format
503
The database is unavailable (persistence_disabled).
GET/api/openapi.jsonTry it

This document

200
The OpenAPI 3.1 document.