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. The full reference below lists the exact endpoints each sport 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)
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:

Open your scoreboard's control panel and choose More → Stream Deck & API.
Click Create an API key for this board. Account settings open with this board selected and a one-year expiry.
Give the key a label, pick a permission and create it.
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.

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 and /shotclock/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 (Request body must be a JSON object, Amount must be an integer), which is usually a missing body or a number sent as a string.

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

The full reference is below, generated from the live API.

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

In the reference, {token} is a board token when you send an API key, or one of the board's own tokens without one.

General

GET /api/v1/account/boards

List the boards this key reaches, newest first.

Responses

Status	Meaning	Body
`200`	OK	BoardList
`401`	Missing, invalid, expired or revoked key	—
`429`	Too many requests	—

Response body (200) — BoardList (JSON)

Field	Type	Always present	Description
`boards`	array of BoardSummary	no	Newest first.

POST /api/v1/account/boards

Create a board from a template or a blank sport scoreboard.

Body: exactly one of `template_slug` or `sport`; optional `brand` (sport only, defaults to the brand of the host called), `name`, and `participants` (`[{"name": str, "score"?: number}]`, LEADERBOARD only), which replace the template's demo participants. A `participants` list is never empty and holds at most the plan's participant limit; a per-call cap also applies, and the error names the limit. A longer list refuses the whole create. Needs an admin key that reaches all boards.

Responses

Status	Meaning	Body
`201`	Created	BoardCreated
`400`	Invalid request	—
`401`	Missing, invalid, expired or revoked key	—
`403`	The key cannot create boards	—
`409`	Board quota used up, plan feature missing, or a board created seconds ago	—
`429`	Too many requests	—
`503`	The board store did not answer; no board was created	—

Response body (201) — BoardCreated (JSON)

Field	Type	Always present	Description
`board`	object	no	The new board, as the list returns it.

DELETE /api/v1/account/boards/{board_token}

Delete a board. Needs a key with the admin permission.

Path parameters

