Scoreboard

Scoreboard is a simple service for arcade-style high score tables. Create a game, get an ID, and start submitting scores. Useful for jam games, static sites, or anywhere you need a scoreboard without running your own database.

Each game has a password-protected admin panel where you can manage scores, flag suspicious entries, and configure anti-abuse settings.

Create a Game

API

Create a Game

POST /g with Content-Type: application/json to create a game with settings in one step. Only name is required — all other fields are optional and use sensible defaults. If password is omitted, one is generated for you.

curl -X POST scoreboard/g \
  -H "Content-Type: application/json" \
  -d '{"name": "My Game", "max_score": 10000}'

# Response (201 Created)
{
  "id": "xK9mP2qR5tLw",
  "name": "My Game",
  "password": "G7kP2mR5qT9wXy4b",
  "token_lifetime": 3600,
  "min_play_time": 0,
  "min_checkins": 0,
  "min_checkin_interval": 0,
  "min_score": null,
  "max_score": 10000,
  "lower_is_better": false
}

Returns 201 Created. Save the id and password from the response — the password is needed for the admin panel and cannot be retrieved later.

Get Scoreboard

GET /g/ID returns the scoreboard as an HTML page. /g/ID.json returns JSON.

curl scoreboard/g/abc123.json
{
  "game": "My Awesome Game",
  "scores": [
    {"rank": 1, "name": "AAA", "score": 9999},
    {"rank": 2, "name": "BBB", "score": 8888}
  ]
}

Worst Scores

GET /g/ID/worst.json returns the bottom 100 scores (reverse of the main scoreboard).

Each entry's rank is its global ranking on the main leaderboard.

curl scoreboard/g/abc123/worst.json
{
  "game": "My Awesome Game",
  "scores": [
    {"rank": 17141, "name": "CCC", "score": 10},
    {"rank": 17140, "name": "DDD", "score": 42}
  ]
}

Score Histogram

GET /g/ID/histogram.json returns the distribution of scores across up to 20 buckets (default). Use the optional ?buckets=N query parameter to control the maximum number of buckets (1–100). Passing 0 or omitting the parameter uses the default of 20.

curl scoreboard/g/abc123/histogram.json
curl scoreboard/g/abc123/histogram.json?buckets=10
{
  "game": "My Awesome Game",
  "total": 150,
  "buckets": [
    {"min": 0, "max": 499, "count": 12},
    {"min": 500, "max": 999, "count": 45}
  ]
}

Submit a Score

Score submission uses a two-step token flow to prevent abuse. First, request a token, then submit the score with the token.

1. Request a Token

POST /g/ID/token to get a time-limited, IP-bound token.

curl -X POST scoreboard/g/abc123/token
{"token": "xK9mP2qR5tLw"}

2. Submit the Score

POST /g/ID with token, name (max 15 chars), score, and optionally checkins.

curl -X POST scoreboard/g/abc123 \
  -d "token=xK9mP2qR5tLw&name=AAA&score=9999&checkins=[10,30,65]"

Tokens are single-use, IP-matched, and time-limited. Games can configure a minimum play time so scores submitted too quickly are rejected, a token lifetime after which the token expires, and min/max score bounds to reject impossible values.

Checkins

Checkins are an optional array of timestamps (seconds since token creation) representing milestones like level completions or rounds. The game client records these locally and sends them with the score. Games can require a minimum number of checkins and a minimum interval between them as an anti-cheat heuristic.

Admin Panel

Visit /g/ID/admin to access the admin panel. You'll need the password you set when creating the game. From there you can rename the game, configure all anti-cheat settings, flag or delete individual scores, or reset all scores.