Leaderboard Developer API

Read a board's standings and push score updates from your own code: a game, an app, a spreadsheet script, or a server job. Updates appear on the live board, embeds, and TV view in real time.

Requirements

The API is available on the Pro and Premium plans. Upgrade if you're on the Free plan.

Authentication

There are no separate API keys. Each board is accessed with its admin token, which you pass directly in the URL path. Find the full address in the board editor under Share → Editing access → Developer API. If editing access is turned off, click Create a management link there first: the API uses the same token, so regenerating or turning off that link changes or disables the API address too.

⚠️ Treat the token like a password: anyone who has it can update your board. Don't embed it in public client-side code.

Endpoints

Get the board & standings

GET /api/v1/<admin_token>

curl https://maketheboard.com/api/v1/<admin_token>

Returns board metadata and the ranked standings:

{
  "board": {
    "id": 123,
    "title": "Sales Leaderboard",
    "board_type": "leaderboard",
    "share_slug": "abc123",
    "sort_order": "desc",
    "participant_count": 5
  },
  "standings": [
    { "rank": 1, "participant_id": 12, "name": "Alex", "score": 48200 },
    { "rank": 2, "participant_id": 13, "name": "Jordan", "score": 41750 }
  ]
}

Get standings only

GET /api/v1/<admin_token>/standings

Update scores

POST /api/v1/<admin_token>/scores

Identify a participant by participant (name, case-insensitive) or participant_id. Set an absolute value with score, or adjust the current score with delta.

Single update, add 5 points to Alex:

curl -X POST https://maketheboard.com/api/v1/<admin_token>/scores \
  -H "Content-Type: application/json" \
  -d '{"participant":"Alex","delta":5}'

Set an absolute score:

curl -X POST https://maketheboard.com/api/v1/<admin_token>/scores \
  -H "Content-Type: application/json" \
  -d '{"participant_id":12,"score":100}'

Batch update, many participants in one call:

curl -X POST https://maketheboard.com/api/v1/<admin_token>/scores \
  -H "Content-Type: application/json" \
  -d '{"scores":[
        {"participant":"Alex","score":100},
        {"participant":"Jordan","delta":-1}
      ]}'

The response returns the updated standings and any per-item errors:

{
  "updated": 2,
  "standings": [ ... ],
  "errors": [
    { "index": 2, "error": "Participant not found", "item": { "participant": "Nobody" } }
  ]
}

Participants are matched, never created. Add players from the dashboard first, then push their scores by name or id. A batch is applied item by item: the good ones save even when others fail.

Which boards it works with

Use the API with leaderboards and goal trackers. A scoresheet adds up its round scores, so a total pushed through the API is replaced the next time a round score changes; a Google Sheet board is replaced on its next sync. Brackets, tier lists and leagues don't use a single score.

Responses & limits

• 200: success (at least one update saved). 400: bad request, or no update in the call saved. 402: the board owner isn't on a paid plan. 404: invalid token or board not found. 429: rate limit hit; wait for the Retry-After seconds.
• Rate limited to 120 requests per minute per token, and up to 500 score items per call. Use one batch call rather than a call per participant.
• Scores accept any finite number (including negatives and decimals).

Use it from an AI assistant

The same token also works as an MCP server, so Claude, ChatGPT, Cursor or Claude Code can read the board and update scores when you ask. See connecting a leaderboard to an AI assistant. Agents can read this whole reference as plain markdown at /developers.md.

Real-time

Every successful score update broadcasts to anyone viewing the board, its embed, or the TV display, no refresh needed.