Contents

API Documentation

Keepthescore.co has a simple REST API. Please be aware that breaking changes may occur without notice.

Currently, the API allows you to:

  • Get list of players and their total scores
  • Add a round (add scores for all players in one request)
  • Add scores for one player only
  • Add players / add counters

The API does not allow you to:

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

Getting started 👋

To use the API you require a token from your scoreboard. Note that each scoreboard 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 "SHARE" button).

All examples in this documentation use this leaderboard which has

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

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 minute for many days in a row.

Get all board data

Returns all the data shown on a board.

GET https://keepthescore.co/api/<PUBLIC_TOKEN>/board/

Example request

You can paste this directly into your terminal 👇

curl https://keepthescore.co/api/ltxphsnqskr/board/

Add a player

This request adds a player.

  • Note that when you are adding a player to a team leaderboard, you must include the team id in the payload.
  • You can use this request to add counters too

POST http://localhost:5000/api/<EDIT_TOKEN>/player/

Example request for leaderboards, counters and scoreboards

You can paste this directly into your terminal 👇

curl -H "Content-Type: application/json" -X POST -d '{"name": "New player name"}' https://keepthescore.co/api/xvrynjqlgne/player/

Example request for team leaderboards

You can paste this directly into your terminal 👇

curl -H "Content-Type: application/json" -X POST -d '{"name": "New player name", "team": 57}' https://keepthescore.co/api/xvrynjqlgne/player/

Add scores for one player

  • Players are identified by their ids.
  • This API call requires the edit token.

POST https://keepthescore.co/api/<EDIT_TOKEN>/score/

Example request

You can paste this directly into your terminal 👇

curl -H "Content-Type: application/json" -X POST -d '{ "player_id": 2753171, "score": 100}' https://keepthescore.co/api/xvrynjqlgne/score/

Add a round (scores for all players)

Add a round including comments.

  • All players must be included in the request, even if their scores are 0.
  • Players are identified by their ids.
  • This API call requires the edit token.

POST https://keepthescore.co/api/<EDIT_TOKEN>/round/

Example request

You can paste this directly into your terminal 👇

curl -H "Content-Type: application/json" -X POST -d '{ "scores": [{"player": 2753171, "score": 10}, {"player": 2753170, "score": 1}], "comment": "Yeah" }' https://keepthescore.co/api/xvrynjqlgne/round/

CORS Headers

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

Questions and feedback

Do you have a question, feedback, or a feature request?

Great! We answer every message within 1 working day (sometimes on the weekend too). You can reach us in the following ways:

We love feature requests, but it depends on whether we think it'll be useful to other users and how much effort it'll be.

Whilst you're here: subscribe to our newsletter to always be informed about what's new.