Keepthescore.com REST API

This documentation is intended for developers who want to control their scores programmatically.

NOTE: the API does not allow changing scores on live sports scoreboards.

Please read this page to understand what the different resources (counters, leaderboards, etc.) are. The API allows you to:

  • Fetch all data for leaderboards and score sheets
  • Fetch all data for a live sports scoreboard
  • Populate a leaderboard with players and scores
  • Add scores for one player
  • Add a round (add scores for all players in one request) including a comment
  • Add players / counters / teams
  • Delete a player / counter / team
  • Set the appearance of leaderboards and score sheets

The API does not allow you to:

  • Create a scoreboard
  • Edit players and counters
  • Edit the scoreboard (e.g. change fields like title, description or formatting)

This documentation is a work in progress, just like the API itself. Not everything is documented yet. If you have a request or find something that is confusing or wrong, please write an email to [email protected].

Board Tokens

To use the API you require the edit token from an existing board. You can extract this token from the admin URL of your board.

For instance, this leaderboard has the following admin URL: keepthescore.com/board/xvrynjqlgne/.

It has the edit token: xvrynjqlgne and this is required as a path variable for all API requests. See the detailed documentation below.

(Note, to prevent vandalism, the admin url of this board cannot be opened in a browser. But you can use the API to change it).

Rate limiting

All API endpoints are rate-limited. If you send more than 5 requests per second per board you will be rate-limited for 1 minute.

Exceeded the rate-limit will result in a response code of 429 instead of 200. If you intend to send many requests, your code should handle this eventuality.

If we get the impression that you are "abusing" the API (and this definition is kept vague on purpose), your board may be deleted without prior notice. Don't worry, we do this very rarely. Examples of abuse include: sending identical API requests every second for many days in a row.

CORS Headers

All responses contain a CORS header (access-control-allow-origin: *), meaning that the API can also be called from a browser.