REST reference

Every REST endpoint with request params, response fields, and status codes. Matchmaking, bot games, presence and spectating are NOT here — they are socket messages (see WebSocket wire).

Index

bash

# Base path: /v1 — all server-to-server, IP whitelist + X-Service-Auth header.
# Every response uses the one envelope: { success, response, responseCode, data, error }.
# On failure data is null and error = { errorCode: "#<status>", errorMessage }.

Verb	Endpoint
GET	`/v1/game-types`
POST	`/v1/sessions`
POST	`/v1/tournaments (+ join · withdraw · start)`
GET	`/v1/tournaments · /v1/tournaments/{id}`
GET	`/v1/matches/{id}`
GET	`/v1/matches/{id}/review`
GET	`/v1/matches/results?since=`
GET	`/v1/puzzles/next`
POST	`/v1/puzzles/{id}/attempt`
GET	`<platform>/users/{userId} — hosted by YOU`

Game types

GET /v1/game-types

Catalog of variants + time controls — render your game-picker from it. No parameters.

http

GET /v1/game-types
X-Service-Auth: <secret>

# 200 — catalog the platform renders its "choose game" UI from
{
  "success": true, "response": "success", "responseCode": 200,
  "data": {
    "variants": ["standard"],
    "timeControls": [
      { "id": "bullet_1_0", "speed": "bullet", "base": 60,  "inc": 0, "label": "1 | 0" },
      { "id": "blitz_3_2",  "speed": "blitz",  "base": 180, "inc": 2, "label": "3 | 2" },
      { "id": "rapid_10_5", "speed": "rapid",  "base": 600, "inc": 5, "label": "10 | 5" }
    ]
  }
}

Response field	Type	Description
`variants`	`string[]`	available variants, e.g. "standard"
`timeControls[].id`	`string`	the id you pass to queue / play_bot / tournaments
`timeControls[].speed`	`"bullet" \| "blitz" \| "rapid"`	rating bucket the control belongs to
`timeControls[].base`	`number`	base clock in seconds
`timeControls[].inc`	`number`	increment per move in seconds
`timeControls[].label`	`string`	display label, e.g. "3 \| 2"

Sessions

POST /v1/sessions

Field	Type	Required	Default	Description
`userId`	string	yes	—	platform user id the token is minted for (opaque to the engine)

Response field	Type	Description
`token`	`string`	opaque session token — the client's socket credential for the whole login session
`expiresAt`	`string (Y-m-d H:i:s.v)`	token expiry; re-mint at the next login, not before

http

POST /v1/sessions
X-Service-Auth: <secret>

{ "userId": "user_123" }

# 201
{ "success": true, "response": "success", "responseCode": 201,
  "data": { "token": "s_9f3c...", "expiresAt": "2026-07-21 11:00:00.000" } }

# FAILS CLOSED: refuses to serve when the service secret is unconfigured.
# Minting again does not invalidate earlier tokens — the socket enforces one-per-user.

Tournaments

http

POST /v1/tournaments                 → 201 { data: { tournamentId } } · 422 unknown format
POST /v1/tournaments/{id}/join       → 200 { data: null } · 409 already in a tournament
POST /v1/tournaments/{id}/withdraw   → 200 { data: null }   (forfeits remaining games)
POST /v1/tournaments/{id}/start      → 200 { data: null }   (close registration + begin)
GET  /v1/tournaments                 → 200 tournaments still open for registration
GET  /v1/tournaments/{id}            → 200 config + standings + current round

POST /v1/tournaments

