API Documentation

Keepthescore.co has a REST API but please don't get too excited, because it's rudimentary. Also be aware that breaking changes may occur without notice.

Currently the API allows you to:


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 "publish" button).

Get scores

Returns a list of scores and dates when the round was created.

Request: GET https://keepthescore.co/api/<TOKEN>/rounds

Response: [ { "comment": "", "date": "Sun, 12 Jul 2020 21:22:46 GMT", "id": 876, "scores": [ 0, 0, 0, 50 ] }, { "comment": "WHAT IS GOING ON?", "date": "Tue, 16 Jun 2020 20:49:03 GMT", "id": 820, "scores": [ 0, 0, 0, 0 ] }, { "comment": "", "date": "Tue, 16 Jun 2020 20:48:51 GMT", "id": 819, "scores": [ 20, 150, 0, 0 ] } ]

Get players and meta-information

This returns information on the scoreboard including the ids of the players. You need to get the player ids from this response if you want to add scores (see POST request below.)

Request: GET https://keepthescore.co/api/<TOKEN>/

Response: { "do_next_poll": 45, "players": [ { "game": 891, "id": 3526, "player_name": "Four" }, { "game": 891, "id": 3523, "player_name": "One" }, { "game": 891, "id": 3525, "player_name": "Three" }, { "game": 891, "id": 3524, "player_name": "Two" } ], "total_strings": [ "210 \ud83c\udfc6", "190", "150", "120" ], "type": "SCOREBOARD", "updated": "Sun, 12 Jul 2020 19:23:17 GMT" }

Add new scores

There are 2 endpoints for adding scores. You can either add a round, which means points must be specified for all players. Or you can add points for just one player.

Add a round

Add a round including comments as JSON.

Request: POST https://keepthescore.co/api/<TOKEN>/add_round

Here's the post request with curl: curl -i -H "Content-Type: application/json" -X POST -d '{ "scores": [{"player": 1690991, "score": 10}, {"player": 1690989, "score": 1}], "comment": "Yeah" }' https://keepthescore.co/api/<TOKEN>/add_round

Add points for one player

Add points for one player including a comment as JSON.

Request: POST https://keepthescore.co/api/<TOKEN>/add_single_score

Here's the post request with curl: curl -i -H "Content-Type: application/json" -X POST -d '{ "player_name": "Caspar", "score": 10, "comment": "Yeah" }' https://keepthescore.co/api/<TOKEN>/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.

Help! 👋

If you need help or have requests, please comment below or write a mail.