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

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

🟠404Record Not Found

🟠409

🔴500Server Error

🔴502Bad Gateway

curl --location --request PATCH 'https://api.returning.ai/v1/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" } }