Leaderboards

Leaderboard definitions (metric, period, max entries) + admin-side ranked entries.

Leaderboards are named rankings of users by a metric (xp, streak_length, custom). Entries are written automatically by the engagement pipeline; ranking and tiebreaker logic is shared with the segment-rule and gamification engines.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/leaderboards`	Create a leaderboard.
GET	`/admin/projects/:projectId/leaderboards`	List leaderboards.
GET	`/admin/projects/:projectId/leaderboards/:leaderboardId`	Fetch.
PATCH	`/admin/projects/:projectId/leaderboards/:leaderboardId`	Partial update.
DELETE	`/admin/projects/:projectId/leaderboards/:leaderboardId`	Delete.
GET	`/admin/projects/:projectId/leaderboards/:leaderboardId/entries`	Paginated ranked entries with user display info.

POST /admin/projects/:projectId/leaderboards

Request

Field	Type	Required	Default
`name`	string	yes	—
`metric`	string	yes	—
`period`	string	no	`"all_time"`
`max_entries`	number	no	100
`custom_event`	string	no	null

Response 201

{ "data": { "id": "…", "name": "…", "metric": "xp", "period": "all_time", "max_entries": 100 } }

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/leaderboards

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/leaderboards' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/leaderboards

{ "data": [{ "id": "…", "name": "…", "metric": "xp" }] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/leaderboards

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/leaderboards' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/leaderboards/:leaderboardId

Errors

404 NOT_FOUND.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/leaderboards/{leaderboardId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/leaderboards/:leaderboardId

Allowed fields: name, metric, period, max_entries, custom_event, is_active.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/leaderboards/{leaderboardId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/leaderboards/:leaderboardId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/leaderboards/{leaderboardId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/leaderboards/:leaderboardId/entries

Paginated entries ordered by rank ascending (entries without a rank sort last). Each row carries the user's display_name and avatar_url.

Query

Param	Default
`limit`	50
`offset`	0

Response 200

{
  "data": [
    {
      "leaderboard_id": "…",
      "app_user_id": "…",
      "rank": 1,
      "score": 1234,
      "app_users": { "display_name": "…", "avatar_url": "…" }
    }
  ],
  "total": 100,
  "offset": 0,
  "limit": 50
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D/entries

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/leaderboards/%7B%7BleaderboardId%7D%7D/entries'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/leaderboards/{leaderboardId}/entries' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

On this page