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 it in the Share modal on your dashboard, under Developer API.

⚠️ 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.

Responses & limits

• 200 — success. 400 — bad request / no valid updates. 402 — the board owner isn't on a paid plan. 404 — invalid token or board not found.
• Rate limited to 120 requests per minute per token.
• Scores accept any finite number (including negatives and decimals).

Real-time

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