API Documentation

Contents

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. Alternatively you can write a comment below.

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.