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:

The API does not allow you to:

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

Get players and total scores

Returns a list of player ids, their names and their total scores.

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

Example request

You can paste this directly into your terminal 👇

curl -i https://keepthescore.co/api/ltxphsnqskr/players

Example Response

HTTP/2 200
date: Thu, 18 Mar 2021 10:36:17 GMT
content-type: application/json
...
{
   "players":[
      {
         "player_id":2753171,
         "player_name":"Player 2",
         "total": 10
      },
      {
         "player_id":2753170,
         "player_name":"Player 1",
         "total": 1
      }
   ]
}

Add a round

Add a round including comments as JSON.

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

Example request

You can paste this directly into your terminal 👇

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

Add points for one player

Add points for one player including a comment as JSON.

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

Example request

You can paste this directly into your terminal 👇

curl -i -H "Content-Type: application/json" -X POST -d '{ "player_name": "Player 1", "score": 10, "comment": "Woot" }' https://keepthescore.co/api/xvrynjqlgne/add_single_score

CORS Headers

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

Rate limiting

All API calls are rate-limited.

If a rate-limit is applied your will recieve a response code of 429.

Help! 👋

If you need help or have requests us an email.

I have a question, feedback, or a feature request

Great! Write us an email — we answer every single one.

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. To help us decide what to make next please take this 20 second poll.