Skip to main content
All docs

API - Control Your Scoreboard Programmatically

REST API for Keepthescore.com sports scoreboards. Control scores, timers, and game state for basketball, baseball, football and more.

New here? Start with the quick start guide before you wire anything up.

The API lives at /api/v1/sport/. It lets you read and (for some sports) update sports scoreboards from your own code.

Sports with read & write support

These sports support both reads and writes:

  • Basketball - scores, fouls, timeouts, period, possession, timers
  • Baseball - scores, balls, strikes, outs, bases, innings, timers
  • Football (American) - scores, timeouts, quarter, downs, yards, possession, foul flag, 1st & 10 reset, timers
  • Hockey - scores, shots, penalties (add/clear, with penalty timers synced to the game clock), empty net, timeouts, period
  • Soccer - scores, period, possession, FINAL, reset
  • Volleyball - scores, sets, serve
  • Pickleball, Badminton, Squash - points, sets, serve / side-out, reset (one shared set-based namespace)

On a board that closes its sets automatically (every volleyball, squash, badminton and pickleball board created since October 2026, or an older one with the Setup switch on), a point that wins a set closes it and opens the next one in the same write, and the match ends once it is decided — exactly as the control panel does. A point on a closed set is not added: the API answers 200 with "Set N is over: the point was not added…"; take a point back with -1, reset the set or move the set to correct the score. A point on badminton's cap (30 by default) is refused the same way, and an amount that would cross the cap stops at it. Every request computes its write from a read inside a Firestore transaction, so a Stream Deck tap and a click in the control panel at set point land one after the other. - Universal - scores, fouls, timeouts, period, possession

Basketball, baseball and football have the deepest field coverage; the others cover core scoring plus a reset. Each sport's reference page lists the exact endpoints it exposes.

Read-only sports

Everything else is read-only for now. You can GET the scoreboard data, but you can't update it via the API. That covers Tennis, Softball, and the rest.

What you can do

Reads (every sport)

  • Pull the full scoreboard as JSON
  • Get current scores, timers, periods/innings, and game state
  • Read team names, colors, and logos
  • Pull all game stats and settings

Writes (the read/write sports above)

  • Set scores and game state
  • Run timers and shot clocks, including the short shot-clock reset (the FIBA 14-second rule)
  • Run the basketball timeout clock: start and stop it, load a full or a short timeout, correct the time
  • Handle sport-specific fields: innings, outs, downs, fouls, penalties, possession, and so on
  • Increment or decrement values, with the scorekeeping logic handled for you
  • Trigger the same on-board animations as the web control panel — goal celebrations, victory dances, 3-pointer flashes — when you score, subject to the board's own animation settings (API scoring respects the same show/threshold toggles as the control panel)

Getting access

The API authenticates with an account API key. A key belongs to your account, and you decide what it may do: one board or all your boards, read-only or full control, and when it expires. You can revoke it at any time.

Create a key

The quickest way is from the board itself:

  1. Open your scoreboard's control panel and choose More → Stream Deck & API.
  2. Click Create an API key for this board. Account settings open with this board selected and a one-year expiry.
  3. Give the key a label, pick a permission and create it.
  4. Copy the key. It starts with swk_ and is shown once.

You can also create keys in account settings, in the API keys section, and revoke them there. A revoked key stops working immediately.

Permission What the key can do
Admin Everything the board's admin link can do, including deleting the board. It can also create new boards — but only when the key covers All boards. A key limited to selected boards cannot create boards.
Scorekeeper Every Sports API call on the scoreboard: scores, clock, periods, fouls, possession and reset. Not board settings.
Read-only Read the scoreboard.

Find the board token

Requests name the board by its board token: eleven lowercase letters, for example tkzpfqvrwcb. The Stream Deck & API window shows it with a Copy button, and GET /api/v1/account/boards lists it as each board's board_token.

The Stream Deck and API window: the board token with a Copy button, the Create an API key for this board button, and the hidden Elgato Stream Deck token

A board token only names the board — without a key every request returns 403, and the key decides everything.

Send the key

Put the key in the Authorization header and the board token in the URL. Never put a key in a URL.

curl -X POST https://keepthescore.com/api/v1/sport/BOARD_TOKEN/basketball/home/points/increment \
  -H "Authorization: Bearer swk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2}'

Responses to a key never contain the board's own tokens or links built from them; each board carries its board_token instead. On a board endpoint, a wrong, expired or revoked key, or a board the key does not cover, returns 404, so a response never reveals whether a board exists. A valid key without the needed permission returns 403. On the account endpoints, a missing, expired or revoked key returns 401.

