All docs

General API reference

Every general endpoint of the KeepTheScore API, with its parameters, request body and responses, generated from the live API.

Keys, tokens, request bodies and rate limits are explained in the API guide. In the paths below, {token} is a board token when you send an API key, or one of the board's own tokens without one.

This page is generated from the live API. The same reference is available as OpenAPI 3 at /apispec.json, if you'd rather generate a client than read tables.

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, a blank sport scoreboard, or a plain leaderboard.

Body: exactly one of `template_slug`, `sport` or `board_type` (only "LEADERBOARD": a plain leaderboard on Leaderboarded); optional `brand` (sport only, defaults to the brand of the host called), `name`, and `participants` (`[{"name": str, "score"?: number}]`, LEADERBOARD only), which replace a template's demo participants or seed a plain leaderboard. 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.

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.