Field	Type	Required	Default	Description
`format`	string	yes	—	arena · swiss · round_robin · knockout (unsupported → 422)
`variant`	string	—	"standard"	one of the variants from GET /v1/game-types
`timeControl`	string	yes	—	a time-control id from GET /v1/game-types
`rated`	boolean	—	true	whether tournament games update Glicko-2
`rounds`	number	if swiss	ceil(log2(n))	number of Swiss rounds
`roundDeadlineSec`	number	—	0	per-round deadline in seconds; 0 = none
`allowMatchmakingDuringTournament`	boolean	—	false	false = exclusive (blocks the player's matchmaking while entered)
`arena`	object	if arena	—	{ durationMin } — minutes, capped 1..1440

POST /v1/tournaments/{id}/join

Field	Type	Required	Default	Description
`userId`	string	yes	—	participant
`rating`	object	if rated	—	{ r, rd, vol } for the tournament's (variant, speed)

GET /v1/tournaments

Response field	Type	Description
`tournaments[].tournamentId`	`string`	id
`tournaments[].format`	`string`	arena · swiss · round_robin · knockout
`tournaments[].variant / timeControl`	`string`	game type
`tournaments[].rated`	`boolean`	rated flag
`tournaments[].players`	`number`	current entrant count
`tournaments[].durationMin / rounds`	`number`	arena duration · swiss rounds (per format)

GET /v1/tournaments/{id}

Response field	Type	Description
`standings[].userId`	`string`	participant
`standings[].rank`	`number`	current rank (1-based)
`standings[].score`	`number`	points
`standings[].games`	`number`	games played

Matches

GET /v1/matches/{id}

http

GET /v1/matches/{id}
# 200 — history / state of one game
{
  "success": true, "response": "success", "responseCode": 200,
  "data": {
    "matchId": "match_abc", "status": "finished",
    "result": "white_win", "termination": "checkmate",
    "movesUci": ["e2e4","e7e5","d1h5","b8c6","f1c4","g8f6","h5f7"]
  }
}

Response field	Type	Description
`matchId`	`string`	id
`status`	`"active" \| "finished"`	live or done
`result`	`string`	white_win \| black_win \| draw \| aborted (finished only)
`termination`	`string`	how it ended — see Errors & codes for the full list
`movesUci`	`string[]`	full move list (UCI)

Game review

GET /v1/matches/{id}/review

http

GET /v1/matches/{id}/review
# First call starts async Stockfish generation:
#   202 { data: { status: "generating", matchId } }  → poll until 200
#   200 → the finished review (cached ~1d in Redis, stored permanently)
#   503 → analysis engine unavailable

Response field (data.*)	Type	Description
`engine / depth`	`string / number`	analyzer + depth (e.g. "Stockfish", 18)
`white / black`	`object`	per-player summary: { accuracy, estRating, counts }
`…accuracy`	`number`	0..100 — win%-model accuracy (heuristic, chess.com-style)
`…estRating`	`number`	estimated performance rating for this game (heuristic)
`…counts`	`object`	10 keys: brilliant · great · book · best · excellent · good · inaccuracy · mistake · miss · blunder
`moves[].ply`	`number`	1-based ply index
`moves[].by`	`"white" \| "black"`	side that moved
`moves[].uci / best`	`string`	the move played · the engine's best move
`moves[].cpWhite`	`number`	eval after the move, centipawns from White's view
`moves[].cpLoss`	`number`	centipawns given up vs the best move
`moves[].classification`	`string`	one of the 10 classes above
`evalGraph[]`	`object[]`	{ ply, cp } — plot-ready eval curve

ℹ accuracy / estRating / classification are heuristics (win%-model, chess.com-style) — an approximation, not a replica of any specific ladder.

Reconciliation

GET /v1/matches/results?since=<cursor>

http

GET /v1/matches/results?since=<cursor>&limit=200
# Reconciliation — finished game_result events ended after "since", oldest-first.
# since: unix ms (also "Y-m-d H:i:s.v" or RFC3339); empty = from the beginning.
# limit: default 200, max 1000.
{
  "success": true, "response": "success", "responseCode": 200,
  "data": { "results": [ { /* identical game_result payloads */ } ],
            "count": 12, "nextCursor": "1720429652000" } }

Puzzles

GET /v1/puzzles/next

Field	Type	Required	Default	Description
`rating`	number	—	1500	player's puzzle rating — drawn within ±300
`theme`	string	—	any	filter by theme; omit for any
`userId`	string	—	—	carried for tracking; selection is by rating + theme

Response field	Type	Description
`puzzleId`	`string`	id for the attempt calls
`fen`	`string`	position BEFORE the setup move
`setupMove`	`string`	opponent's setup move (UCI) — animate it, then the player solves
`rating`	`number`	the puzzle's rating
`themes`	`string[]`	the puzzle's themes

POST /v1/puzzles/{id}/attempt

Field	Type	Required	Default	Description
`userId`	string	yes	—	player attempting the solve
`ply`	number	yes	—	solution index being answered (1, 3, 5, …)
`uci`	string	yes	—	the move played (UCI)
`msTaken`	number	—	—	time spent (ms) — recorded, not rated
`rating`	object	if rated	—	{ r, rd, vol } overall puzzle rating; omit to record unrated
`themeRatings`	object	—	—	{ [theme]: { r, rd, vol } } per tracked theme

Response field	Type	Description
`correct`	`boolean`	this move matched the solution
`done`	`boolean`	the solve is over (finished or failed)
`solved`	`boolean`	the whole puzzle was solved correctly
`reply / nextPly`	`string / number`	mid-solve only: opponent's reply to animate + the next ply to answer
`rating`	`object`	first rated attempt only: { before, after, delta } for the overall puzzle rating
`themeRatings`	`object`	first rated attempt only: { [theme]: { before, after, delta } }

Hosted by you: GET /users/{userId}

The one endpoint the engine pulls — user detail + every rating category, at enqueue. Request carries no query parameters. The payload sits under a data envelope with snake_case keys (user_id); the engine unwraps it. Full behaviour in Platform setup.

Field	Type	Required	Default	Description
`data.user_id`	string	yes	—	echoed back (opaque to the engine)
`data.username / avatar / title`	string	—	omitted	display passthrough; username is placed on each match_found / game_state seat so clients render the opponent by name
`data.ratings`	object	yes	—	EVERY category, keyed "<variant>:<speed>" → { r, rd, vol, lastGameAt?, floor? }

Status codes

400 malformed payload · 401/403 service auth failure · 404 not found · 409 conflict (e.g. already in a game/tournament) · 422 validation (unknown game type / format) · 503 engine or analysis not ready. Full handling advice: Errors & codes.