Reads are open. Writes need Authorization: Bearer <api-token>; the
dashboard shows your token while you are signed in. Sign-in is a browser
flow at /login, with GitHub. Times are unix
seconds. Errors are {"error":"why"} with status 400, or 401 when the
token is missing or bad.
GET /api/stateEverything the dashboard shows.
200: answers a State.
GET /api/gameOne game, replayable.
| Param | Type | |
|---|---|---|
| file | string | A history row's file plus ".moves" |
| n | integer | Game index within the file, from 0 |
200: answers a Game.
Refused with 400.
POST /api/submitSubmit an entry. Needs your token.
| Param | Type | |
|---|---|---|
| name | string | Your entry's ladder name. Yours once accepted. |
| kind | tarball |
Body (application/gzip): The entry source as .tar.gz: git archive HEAD:entries/example --format=tar.gz
200: Queued; poll /api/job, or watch your entries in /api/state.
| Field | Type | |
|---|---|---|
| job | integer | |
| queued | boolean |
Refused with 400, 401.
GET /api/jobOne submitted build.
| Param | Type | |
|---|---|---|
| id | integer | From /api/submit's answer |
200: answers a Job.
Refused with 400.
POST /api/tokenRotate your API token. The old token stops working immediately. Needs your token.
200: The fresh token.
| Field | Type | |
|---|---|---|
| token | string |
Refused with 401.
POST /api/logoutEnd the browser session.
302: Session cookie cleared, redirect to /.
GET /results/{file}Raw match records.
| Param | Type | |
|---|---|---|
| file | string | A .txt, .pgn or .moves filename that history names |
200: The file.
Refused with 404.
GET /api/engineOne engine's aggregate record.
| Param | Type | |
|---|---|---|
| name | string |
200: answers a EngineStats.
Refused with 400.
GET /api/playOne casual move against an engine. Replays moves from the start position and answers with the engine's reply. Rate-limited per address; positions are only reachable by playing to them. Never rated.
| Param | Type | |
|---|---|---|
| engine | string | |
| moves | string | Comma-separated UCI moves from the start position |
200: answers a PlayReply.
Refused with 400, 429.
| Field | Type | |
|---|---|---|
| book | Book | |
| leaderboard | Leaderboard | |
| history | [MatchRow] | |
| entries | [Submission] | Your entries and in-flight submissions, newest first; empty signed out |
| user | string? | |
| token | string? | |
| github_login | boolean | Whether GitHub sign-in is configured |
| Field | Type | |
|---|---|---|
| checksum | string | |
| openings | integer |
| Field | Type | |
|---|---|---|
| rows | [Standing] | |
| excluded | [string] | Result sets left out of the fit, with the reason |
| pairings | integer | |
| anchor | string? | The entry rated 0 |
| Field | Type | |
|---|---|---|
| name | string | |
| elo | number | |
| err | number | Half-width of the 95% interval; negative when it cannot be estimated |
| games | integer | |
| opponents | integer | |
| group | integer | 0 is the main group; other groups are not comparable with it |
| owner | string? | The submitter: a GitHub login, a ~guest, or null for house engines |
| submitted | integer? | When the standing build was accepted; resubmission resets it |
| Field | Type | |
|---|---|---|
| file | string | |
| a | string | |
| b | string | |
| games | integer | |
| cycles_a | integer | |
| cycles_b | integer | |
| score | number | Points percentage for a |
| elo | number? | Null when every game went one way |
| err | number | Negative when it cannot be estimated |
| book | string | |
| when | integer | |
| pgn | string? | Filename for /results/ |
| Field | Type | |
|---|---|---|
| id | integer | |
| state | queued | running | done | failed | |
| log | string | Live while running, final afterwards |
| Field | Type | |
|---|---|---|
| name | string | |
| state | queued | building | accepted | rejected | |
| when | integer | |
| bytes | integer? | The standing accepted build's size, when one exists |
| log | string? | The build log's tail: live while building, the reason when rejected |
| Field | Type | |
|---|---|---|
| result | 1-0 | 0-1 | 1/2-1/2 | * | |
| count | integer | Games in the file |
| frames | [Frame] | One per ply; frame 0 is the opening position |
| cycles | [integer] | Spent per ply; empty for old records |
| budget | integer | Cycles allowed per move |
| white | string? | Who has the white pieces; null for records the database no longer names |
| black | string? | |
| ended | string? | Why it ended: checkmate, a draw's reason, or the forfeit's; null for unfinished games |
| Field | Type | |
|---|---|---|
| fen | string | |
| san | string | Empty on frame 0 |
| from | integer | Square index, 0 = a1, 63 = h8; absent on frame 0 |
| to | integer | Absent on frame 0 |
| Field | Type | |
|---|---|---|
| name | string | |
| owner | string? | The submitter: a GitHub login, a ~guest, or null for house engines |
| submitted | integer? | When the standing build was accepted; resubmission resets it |
| rating | object? | Null while unrated |
| rank | integer? | Within the main group |
| of | integer | Rated engines in the main group |
| games | integer | |
| wins | integer | |
| draws | integer | |
| losses | integer | |
| avg_plies | number | |
| head_to_head | [HeadToHead] | |
| recent | [RecentMatch] | Newest first, at most 20 |
| Field | Type | |
|---|---|---|
| opponent | string | |
| games | integer | |
| score | number | This engine's share of the points, 0 to 1 |
| Field | Type | |
|---|---|---|
| opponent | string | |
| games | integer | |
| score | number | Percent, for this engine |
| when | integer | |
| file | string | Tag; append ".moves" for /api/game |
| Field | Type | |
|---|---|---|
| engine_move | string? | UCI; absent when the game was already over |
| san | string? | |
| cycles | integer? | What the move cost the engine |
| fen | string | |
| result | string? | Null while the game is ongoing |
| note | string? | Why the engine forfeited, when it did |
| check | boolean | Whether the side to move stands in check |
This page is rendered from openapi.json.