Leaderboards API

POST /v1/leaderboards

Submit a score to a leaderboard. Uses UPSERT logic — if the player already has an entry, it’s updated only if the new score is higher.

Auth: x-game-api-key header

curl -X POST https://api.questdata.io/v1/leaderboards \
  -H "Content-Type: application/json" \
  -H "x-game-api-key: YOUR_API_KEY" \
  -d '{
    "board_name": "weekly_highscore",
    "player_id": "player-123",
    "score": 15000,
    "player_name": "DragonSlayer",
    "metadata": {"level": 42, "character": "warrior"}
  }'

Request Body

Field	Type	Required	Description
board_name	string	Yes	Leaderboard identifier (max 255 chars)
player_id	string	Yes	Player identifier
score	number	Yes	Score value
player_name	string	No	Display name on the leaderboard
metadata	object	No	Additional data stored with the entry

Response (201)

The created or updated leaderboard entry.

---

GET /v1/leaderboards/:board_name

Fetch ranked entries for a leaderboard.

Auth: x-game-api-key header

curl "https://api.questdata.io/v1/leaderboards/weekly_highscore?limit=10" \
  -H "x-game-api-key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Default	Description
limit	number	50	Entries to return (max 100)
offset	number	0	Pagination offset

Response (200)

{
  "board_name": "weekly_highscore",
  "entries": [
    {
      "rank": 1,
      "player_id": "player-123",
      "player_name": "DragonSlayer",
      "score": 15000,
      "metadata": {"level": 42, "character": "warrior"},
      "updated_at": "2026-04-08T10:30:00Z"
    }
  ]
}

Error Responses

Status	Cause
400	Invalid limit or offset value
401	Missing or invalid API key