Update an existing leaderboard

Partially updates an existing leaderboard in the API-key's community and returns the updated document.

Use this to edit leaderboard configuration after creation — e.g. rename the leaderboard, change its slug, toggle enabled/previewEnabled, adjust duration/timeFilters, or update widget embedding rules.

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:

Updates the leaderboard document in the gamification service

Publishes the update: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:

All body fields are optional — only provided fields are updated

slug must remain unique within the community — conflicts return 409

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

name, slug: 1–100 chars; description: max 2000 chars

rankBy: 1–100 chars, only letters/digits/hyphens/underscores

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

timeFilters entries must be within the allowed enum

When duration is provided, the same nested rules as create apply

Returns 404 if the leaderboard does not exist in this community

Validation violations return 400

Example — update:

{
  "name": "Top Traders (Q2)",
  "enabled": false,
  "previewEnabled": true
}

Related endpoints:

GET /leaderboards — list leaderboards

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

POST /leaderboards — create a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

curl --location --request PATCH 'https://api.returning.ai/v1/leaderboards/507f1f77bcf86cd799439012' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Top Traders (Q2)", "enabled": false, "previewEnabled": true }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update leaderboard success.", "data": { "_id": "507f1f77bcf86cd799439012", "communityID": "507f1f77bcf86cd799439013", "name": "Top Traders (Q2)", "slug": "top-traders", "description": "Monthly trading leaderboard", "rankBy": "currencies", "enabled": false, "previewEnabled": true, "updatedAt": "2026-04-20T00:00:00.000Z" } }

Update an existing leaderboard

Request

Responses