Leaderboards API
Retrieve progression leaderboard rankings by leaderboard code. Rankings are computed on-the-fly from the progression system.
Authentication: Public endpoint. Pass
engagement_id as a query parameter. No API key required.Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /public/leaderboards/{code} | Get leaderboard rankings by code |
Get Leaderboard
Returns ranked entries for a progression leaderboard. The leaderboard code is configured in the Bricqs Builder under Progression settings. Rankings auto-refresh every 30 seconds at runtime.
curl -X GET "https://YOUR_API_DOMAIN/api/v1/public/leaderboards/top_scorers?engagement_id=550e8400-e29b-41d4-a716-446655440000&limit=10"Response
{
"leaderboard_code": "top_scorers",
"name": "Top Scorers",
"entries": [
{
"rank": 1,
"participant_id": "p_456",
"display_name": "Jordan K.",
"score": 2450,
"avatar_url": null
},
{
"rank": 2,
"participant_id": "p_789",
"display_name": "Alex M.",
"score": 2100,
"avatar_url": null
},
{
"rank": 3,
"participant_id": "p_012",
"display_name": "Sam T.",
"score": 1875,
"avatar_url": null
}
],
"total_participants": 342
}Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
engagement_id | UUID | Yes | The engagement/campaign ID |
limit | integer | No | Number of entries to return (default: 10, max: 100) |
session_id | string | No | If provided, highlights the current participant's rank |