Keepthescore.com REST API for scores, leaderboards, and counters

Documentation for the KeepTheScore API for managing leaderboards, trackers and counters. Fetch data, update scores, and customize appearance.

Page Contents

If you're new to Keepthescore.com, we recommend starting with our quick start guide.

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

The API allows you to:

  • Fetch all data for all board types (including sports scoreboards)
  • Populate a leaderboard with participants, scores and profile images
  • Increment or set scores for one participant
  • Add a round (add scores for all participants in one request) including a comment
  • Add a participant, counter or team
  • Update a participant or counter
  • Delete a participant, counter or team
  • Set the appearance of a board (but not sports scoreboards)

The API does not allow you to create a board

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

API Access

Each board has it's own unique access token for using the API.

You can find it by clicking the "Share" button in the control panel of your board, and then clicking on the "Embed on a Website" panel.

Settings Colors Example This is where the access token for using the API is located

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.

When relying on the CORS header, ensure that you check whether the route has a trailing slash "/" or not. Otherwise, your API call may fail.

API Routes

Below is a list of all public endpoints.

Note: Participants and players are the same entity.