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:

The API does not allow you to:

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].


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

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.