REST API Reference

Returns all API keys for the club (active and revoked). Raw key values are never returned — only the prefix and metadata. Requires manager session for the same club.

[
  {
    "id": 1,
    "label": "TV Display Screen",
    "key_prefix": "sk_ABCD",
    "is_active": true,
    "last_used_at": "2026-04-17T10:22:00",
    "created_at": "2026-04-01T09:00:00"
  }
]

Creates a new API key for the club. The full raw key is returned once only — store it securely. Subsequent calls to list keys will only show the prefix.

{
  "success": true,
  "id": 1,
  "key": "sk_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
  "key_prefix": "sk_AbCdEf"
}

Marks the key as inactive. Any requests using the revoked key will immediately receive 401. Requires manager session for the same club.

{ "success": true }

Returns the current scoring state for the given table. Requires manager session or API key — club is identified automatically from auth.

{
  "players": [{"name": "Alice", "club": "TRSCL", "nationality": "GB"}, {...}],
  "player_ids": [3, 7],
  "current_player": 0,
  "frames_won": [2, 1],
  "current_frame": {
    "points": [47, 12],
    "current_break": 23,
    "reds_remaining": 8
  },
  "game_mode": "frames",
  "current_match_id": 42
}

Returns the raw internal game-state dict for the given table. Includes undo history, frame stats, and all internal counters. Club is identified from auth. Use /api/state/{table_id} for the leaner client-formatted state.

Adds points to the current player's break. Returns the updated game state.

Awards foul points to the non-offending player.

Ends the current player's visit and transfers play to the other player.

Steps back one entry in the undo history. Returns 400 if nothing to undo.

Finalises the current frame, records the winner, and starts a new frame. If the match target is reached the match is completed and persisted.

Clears all live state for the table. Any in-progress match is finalised and closed in the database.

Sets player names, clubs, nationalities and optionally links to database player records. Call before the first frame is scored. A match record is created lazily when the first frame ends.

[
  { "id": 3, "name": "Alice", "nationality": "GB", "is_active": true, "sort_order": 0 }
]

Partial update — only provided fields are changed.

Permanently removes the player record. Returns 404 if not found.

Sets the display order for a list of players in bulk.

Returns the live status of every active table. The primary endpoint for public display screens. Club is identified from auth.

{
  "club_id": 5,
  "club_name": "TRSCL",
  "session_high_break": 63,
  "tables": [
    {
      "scoreboard_id": 1,
      "table_name": "Table 1",
      "status": "live",
      "player1": { "name": "Alice", "frames": 2, "points": 47 },
      "player2": { "name": "Bob",   "frames": 1, "points": 12 },
      "match_start": "2026-04-17T09:12:00"
    },
    {
      "scoreboard_id": 2,
      "table_name": "Table 2",
      "status": "idle"
    }
  ]
}

Returns all recorded matches for a player, with frame wins/losses and high breaks. Matches with no completed frames are excluded.

Returns the most recent completed matches for a club, newest first. Club is identified from auth.

Returns complete frame-by-frame detail for a single match including player names, points per frame, breaks, and high breaks.

Returns all tournaments for the club identified from auth.

Returns the full bracket/group results for a tournament. Used by the public results wall display.

Returns the highest breaks achieved during a tournament, sorted descending. Used by the high breaks display screen.

Returns 200 with DB and Redis status when healthy, 500 on error. Use for uptime monitoring.

{ "status": "healthy", "db": "ok", "redis": "ok" }