Keepthescore.com REST API

Welcome to the KeepTheScore API documentation. 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 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].

Authentication

To use the API you require a token from your board. Note that each board has 2 tokens: the public token (end's with the character r) and the edit token (ends with the character e). You can extract both tokens from the 2 URLs of your scoreboard (they are revealed by pressing the "PUBLISH" button).

All examples in this documentation use this leaderboard which has

the following edit token: xvrynjqlgne and
the following public token: ltxphsnqskr.

You can carry out GET requests with either the public or the edit token. However, you can only carry out POST, PATCH and DELETE requests with the edit token.

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.