Create a new leaderboard

Creates a new leaderboard in the API-key's community and returns the created document.

Use this when a partner integration needs to provision a new leaderboard (e.g. launching a monthly trader ranking, creating an embeddable widget, or seeding leaderboards as part of community onboarding).

Authentication:

Bearer API key in Authorization header

API key must have the leaderboard permission

Community is resolved from the API key token — do not pass communityID

Returns 401 if the key is missing, invalid, or lacks the required permission

Side effects:

Inserts a new leaderboard document in the gamification service

Publishes the create:leaderboard pub/sub event; the gamification service processes it and performs the DB write

Returns 502 if the upstream gamification service is unreachable or the publisher times out

Rate limits:

Standard API rate limits apply

Constraints:

slug must be unique within the community — conflicts return 409

slug must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ (lowercase, digits, hyphens)

name, slug: 1–100 chars

description: max 2000 chars (defaults to empty string)

rankBy: 1–100 chars, only letters/digits/hyphens/underscores (system or custom field name)

displayedFields, displayFieldsOrder: up to 50 entries, each max 100 chars

timeFilters: entries must be within the allowed enum (e.g. all-time, monthly, weekly, daily)

duration.start required; duration.end only required when duration.noEndDate is false

widget.whitelistedDomains: up to configured max; each domain must be a valid FQDN

widget.theme.* colours must match the CSS colour regex

Regex/enum violations return 400

Example — create:

{
  "name": "Top Traders",
  "slug": "top-traders",
  "description": "Monthly trading leaderboard",
  "rankBy": "currencies",
  "displayedFields": ["name", "score"],
  "displayFieldsOrder": ["name", "score"],
  "timeFilters": ["all-time", "monthly"],
  "performanceDisplay": {
    "showTop": { "enabled": true, "value": 10 },
    "showPositive": { "enabled": true },
    "showDummy": { "enabled": false }
  },
  "duration": {
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-12-31T23:59:59.999Z",
    "noEndDate": false,
    "timeZone": 7
  },
  "enabled": true,
  "previewEnabled": false
}

Related endpoints:

GET /leaderboards — list leaderboards

GET /leaderboards/{leaderboardID} — read a single leaderboard

PATCH /leaderboards/{leaderboardID} — update a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

curl --location --request POST 'https://api.returning.ai/v1/leaderboards' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Top Traders", "slug": "top-traders", "description": "Monthly trading leaderboard", "rankBy": "currencies", "displayedFields": [ "name", "score" ], "displayFieldsOrder": [ "name", "score" ], "timeFilters": [ "all-time", "monthly" ], "performanceDisplay": { "showTop": { "enabled": true, "value": 10 }, "showPositive": { "enabled": true }, "showDummy": { "enabled": false } }, "duration": { "start": "2026-01-01T00:00:00.000Z", "end": "2026-12-31T23:59:59.999Z", "noEndDate": false, "timeZone": 7 }, "enabled": true, "previewEnabled": false }'

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create leaderboard success.", "data": { "_id": "507f1f77bcf86cd799439012", "communityID": "507f1f77bcf86cd799439013", "name": "Top Traders", "slug": "top-traders", "description": "Monthly trading leaderboard", "rankBy": "currencies", "displayedFields": [ "name", "score" ], "displayFieldsOrder": [ "name", "score" ], "timeFilters": [ "all-time", "monthly" ], "duration": { "start": "2026-01-01T00:00:00.000Z", "end": "2026-12-31T23:59:59.999Z", "noEndDate": false, "timeZone": 7 }, "enabled": true, "previewEnabled": false, "selected": false, "createdAt": "2026-04-20T00:00:00.000Z", "updatedAt": "2026-04-20T00:00:00.000Z" } }

Request

Responses