Name	Type	Required	Description
`board_token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`401`	Missing, invalid, expired or revoked key	—
`403`	The key cannot delete boards	—
`404`	Board not found	—
`429`	Too many requests	—

GET /api/v1/sport/{token}/

Return all sport scoreboard data as JSON.

Path parameters

Name	Type	Required	Description
`token`	string	yes	The token of the board to retrieve.

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

GET /api/v1/templates/

List the templates a board can be created from. No key needed.

Responses

Status	Meaning	Body
`200`	OK	TemplateList
`429`	Too many requests	—

Response body (200) — TemplateList (JSON)

Field	Type	Always present	Description
`templates`	array of Template	no	In gallery order.

Baseball

POST /api/v1/sport/{token}/baseball/away/runs/increment

Increment away team runs for baseball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/balls/increment

Increment balls count for baseball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/base/1/toggle

Toggle runner on first base.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/base/2/toggle

Toggle runner on second base.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/base/3/toggle

Toggle runner on third base.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/count/reset

Reset balls and strikes to zero.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/final/toggle

Toggle the FINAL state of a baseball scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/home/runs/increment

Increment home team runs for baseball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/outs/increment

Increment outs count for baseball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/reset

Reset all game state to initial values for a new baseball game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/baseball/strikes/increment

Increment strikes count for baseball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Basketball

POST /api/v1/sport/{token}/basketball/away/bonus/toggle

Toggle bonus for away team in basketball.

When show_double_bonus is enabled on the board, this cycles through three states: no bonus -> bonus -> double bonus -> no bonus When show_double_bonus is disabled, this performs a simple toggle: no bonus <-> bonus If double_bonus is active and the bonus is toggled off, double_bonus is also turned off.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/basketball/away/fouls/increment

Increment away team fouls for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/away/points/increment

Increment away team points for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/away/timeouts/increment

Increment away team timeouts for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/final/toggle

Toggle the FINAL state of a basketball scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/home/bonus/toggle

Toggle bonus for home team in basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/basketball/home/fouls/increment

Increment home team fouls for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/home/points/increment

Increment home team points for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/home/timeouts/increment

Increment home team timeouts for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/period/increment

Increment period for basketball.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/possession/toggle

Toggle possession between home and away teams.

When toggling possession, one team gets possession and the other loses it.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/basketball/reset

Reset all game state to initial values for a new basketball game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Football

POST /api/v1/sport/{token}/football/away/possession/toggle

Toggle away team possession for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/away/score/increment

Increment away team score for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/away/timeouts/increment

Increment away team timeouts for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/downs/increment

Increment downs for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/final/toggle

Toggle the FINAL state of a football scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/first-down-reset

Reset down and distance to 1st & 10 in a single atomic update.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/flag/toggle

Toggle the foul/flag indicator on a football scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/home/possession/toggle

Toggle home team possession for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/home/score/increment

Increment home team score for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/home/timeouts/increment

Increment home team timeouts for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/quarter/increment

Increment quarter for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/reset

Reset all game state to initial values for a new football game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/football/yards/increment

Increment yards to go for football.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Hockey

POST /api/v1/sport/{token}/hockey/away/empty_net/toggle

Toggle away team empty net for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/away/penalty/add

Add a penalty for away team in hockey.

Body: {duration: seconds (default 120), number: player number (default "")}

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/hockey/away/penalty/clear

Clear the oldest penalty for away team in hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/hockey/away/score/increment

Increment away team score for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/away/shots/increment

Increment away team shots for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/away/shots_on_goal/increment

Increment away team shots on goal for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/away/timeout/toggle

Toggle away team timeout for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/final/toggle

Toggle game final status for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/home/empty_net/toggle

Toggle home team empty net for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/home/penalty/add

Add a penalty for home team in hockey.

Body: {duration: seconds (default 120), number: player number (default "")}

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/hockey/home/penalty/clear

Clear the oldest penalty for home team in hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`204`	No Content	—
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

POST /api/v1/sport/{token}/hockey/home/score/increment

Increment home team score for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/home/shots/increment

Increment home team shots for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/home/shots_on_goal/increment

Increment home team shots on goal for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/home/timeout/toggle

Toggle home team timeout for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/period/increment

Increment period for hockey.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/hockey/reset

Reset all game state to initial values for a new hockey game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Lacrosse

POST /api/v1/sport/{token}/lacrosse/away/empty_net/toggle

Toggle away team empty net for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/away/score/increment

Increment away team score for lacrosse. A positive amount plays the GOAL celebration when it is switched on.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/away/shots_on_goal/increment

Increment away team shots on goal for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/final/toggle

Toggle game final status for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/home/empty_net/toggle

Toggle home team empty net for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/home/score/increment

Increment home team score for lacrosse. A positive amount plays the GOAL celebration when it is switched on.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/home/shots_on_goal/increment

Increment home team shots on goal for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/period/increment

Increment period for lacrosse.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/lacrosse/reset

Reset all game state to initial values for a new lacrosse game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Set-based

POST /api/v1/sport/{token}/set-based/away/score/increment

Increment the away team's points (simple or current-set, sport auto-detected).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/away/set/increment

Increment the away team's sets won (simple mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/current_set/increment

Advance to the next/previous set (expanded mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/home/score/increment

Increment the home team's points (simple or current-set, sport auto-detected).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/home/set/increment

Increment the home team's sets won (simple mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/reset

Reset all game state to initial values for a new match.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/set-based/serve/toggle

Manually switch serve / side-out (pickleball-aware).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Shotclock

POST /api/v1/sport/{token}/shotclock/adjust

Adjust the shot clock duration by a specified number of seconds.

Body: {"amount": <seconds>} - positive to add time, negative to subtract. The shot clock duration will not go below 0.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/shotclock/reset

Reset the shot clock to its initial duration.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/shotclock/reset-short

Reset the shot clock to its short-reset duration (e.g. the FIBA 14-second rule).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/shotclock/toggle

Toggle the shot clock timer.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Soccer

POST /api/v1/sport/{token}/soccer/away/score/increment

Increment away team score for soccer.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/soccer/final/toggle

Toggle the FINAL state of a soccer scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/soccer/home/score/increment

Increment home team score for soccer.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/soccer/period/increment

Increment period (half) for soccer.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/soccer/possession/toggle

Toggle possession between home and away teams.

When toggling possession, one team gets possession and the other loses it.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/soccer/reset

Reset all game state to initial values for a new soccer match.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Timer

POST /api/v1/sport/{token}/timer/adjust

Adjust the main timer duration by a specified number of seconds.

Body: {"amount": <seconds>} - positive to add time, negative to subtract. The timer duration will not go below 0.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/timer/reset

Reset the main timer to its initial duration.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/timer/toggle

Toggle the main timer for any sport scoreboard.

Sport-specific behavior: - Basketball: Also syncs the shot clock (starts/stops with main timer)

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Universal

POST /api/v1/sport/{token}/universal/away/fouls/increment

Increment away team fouls for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/away/score/increment

Increment away team score for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/away/timeouts/increment

Increment away team timeouts for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/final/toggle

Toggle the FINAL state of a universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/home/fouls/increment

Increment home team fouls for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/home/score/increment

Increment home team score for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/home/timeouts/increment

Increment home team timeouts for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/period/increment

Increment period for universal scoreboard.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/universal/possession/toggle

Toggle possession between home and away teams.

When toggling possession, one team gets possession and the other loses it.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Volleyball

POST /api/v1/sport/{token}/volleyball/away/score/increment

Increment away team score for volleyball.

In simple mode: updates away.score In expanded mode: updates away.scores_in_sets[current_set - 1] Also switches serve to away team when scoring (amount > 0).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/away/set/increment

Increment away team sets won (simple mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/current_set/increment

Increment current set number (expanded mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/home/score/increment

Increment home team score for volleyball.

In simple mode: updates home.score In expanded mode: updates home.scores_in_sets[current_set - 1] Also switches serve to home team when scoring (amount > 0).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/home/set/increment

Increment home team sets won (simple mode).

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/reset

Reset all game state to initial values for a new volleyball game.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

POST /api/v1/sport/{token}/volleyball/serve/toggle

Toggle serve between home and away teams.

Path parameters

Name	Type	Required	Description
`token`	string	yes

Responses

Status	Meaning	Body
`200`	OK	MessageResponse
`400`	Malformed request	—
`403`	This token does not allow the board to be edited	—
`404`	Board not found	—
`429`	Too many requests	—
`500`	Internal server error	—

Response body (200) — MessageResponse (JSON)

Field	Type	Always present	Description
`message`	string	yes	Status message

Models

BoardSummary

Field	Type	Always present	Description
`board_token`	string	no	Names the board in /api/<board_token>/… with the same key. Grants nothing on its own.
`title`	string	no
`custom_name`	string	no
`type`	string	no
`sport`	string	no
`brand`	string	no	The brand the board was created on.
`created`	string	no	ISO 8601 timestamp.
`updated`	string	no	ISO 8601 timestamp.

Template

Field	Type	Always present	Description
`slug`	string	no	Pass as `template_slug` to POST /api/v1/account/boards.
`name`	string	no
`description`	string	no
`type`	string	no	The board type it creates.
`sport`	string	no
`brand`	string	no	The brand a board made from it lands on.
`accepts_participants`	boolean	no	Whether the create takes a `participants` list with this template.

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.

Stream Deck Integration - Physical button control for your scoreboard
Streaming Software Setup - Display scoreboards on your stream
Quick Start Guide - Get started with Keepthescore.com