Leaderboards API
Query leaderboard rankings and individual participant positions. Rankings are computed on-the-fly from the points and scoring data.
Authentication: All endpoints require an
X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify| Method | Endpoint | Description |
|---|---|---|
| GET | /gamify/leaderboards/{code} | Top rankings with optional time period filter. |
| GET | /gamify/leaderboards/{code}/rank/{pid} | Individual rank, score, and percentile. |
Get Rankings
GET /api/v1/gamify/leaderboards/top_scorers?limit=10&period=monthly
{
"leaderboard_code": "top_scorers",
"period": "monthly",
"entries": [
{ "rank": 1, "participant_id": "user_456", "score": 5000, "change": "up" },
{ "rank": 2, "participant_id": "user_123", "score": 4500, "change": "same" },
{ "rank": 3, "participant_id": "user_789", "score": 4200, "change": "new" }
],
"total_participants": 1250
}Get Individual Rank
GET /api/v1/gamify/leaderboards/top_scorers/rank/user_123
{
"participant_id": "user_123",
"rank": 2,
"score": 4500,
"total_participants": 1250,
"percentile": 99.8
}Period options:
all_time, yearly, monthly, weekly, daily. If omitted, uses the leaderboard definition's default time window.