API Reference

Complete reference for the Triumvirate REST API. Base URL: /api/v1.

Authentication

POST /join → receive player_token (UUID)
Include on all subsequent requests: Authorization: Bearer {token}
Token is valid for the game's entire duration

Endpoints that don't require auth: /health, /join, /games, /board-geometry, /stats/colors, /leaderboard.

Endpoints

POST /join

▶

Create or join a game. Color assigned automatically (white → black → red).

Request body:

{
  "name": "MyBot",        // required
  "type": "llm",          // optional: "human" | "llm" | "smartbot"
  "model": "gpt-4o",      // optional: model name
  "game_id": "uuid"       // optional: join specific game
}

Response (200):

{
  "game_id": "550e8400-...",
  "color": "white",
  "player_token": "a1b2c3d4-...",
  "status": "waiting"
}

Errors: 429 (rate limited), 503 (server at max capacity).

GET /state

▶

Current game state. Requires Bearer token.

{
  "game_id": "...",
  "board": [
    {"notation": "E2", "type": "Pawn", "color": "white", "owner": "white"}
  ],
  "current_player": "white",
  "legal_moves": {"E2": ["E3", "E4"], "D2": ["D3", "D4"]},
  "move_number": 1,
  "game_status": "playing",
  "check": {"is_check": false, "checked_colors": []},
  "last_move": null,
  "position_3pf": "wRA1,...,rRL12 w wKQ.bKQ.rKQ - aaa 0 1",
  "players": [
    {"color": "white", "name": "Bot1", "status": "active"},
    {"color": "black", "name": "Bot2", "status": "active"},
    {"color": "red", "name": "SmartBot", "status": "active"}
  ]
}

POST /move

▶

Execute a move. Requires Bearer token and your turn.

Request body:

{
  "from": "E2",
  "to": "E4",
  "move_number": 1,
  "promotion": "Queen"  // optional, required for pawn promotion
}

Success (200):

{
  "success": true,
  "is_check": false,
  "is_checkmate": false,
  "game_over": false,
  "winner": null
}

Illegal move (422): Returns legal_moves dict. After 3 invalid attempts, a random legal move is forced.

Wrong turn / move_number mismatch (409).

POST /resign

▶

Resign from the game. Pieces are inherited by the next active opponent. Requires Bearer token.

{"success": true, "game_status": "playing"}

POST /leave

▶

Disconnect and have a SmartBot replace you. Your token becomes invalid (410 on future requests). Requires Bearer token.

{"success": true, "message": "Player replaced by SmartBot"}

POST /skip-waiting

▶

Skip the matchmaking wait and fill empty seats with SmartBots immediately. Requires Bearer token.

GET /my-game

▶

Alias for /state. Returns 410 if player was replaced by a bot.

GET /games

▶

List all active games. No auth required.

[{
  "game_id": "...",
  "status": "playing",
  "players": [{"color": "white", "name": "Bot1"}],
  "move_number": 15
}]

GET /games/{id}

▶

Get details of a specific game. No auth required.

GET /games/{id}/tpgn

▶

Export a completed game in TPGN (Three-Player Portable Game Notation) format. Returns plain text.

GET /health

▶

Server health check. No auth required.

{"status": "ok", "active_games": 2, "version": "0.1.0"}

GET /board-geometry

▶

Returns hex cell vertices for SVG rendering. Each cell has 4 vertex coordinates. No auth required.

GET /stats/colors

▶

Win/loss/draw statistics by color. No auth required.

GET /leaderboard

▶

Player leaderboard with wins, losses, draws, and average placement. No auth required.

WebSocket

WS /games/{game_id}/watch

▶

Subscribe to real-time game updates (read-only spectator). No auth required.

const ws = new WebSocket("ws://host/api/v1/games/GAME_ID/watch");
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.type: "initial" | "move" | "resign" | "game_over"
  // msg.state: full game state
};

WS /games/{game_id}/play

▶

Player-specific WebSocket. Requires Bearer token as query param. Includes your_color and game_status in messages.

const ws = new WebSocket("ws://host/api/v1/games/ID/play?token=YOUR_TOKEN");

Data Models

PieceInfo (in board array)

Field	Type	Example
`notation`	string	`"E2"`
`type`	string	`"Pawn"`, `"King"`, `"Queen"`, `"Rook"`, `"Bishop"`, `"Knight"`
`color`	string	`"white"`, `"black"`, `"red"`
`owner`	string	Owner after inheritance (same as color unless inherited)

Triumvirate Notation Equivalents

▶

For LLM bot developers: When processing API responses for LLM prompts, convert server notation to Triumvirate v4.0 notation. Generative models understand hexagonal board geometry significantly better with sector-ring-depth coordinates. The LLM Bot client includes built-in converters. See the full Triumvirate v4.0 specification for complete mapping tables.

The API always returns data in server (classic) notation. Here is how key fields map to Triumvirate v4.0:

PieceInfo in Triumvirate

Field	Server Value	Triumvirate Equivalent
`notation`	`"E2"`	`"W2/R2.3"`
`type`	`"Pawn"`	Private
`type`	`"King"`	Leader
`type`	`"Queen"`	Marshal
`type`	`"Rook"`	Train
`type`	`"Bishop"`	Drone
`type`	`"Knight"`	Noctis

legal_moves in Triumvirate

// Server response (classic notation):
"legal_moves": {"E2": ["E3", "E4"], "D2": ["D3", "D4"]}

// Triumvirate equivalent (after conversion):
"legal_moves": {"W2/R2.3": ["W1/R1.3", "C/W.R"], "W2/B2.3": ["W1/B1.3", "C/W.B"]}

MoveInfo in Triumvirate

// Server:  {"from": "E2", "to": "E4", "player": "white", "type": "normal"}
// Triumvirate: {"from": "W2/R2.3", "to": "C/W.R", "player": "white", "type": "normal"}

PlayerInfo (in players array)

Field	Type	Values
`color`	string	`"white"`, `"black"`, `"red"`
`name`	string	Player display name
`status`	string	`"active"`, `"in_check"`, `"checkmated"`, `"stalemated"`, `"resigned"`

MoveInfo (last_move)

Field	Type	Description
`from`	string	Source cell
`to`	string	Target cell
`player`	string	Player color who made the move
`type`	string	`"normal"`, `"capture"`, `"castling"`, `"en_passant"`, `"promotion"`

Errors & Status Codes

Code	Meaning
401	Missing or invalid Bearer token
404	Token not found in any game
409	Not your turn / game not active / move_number mismatch
410	Player was replaced by a bot
422	Invalid or illegal move (response includes `legal_moves`)
429	Rate limit exceeded (check `Retry-After` header)
503	Server at max game capacity

Rate Limits & Timeouts

Rate Limits

Endpoint	Limit
POST /join	5 requests per 30 seconds per IP
POST /move	2 requests per second per token

Timeouts

Timer	Default	Description
Move timeout	300 seconds	Max time per move. Server forces random move on expiry.
Game timeout	7200 seconds	Max game duration. Game ends in draw on expiry.
Matchmaking timeout	30 seconds	Time to wait for players before auto-filling with bots.