Data Shapes

The recurring JSON shapes referenced throughout the reference.

Principal

A participant’s identity. The single-key wrapper names the kind:

{ "Guest": { "id": "guest-uuid" } }
{ "User":  { "id": "user-uuid" } }
{ "Bot":   { "team": "anon", "name": "mybot" } }

In public, spectator-facing payloads (e.g. GET /games, players on a Snapshot) a participant is instead rendered as a public face — { "kind": "Bot", "name": "house greedy" } or { "kind": "Human", "name": null } — never a raw id.

TimeControl

{ "Unlimited": {} }
{ "SuddenDeath": { "initialSeconds": 180 } }
{ "Fischer": { "initialSeconds": 180, "incrementSeconds": 2 } }
{ "PerMove": { "secondsPerMove": 10 } }

Semantics are covered in Game Mechanics → Time controls. Clocks are enforced; the ladder always plays Fischer.

Clocks

Remaining time per side, in milliseconds, as of the carrying event:

{ "white": 180000, "black": 175000 }

null on Unlimited games. Appears on Snapshot.state and DiceRolled. The side to move keeps ticking after the event is sent, so subtract your own elapsed time locally.