Update an existing leaderboard
PATCH
https://sgtr-api.returning.ai/v1/leaderboards/{leaderboardID}
Gamification/Leaderboards
What this endpoint does
INFO
leaderboard, call GET /v1/leaderboards, then use an id from that list.Quick start
PATCH or DELETE only after a disposable board exists. Do not patch prize/reset on a live community from docs.Authentication and permission
leaderboard.Complete examples
AUTH_PERMISSION_REQUIRED body as the list page when leaderboard is missing.message is Read leaderboard success. data is one board object with the same fields as a list row (_id, name, slug, rankBy, displayedFields, widget, and the rest).{
"meta": { "status": "success", "statusCode": 200 },
"message": "Read leaderboard success.",
"data": {
"_id": "<leaderboardID>",
"name": "Example board",
"slug": "example-board",
"rankBy": "Messages Sent"
}
}Success and readback
200 is the readback for PATCH. After DELETE, the id should disappear from the list.Errors and recovery
| Status | When | Recovery |
|---|---|---|
403 leaderboard | Key lacks permission | Grant leaderboard. |
404 | Path without /v1 | Prefix /v1. |
401 | Missing or invalid token | Replace the key. |
Retry safety
WARNING
Gotchas
{leaderboardID} is not a user id.Next steps
Request
Path Params
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PATCH 'https://sgtr-api.returning.ai/v1/leaderboards/65f1b2c3d4e5f67890123456' \
--header 'Authorization: Bearer XXXXXX' \
--header 'Content-Type: application/json' \
--data '{"leaderImage": "https://cdn.example.com/leaderboards/april.png", "name": "April Updated Leaderboard", "slug": "april-updated-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "rankBy": "currencies", "displayedFields": ["user", "currencies", "xps", "level"], "displayFieldsOrder": ["user", "currencies", "xps", "level"], "timeFilters": ["all-time", "daily", "weekly", "monthly", "yearly"], "performanceDisplay": {"showTop": {"enabled": true, "value": 10}, "showPositive": {"enabled": true}, "showDummy": {"enabled": false}}, "duration": {"start": "30-01-2026", "end": null, "noEndDate": true, "timeZone": 600, "startTime": {"hours": 12, "minutes": 0, "ampm": "AM"}, "endTime": {"hours": 11, "minutes": 59, "ampm": "PM"}}, "rankedUserRoles": {"users": [], "roles": ["6502c97314a3e564c5bbfa84"], "tags": []}, "viewPermissionUserRoles": {"users": [], "roles": ["6502c97314a3e564c5bbfa84"], "tags": []}, "widget": {"enabled": true, "apiKey": "widget-key", "whitelistedDomains": ["example.com"], "size": "dynamic", "width": null, "height": null, "theme": {"default": "dark", "dark": {"name": "Custom Dark", "accent": "#7C3AED", "accent2": "#22C55E", "accent3": "#F59E0B", "accent4": "#EF4444", "text": "#FFFFFF", "text2": "#E5E7EB", "text3": "#D1D5DB", "text4": "#9CA3AF", "text5": "#6B7280", "text6": "#4B5563", "background": "#111827", "background2": "#1F2937", "background3": "#374151", "background4": "#4B5563", "background5": "#6B7280", "background6": "#9CA3AF", "background7": "#D1D5DB", "divider": "#374151", "divider2": "#4B5563", "shadow": "#000000", "scrollbarBackground": "#1F2937", "scrollbarThumb": "#6B7280"}}, "font": "Inter", "ctaButton": {"enabled": true, "text": "Join", "link": "https://example.com/join"}, "button": {"enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard"}, "domains": ["example.com"], "communityThemeOverride": true}, "banner": {"enabled": true, "title": "April Challenge", "description": "Compete for the top monthly prize.", "image": "https://cdn.example.com/banners/april.png"}, "translations": {"name": [{"languageCode": "en", "translation": "April Last Leaderboard"}, {"languageCode": "th", "translation": "April Leaderboard TH"}], "description": [{"languageCode": "en", "translation": "Monthly leaderboard created through the partner API."}]}, "enableLeaderboardReset": true, "leaderboardResetFrequency": "weekly", "enablePrizePool": true, "prizes": [{"_id": "prize-1", "position": 1, "positionFrom": null, "positionTo": null, "isRange": false, "prizeName": "Champion Reward", "useRewardAsPrizeName": false, "coins": 1000, "xp": 500, "customFields": [{"id": "wallet-address", "fieldType": "text", "fieldName": "Wallet Address", "description": "Wallet address used for prize delivery.", "placeholderText": "0x...", "isRequired": true, "isExpanded": false}]}, {"_id": "prize-2", "position": null, "positionFrom": 2, "positionTo": 5, "isRange": true, "prizeName": "Top 5 Reward", "useRewardAsPrizeName": false, "coins": 500, "xp": 250, "customFields": []}], "userInformationDisplay": [{"field": "name", "displayMode": "full", "order": 0}, {"field": "email", "displayMode": "partial", "order": 1}], "leaderboardPageConfig": {"bannerDisplay": {"enabled": true}, "rolesUsers": {"roles": ["6502c97314a3e564c5bbfa84"], "users": []}, "viewingPermission": {"roles": ["6502c97314a3e564c5bbfa84"], "users": []}, "enableWidgets": {"enabled": true}, "guestMode": {"enabled": false}, "leftPanel": {"leaderboardName": true, "startAndEndDate": true, "countdown": true, "eventImage": true, "eventDescription": true, "prizePool": true}, "rightPanel": {"podium": true, "userPosition": true, "hallOfChampions": true}, "timeFilterView": {"allTime": true, "daily": true, "weekly": true, "monthly": true, "yearly": false}}, "enabled": true, "previewEnabled": false, "order": 2}'Response Response Example
{"meta": {"status": "success", "statusCode": 200}, "message": "Update leaderboard success.", "data": {"_id": "507f1f77bcf86cd799439012", "communityID": "6502c97314a3e564c5bbfa84", "name": "April Updated Leaderboard", "slug": "april-updated-leaderboard", "description": "Monthly leaderboard updated through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankBy": "currencies", "displayedFields": ["user", "currencies", "xps", "level"], "displayFieldsOrder": ["user", "currencies", "xps", "level"], "timeFilters": ["all-time", "daily", "weekly", "monthly", "yearly"], "performanceDisplay": {"showTop": {"enabled": true, "value": 10}, "showPositive": {"enabled": true}, "showDummy": {"enabled": false}}, "duration": {"start": "30-01-2026", "end": null, "noEndDate": true, "timeZone": 600, "startTime": {"hours": 12, "minutes": 0, "ampm": "AM"}, "endTime": {"hours": 11, "minutes": 59, "ampm": "PM"}}, "rankedUserRoles": {"users": [], "roles": ["6502c97314a3e564c5bbfa84"], "tags": []}, "viewPermissionUserRoles": {"users": [], "roles": ["6502c97314a3e564c5bbfa84"], "tags": []}, "widget": {"enabled": true, "apiKey": "widget-key", "whitelistedDomains": ["example.com"], "size": "dynamic", "width": null, "height": null, "theme": {"default": "dark", "dark": {"name": "Custom Dark", "accent": "#7C3AED", "accent2": "#22C55E", "accent3": "#F59E0B", "accent4": "#EF4444", "text": "#FFFFFF", "text2": "#E5E7EB", "text3": "#D1D5DB", "text4": "#9CA3AF", "text5": "#6B7280", "text6": "#4B5563", "background": "#111827", "background2": "#1F2937", "background3": "#374151", "background4": "#4B5563", "background5": "#6B7280", "background6": "#9CA3AF", "background7": "#D1D5DB", "divider": "#374151", "divider2": "#4B5563", "shadow": "#000000", "scrollbarBackground": "#1F2937", "scrollbarThumb": "#6B7280"}}, "font": "Inter", "ctaButton": {"enabled": true, "text": "Join", "link": "https://example.com/join"}, "button": {"enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard"}, "domains": ["example.com"], "communityThemeOverride": true}, "banner": {"enabled": true, "title": "April Challenge", "description": "Compete for the top monthly prize.", "image": "https://cdn.example.com/banners/april.png"}, "translations": {"name": [{"languageCode": "en", "translation": "April Last Leaderboard"}, {"languageCode": "th", "translation": "April Leaderboard TH"}], "description": [{"languageCode": "en", "translation": "Monthly leaderboard created through the partner API."}]}, "enableLeaderboardReset": true, "leaderboardResetFrequency": "weekly", "enablePrizePool": true, "prizes": [{"_id": "prize-1", "position": 1, "positionFrom": null, "positionTo": null, "isRange": false, "prizeName": "Champion Reward", "useRewardAsPrizeName": false, "coins": 1000, "xp": 500, "customFields": [{"id": "wallet-address", "fieldType": "text", "fieldName": "Wallet Address", "description": "Wallet address used for prize delivery.", "placeholderText": "0x...", "isRequired": true, "isExpanded": false}]}, {"_id": "prize-2", "position": null, "positionFrom": 2, "positionTo": 5, "isRange": true, "prizeName": "Top 5 Reward", "useRewardAsPrizeName": false, "coins": 500, "xp": 250, "customFields": []}], "userInformationDisplay": [{"field": "name", "displayMode": "full", "order": 0}, {"field": "email", "displayMode": "partial", "order": 1}], "leaderboardPageConfig": {"bannerDisplay": {"enabled": true}, "rolesUsers": {"roles": ["6502c97314a3e564c5bbfa84"], "users": []}, "viewingPermission": {"roles": ["6502c97314a3e564c5bbfa84"], "users": []}, "enableWidgets": {"enabled": true}, "guestMode": {"enabled": false}, "leftPanel": {"leaderboardName": true, "startAndEndDate": true, "countdown": true, "eventImage": true, "eventDescription": true, "prizePool": true}, "rightPanel": {"podium": true, "userPosition": true, "hallOfChampions": true}, "timeFilterView": {"allTime": true, "daily": true, "weekly": true, "monthly": true, "yearly": false}}, "enabled": true, "previewEnabled": false, "displayOrder": 2, "order": 2, "selected": false, "createdAt": "2026-05-20T10:00:00.000Z", "updatedAt": "2026-05-20T10:00:00.000Z"}}Modified at 2026-08-19 18:39:45