Public API

Endpoints are versioned under /api/v1

Public game APIs require a per-game API key using the Authorization: Bearer header.

Submit Score

POST /api/v1/games/:gameRefId/scores

curl -X POST "http://localhost:5173/api/v1/games/neon-drifter/scores" \
  -H "Authorization: Bearer <GAME_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "x-score-signature: sha256=<hmac-sha256-signature>" \ # Only if Signature Validation is enabled
  -d '{"score":42000,"submissionId":"abc-123","playerRefId":"player_1","playerName":"Player One","seasonId":"season_2","teamId":"team_red"}'

Fetch Leaderboard

GET /api/v1/games/:gameRefId/leaderboard?limit=20&period=all|weekly|monthly&season=...&team=...

curl "http://localhost:5173/api/v1/games/neon-drifter/leaderboard?limit=20&period=all&season=season_2&team=team_red" \
  -H "Authorization: Bearer <GAME_API_KEY>"

Fetch Player Rank

GET /api/v1/games/:gameRefId/players/:playerRefId/rank?period=all|weekly|monthly&season=...&team=...

curl "http://localhost:5173/api/v1/games/neon-drifter/players/player_1/rank?period=all&season=season_2&team=team_red" \
  -H "Authorization: Bearer <GAME_API_KEY>"

Fetch Centric Leaderboard

GET /api/v1/games/:gameRefId/players/:playerRefId/centric?limit=5&period=all|weekly|monthly&season=...&team=...

curl "http://localhost:5173/api/v1/games/neon-drifter/players/player_1/centric?limit=5&period=all&season=season_2&team=team_red" \
  -H "Authorization: Bearer <GAME_API_KEY>"

Upsert Player Profile

PUT /api/v1/games/:gameRefId/players/:playerRefId

curl -X PUT "http://localhost:5173/api/v1/games/neon-drifter/players/player_1" \
  -H "Authorization: Bearer <GAME_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"playerName":"Player One", "avatarUrl":"https://...", "teamId":"team_red", "level":10, "country":"US", "device":"iOS"}'

Fetch Player Profile

GET /api/v1/games/:gameRefId/players/:playerRefId

curl "http://localhost:5173/api/v1/games/neon-drifter/players/player_1" \
  -H "Authorization: Bearer <GAME_API_KEY>"

Webhooks

Receive realtime events when high scores are achieved or players are overtaken.

POST /your-webhook-endpoint
Content-Type: application/json
X-LLB-Signature: sha256=<hmac-sha256-signature>

{
  "event": "new_top_score", // or "score_overtaken"
  "gameRefId": "neon-drifter",
  "timestamp": "2024-05-12T10:00:00Z",
  "data": {
    "playerRefId": "player_1",
    "score": 42000
  }
}

Event Types:
• new_top_score — Someone just took #1 overall.
• score_overtaken — A named player was displaced by the new score.
• entered_top_10 — Player entered the Top 10 for the first time (or re-entered).
• entered_top_100 — Player entered the Top 100 for the first time (or re-entered).
• personal_best — Player achieved a new personal best score.

Security: All requests are HMAC-SHA256 signed with your webhook secret. Verify payloads using the X-LLB-Signature: sha256=... header. Requests have a 5s timeout.

API Docs