Leaderboards

Leaderboards

A leaderboard is a ranked scoreboard, identified by a string id you pick, for example weekly-time-trial. Submission is server-authoritative: a score is written for the calling player only, gated by the API key and session token. Every call needs both.

Endpoints

• POST /v1/leaderboards/{id}/scores submits a score for the caller.
• GET /v1/leaderboards/{id}/top reads the top slice.
• GET /v1/leaderboards/{id}/around-me reads a window centered on the caller and includes the caller's own rank.

Example

# submit a score
curl -s -X POST http://localhost:8080/v1/leaderboards/weekly-time-trial/scores \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"score":91240}'

# read the top entries
curl -s http://localhost:8080/v1/leaderboards/weekly-time-trial/top \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>"

Each entry carries player_id, score, and rank. The around-me result adds self_rank.

Full reference: the /v1/leaderboards/* operations.