Update an existing leaderboard

Updates a leaderboard for the API-key's community and returns the updated leaderboard document.

Use this to change leaderboard metadata, schedule, ranking fields, displayed columns, permission allow-lists, widget settings, or enabled state.

Authentication:

Bearer API key in Authorization header

Required permission: leaderboard

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

Returns 401 if missing, invalid, or insufficient

Side effects:

Updates the leaderboard in the resolved community

Publishes the update:leaderboard command through the partner publisher path

Gamification service processes the command and persists the leaderboard update

UI reads the updated duration from the stored duration object

Rate limits:

Standard API rate limits apply

Constraints:

Send at least one updatable field

slug must be unique per community and match lowercase letters, numbers, and hyphens

New integrations should use rankingField, displayedColumns, startDate, endDate, hasNoEndDate, isEnabled, and isPreviewEnabled

Include startDate when repairing or changing schedule data so the UI can read the duration correctly

displayedColumns has max 50 items

allowedTimeFilters values are all-time, daily, weekly, monthly, or yearly

widget.whitelistedDomains has max 50 domains

Legacy aliases are accepted for backward compatibility, but flat fields win when both are present

Example — update:

{
  "name": "April Last Leaderboard",
  "slug": "april-last-leaderboard",
  "description": "Monthly leaderboard updated through the partner API.",
  "image": "https://cdn.example.com/leaderboards/april.png",
  "rankingField": "currencies",
  "displayedColumns": [
    { "column": "user", "visible": true, "order": 0 },
    { "column": "currencies", "visible": true, "order": 1 }
  ],
  "topRankOnly": false,
  "topRankLimit": 10,
  "onlyPositiveRanks": false,
  "includeDummyUsers": false,
  "startDate": "2026-01-30T19:30:00.000Z",
  "endDate": "2026-12-31T23:59:59.999Z",
  "hasNoEndDate": true,
  "timeZone": 5.3,
  "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" },
  "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" },
  "allowedTimeFilters": ["all-time", "monthly", "weekly"],
  "allowedUsersToRank": [],
  "allowedRolesToRank": ["507f1f77bcf86cd799439014"],
  "allowedTagsToRank": [],
  "allowedUsersToView": [],
  "allowedRolesToView": ["507f1f77bcf86cd799439014"],
  "allowedTagsToView": [],
  "isEnabled": true,
  "isPreviewEnabled": false,
  "displayOrder": 3,
  "widget": {
    "enabled": false,
    "whitelistedDomains": ["example.com"],
    "size": { "type": "custom", "value": { "width": 420, "height": 640 } },
    "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" }
  }
}

Related endpoints:

GET /leaderboards — list leaderboards

POST /leaderboards — create a leaderboard

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

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

What it is for: Update an existing leaderboard. Use this to manage custom leaderboards that rank users by configured fields, points, or broker-defined metrics.
How to use it: Send a PATCH request to /leaderboards/{leaderboardID} with the request body, query parameters, or multipart fields shown below. Partner API key required when this surface is enabled for the community. Confirm gateway access before using in production.
Availability note: this route is legacy or partner-service-backed. During a 2026-05-18 smoke test, the equivalent root path returned 404 on https://api.returning.ai; keep it marked non-primary until the gateway alias is confirmed.
Successful response: HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

Responses

🟢200OK

application/json

Leaderboard updated successfully. The response envelope is required; leaderboard data fields are documented but optional for compatibility with projected or legacy shapes.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠409Server Error

🔴500Server Error

🔴502Bad Gateway

curl --location --request PATCH 'https://api.returning.ai/leaderboards/507f1f77bcf86cd799439012' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "April Last Leaderboard", "slug": "april-last-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankingField": "currencies", "displayedColumns": [ { "column": "user", "visible": true, "order": 0 }, { "column": "currencies", "visible": true, "order": 1 } ], "topRankOnly": false, "topRankLimit": 10, "onlyPositiveRanks": false, "includeDummyUsers": false, "startDate": "2026-01-30T19:30:00.000Z", "endDate": "2026-12-31T23:59:59.999Z", "hasNoEndDate": true, "timeZone": 5.3, "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" }, "allowedTimeFilters": [ "all-time", "monthly", "weekly" ], "allowedUsersToRank": [], "allowedRolesToRank": [ "507f1f77bcf86cd799439014" ], "allowedTagsToRank": [], "allowedUsersToView": [], "allowedRolesToView": [ "507f1f77bcf86cd799439014" ], "allowedTagsToView": [], "isEnabled": true, "isPreviewEnabled": false, "displayOrder": 3, "widget": { "enabled": false, "whitelistedDomains": [ "example.com" ], "size": { "type": "custom", "value": { "width": 420, "height": 640 } }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" } } }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update leaderboard success.", "data": { "_id": "507f1f77bcf86cd799439012", "communityID": "6502c97314a3e564c5bbfa84", "name": "April Last Leaderboard", "slug": "april-last-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankBy": "currencies", "displayedFields": [ "user", "currencies" ], "displayFieldsOrder": [ "user", "currencies" ], "timeFilters": [ "all-time", "monthly", "weekly" ], "performanceDisplay": { "showTop": { "enabled": false, "value": 10 }, "showPositive": { "enabled": false }, "showDummy": { "enabled": false } }, "duration": { "start": "2026-01-30T19:30:00.000Z", "end": "2026-12-31T23:59:59.999Z", "noEndDate": true, "timeZone": 5.3, "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" } }, "rankedUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "viewPermissionUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "widget": { "enabled": false, "whitelistedDomains": [ "example.com" ], "size": { "type": "custom", "value": { "width": 420, "height": 640 } }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" } }, "enabled": true, "previewEnabled": false, "displayOrder": 3, "selected": false, "updatedAt": "2026-04-13T12:30:00.000Z", "createdAt": "2026-04-13T12:00:00.000Z" } }