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.

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 '{"player_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 '{"player_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! 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.

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