The board's own tokens — when headers are not an option

An API key with the board token is the recommended way to call the API: a key can be limited to one board, given a permission and an expiry, and revoked at any time.

But some webhook senders and automation tools can only call a URL and cannot add an Authorization header. For those, every board has three tokens of its own. Each is a link code that carries its permission in itself — put it in the URL in place of the board token and send no header:

Token Found in What it grants on its own
Board admin token the board's admin link (the Elgato Stream Deck token in the dialog) Full control, including deleting the board
Board restricted token the scorekeeper link Scorekeeping: read the scoreboard and every Sports API write
Board read token the read-only link Reading the scoreboard

Prefer the restricted or read token here, and never put the admin token in a URL you hand to another service: anyone who sees it owns the board. Unlike a key, these tokens cannot be limited, set to expire or revoked — the link grants its permission to anyone who has it.

Create and delete boards

Create a sports scoreboard with POST /api/v1/account/boards and a sport field (optional name and brand); the response has status 201 and includes the new board's board_token. Only an Admin key that covers all boards can create boards. Your plan's board limit and plan features apply as they do on the website. DELETE /api/v1/account/boards/{board_token} deletes a board and returns 204; it needs an Admin key that reaches that board.

What people build with it

Stream Deck control

Run the scoreboard from physical buttons without touching a laptop mid-game. The Stream Deck plugin does not use an API key: it takes the board's Elgato Stream Deck token, from the same Stream Deck & API window.

  • One-touch score updates
  • Dedicated timer buttons
  • Sport-specific actions like fouls, outs, and downs
  • Handy for streamers and scorekeepers

More here: Stream Deck Integration Guide

Custom integrations

Or roll your own:

  • Automated scoring from external data sources
  • Custom dashboards with your branding
  • Multi-board displays for tournaments
  • Integration with other sports software

Request bodies

Most write endpoints take no body at all — but the ones you'll reach for first do, and sending a bare POST to those gets you a 400. Three groups:

Increments need {"amount": <whole number>}. Scores, fouls, timeouts, outs, downs, periods — anything ending in /increment. Send a negative number to subtract; there is no separate decrement endpoint. Values stop at zero rather than going negative.

curl -X POST https://keepthescore.com/api/v1/sport/BOARD_TOKEN/basketball/home/points/increment \
  -H "Authorization: Bearer swk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2}'

Timer adjustments need {"amount": <whole number of seconds>} — /timer/adjust, /shotclock/adjust and /basketball/timeout-clock/adjust. Again, negative takes time off, and the clock stops at zero. These work whether the timer is running or paused.

curl -X POST https://keepthescore.com/api/v1/sport/BOARD_TOKEN/timer/adjust \
  -H "Authorization: Bearer swk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": -30}'

Everything else takes no body. Toggles (/possession/toggle, /timer/toggle, serve), resets, and the short shot-clock reset all work from a bare POST:

curl -X POST https://keepthescore.com/api/v1/sport/BOARD_TOKEN/basketball/possession/toggle \
  -H "Authorization: Bearer swk_YOUR_KEY"

One exception: hockey's add-penalty endpoint takes an optional {"duration": <seconds>, "number": "<player>"}. Omit it and you get a 2-minute penalty logged against player -1.

If a write comes back 400, read the message in the response — it names what was wrong (amount: Amount must be an integer, Request body must be a JSON object), which is usually a missing body or a number sent as a string. Each sport's reference page shows the body of every endpoint that takes one.

Rate limits

Every endpoint is rate-limited so one client can't flood a board:

  • Limit: 5 requests per second per board
  • Cooldown: 1 minute if you exceed it
  • Response code: 429 (Too Many Requests) when you're rate-limited

Handle 429 responses in your client. This matters most if you're polling or pushing updates fast.

CORS

Every response sends access-control-allow-origin: *, so you can call the API straight from a browser.

Note: Watch the trailing slash on routes when calling from CORS. Hit the wrong variant and the request will fail.

API reference

Each sport has its own reference page, generated from the live API. It lists every endpoint with its parameters, request body and responses. General covers the endpoints every sport shares.

Note: The API still gets new features and tweaks based on what users ask for, so check back if something you need is missing.

Machine-readable spec

The same reference is available as OpenAPI 3 at /apispec.json (also at /openapi.json), if you'd rather generate a client than read tables.

Try the endpoints in the browser

Open the interactive console

Heads up: the console sends real requests. Point it at a board you don't mind changing.

Stuck?

Got a question, a feature request, a bug, or just feedback? Email us at [email protected]. A real person reads it.