Returning.AIDevelopers
v1

API reference / Gamification / Leaderboards

.md

Update an existing leaderboard

Change the settings of one leaderboard in the community that owns your API key, sending only the fields you want to change.

Last updated 26 Sep 2026API v1

Method
PATCH
Path
https://api.returning.ai/v1/leaderboards/{leaderboardID}
Permission
leaderboard
Retries
No Idempotency-Key; read back before retrying

When to use this

  • Extend a competition's end date or switch a leaderboard on or off.
  • Change who can see or be ranked on a leaderboard.
  • Add prizes, or change the columns traders see in the table.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
leaderboardShown in the dashboard as “Leaderboard”

Send a Community API key with the leaderboard permission. The key decides the community, so a leaderboard in another community returns 404.

Behaviour#

Only the fields you send change, and the change shows to traders straight away. Unknown fields are ignored, so check spelling. Each of these groups is replaced as a whole when you send any field in it:

  • Schedule: startDate, endDate, hasNoEndDate, timeZone, startTime, endTime. startDate is required, and any part you leave out goes back to its default: no end date off, UTC, 12:00 AM to 11:59 PM. Read the leaderboard first and send the full schedule.
  • Rank lists and view lists: sending one allowed...ToRank list empties the other two rank lists, and the same goes for view lists. Empty arrays are ignored, so a rank or view list can't be cleared completely.
  • Display flags: topRankOnly, topRankLimit, onlyPositiveRanks, includeDummyUsers. The ones you leave out are switched off.
  • Lists and settings objects: displayedColumns, allowedTimeFilters, prizes, widget, banner, translations and userInformationDisplay replace the current value.

displayOrder moves the leaderboard and shifts the others to make room. The Default Leaderboard can be renamed and switched on or off here, but its rank and view lists can only be changed in the dashboard. Switching it on or off also switches the leaderboard feature for your community, and each change to it is logged in configurationHistory.

Request#

Path parameters#

leaderboardID#stringREQUIRED
The leaderboard's _id, from List leaderboards or Create leaderboard.

Rule24-character hex ID

Eg66f000000000000000000301

Headers#

Authorization#stringREQUIRED
Community API key with leaderboard.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

Send only the fields you want to change. An empty body changes nothing and returns the leaderboard as it is. Several fields have an older alias, such as rankBy for rankingField; send one of each pair.

name#stringOPTIONAL
New name shown to traders. Other leaderboards' names aren't checked, so keep names unique yourself.

Rule1-100 chars

Eg"Monthly Trading Volume"

slug#stringOPTIONAL
New URL-friendly ID. Must be unique in your community.

Rule1-100 chars; lowercase letters, numbers and single hyphens

Eg"monthly-trading-volume"

description#stringOPTIONAL
New description shown to traders.

Eg"Top traders by trading volume each month."

image#stringOPTIONAL
Leaderboard image URL. Wins over leaderImage if you send both.

Rulehttp or https URL

Eg"https://cdn.example.com/leaderboards/monthly-volume.png"

isEnabled#booleanOPTIONAL
true makes the leaderboard live for the traders who can see it; false hides it.

Egtrue

rankingField#stringOPTIONAL
What traders are ranked by: XP, Coins, Referrals, or the key of a user field in your community. Anything else returns 400.

RuleXP, Coins, Referrals or a user-field key; no spaces

Eg"tradingvolume"

displayedColumns#arrayOPTIONAL
The table's columns, in order, replacing the current ones. Send names, or objects with column, order and visible to hide one. user is always the first column.

RuleUp to 50

Eg["user", "tier", "level"]

startDate#stringOPTIONAL
First day of the leaderboard. Required whenever you send any schedule field (endDate, hasNoEndDate, timeZone, startTime, endTime).

RuleISO 8601 or DD-MM-YYYY

Eg"2026-10-01T00:00:00.000Z"

endDate#stringOPTIONAL
Last day of the leaderboard, or null for none. Send it with startDate.

RuleISO 8601, DD-MM-YYYY or null

Eg"2026-12-31T00:00:00.000Z"

hasNoEndDate#booleanOPTIONAL
true when the leaderboard has no end date. Reset to false if you change the schedule without it.
timeZone#numberOPTIONAL
Time zone as minutes from UTC. Reset to 0 (UTC) if you change the schedule without it.

RuleMinutes, e.g. 480 for UTC+8

Eg0

startTime#objectOPTIONAL
Time of day the leaderboard and each reset period start, as hours (1-12), minutes (0-59) and ampm. Reset to 12:00 AM if you change the schedule without it.
endTime#objectOPTIONAL
Time of day the leaderboard ends on endDate, in the same format. Reset to 11:59 PM if you change the schedule without it.
allowedTimeFilters#string[]OPTIONAL
Period tabs traders can switch between: all-time, daily, weekly, monthly, yearly. Replaces the current tabs.

Eg["monthly", "all-time"]

allowedRolesToRank#arrayOPTIONAL
Roles whose traders get ranked, by name or ID. @all covers every trader. Sending any rank list replaces all three; lists you leave out become empty.

Eg["@all"]

allowedUsersToRank#arrayOPTIONAL
Traders to rank one by one, by platform user ID, username or email. Each must be a member of your community.

Eg["3247779"]

allowedTagsToRank#arrayOPTIONAL
Tags whose traders get ranked, by name or ID.

Eg[]

allowedRolesToView#arrayOPTIONAL
Roles whose traders can see the leaderboard, by name or ID. Sending any view list replaces all three; lists you leave out become empty.

Eg["@all"]

allowedUsersToView#arrayOPTIONAL
Traders who can see the leaderboard, by platform user ID, username or email.

Eg[]

allowedTagsToView#arrayOPTIONAL
Tags whose traders can see the leaderboard, by name or ID.

Eg[]

displayOrder#numberOPTIONAL
New position among your leaderboards, starting at 1. The others move to make room. 0 leaves the position unchanged.

RuleWhole number, 0 or more

Eg2

enableLeaderboardReset#booleanOPTIONAL
true restarts scores every period and keeps each finished period as history.

Egtrue

leaderboardResetFrequency#stringOPTIONAL
How often scores restart. Required when you send enableLeaderboardReset as true.

Ruledaily, weekly, monthly, yearly

Eg"monthly"

enablePrizePool#booleanOPTIONAL
true pays the prizes rows to the winners when a period ends.

Egfalse

prizes#object[]OPTIONAL
Prize rows by rank, replacing the current ones. Each row has the same fields as in Create leaderboard.

Eg[]

topRankOnly#booleanOPTIONAL
true blurs rows below the top topRankLimit ranks. Sending any of topRankOnly, topRankLimit, onlyPositiveRanks or includeDummyUsers resets the ones you leave out to off.
topRankLimit#numberOPTIONAL
How many top ranks stay visible. Must be 1 or more when topRankOnly is true.

RuleWhole number, 1 or more when topRankOnly is true

onlyPositiveRanks#booleanOPTIONAL
true shows only traders with a score above 0.
includeDummyUsers#booleanOPTIONAL
Older setting for filling the table with placeholder traders. Leave it out.
isPreviewEnabled#booleanOPTIONAL
true lets guests see the leaderboard, if your community allows guest preview.
widget#objectOPTIONAL
Embeddable widget settings, replacing the current ones. Most integrations leave this out.
enabled#booleanOPTIONAL
true when the widget can be embedded.

Egtrue

apiKey#stringOPTIONAL
Key the embedded widget uses.

Eg"wgt_live_abc123"

size#stringOPTIONAL
Widget size setting.

Eg"fixed"

width#numberOPTIONAL
Widget width in pixels.

Eg420

height#numberOPTIONAL
Widget height in pixels.

Eg640

theme#objectOPTIONAL
Widget colours.

Eg{ ... }

font#objectOPTIONAL
Widget font.

Eg{"family": "Inter", "size": 14}

ctaButton#objectOPTIONAL
Call-to-action button settings.

Eg{ ... }

domains#string[]OPTIONAL
Domains allowed to embed the widget.

Eg["example.com", "partners.example.com"]

communityThemeOverride#booleanOPTIONAL
true when the widget uses its own colours instead of your community theme.

Egfalse

banner#objectOPTIONAL
Banner settings, replacing the current ones. Most integrations leave this out.

Eg{ ... }

translations#objectOPTIONAL
Translated names and descriptions, as name and description lists of languageCode and translation. Replaces the current translations.

Eg{ ... }

userInformationDisplay#object[]OPTIONAL
How much of each trader's details the table shows, per field, as full or partial. Replaces the current settings.

Eg{"showAvatar": true, "showName": true, "showEmail": false}

leaderboardPageConfig#objectOPTIONAL
Leaderboard page layout settings. Most integrations leave this out.

Eg{"showHeader": true, "showFilters": true, "rowsPerPage": 25}

leaderImage#stringOPTIONAL
Alias for image. image wins if you send both.

RuleUp to 2,000 chars

Eg"https://cdn.example.com/leaderboards/spring.png"

rankBy#stringOPTIONAL
Alias for rankingField. rankingField wins if you send both.

Eg"points"

displayedFields#string[]OPTIONAL
Visible columns. Alias for displayedColumns; send it with displayFieldsOrder.

Eg["rank", "name", "points", "orders"]

displayFieldsOrder#string[]OPTIONAL
Column order. Alias for displayedColumns; send it with displayedFields.

Eg["rank", "name", "points", "orders"]

timeFilters#string[]OPTIONAL
Alias for allowedTimeFilters. allowedTimeFilters wins if you send both.

Eg["all", "monthly", "weekly"]

duration#objectOPTIONAL
The schedule as one object. Alias for startDate, endDate, hasNoEndDate, timeZone, startTime and endTime, which win if you send them. start is required.
start#stringREQUIRED
First day of the leaderboard.

Eg"2026-05-01T00:00:00.000Z"

end#stringOPTIONAL
Last day, or null.

RuleNullable

Egnull

noEndDate#booleanOPTIONAL
true when there is no end date.
timeZone#numberOPTIONAL
Minutes from UTC.
startTime#objectOPTIONAL
Start time of day.
endTime#objectOPTIONAL
End time of day.
rankedUserRoles#objectOPTIONAL
The rank lists as one object with users, roles and tags. Alias for the allowed...ToRank fields, which win if you send them.

Eg["customer", "affiliate"]

viewPermissionUserRoles#objectOPTIONAL
The view lists as one object with users, roles and tags. Alias for the allowed...ToView fields, which win if you send them.

Eg["customer", "affiliate", "admin"]

performanceDisplay#objectOPTIONAL
The display flags as one object, showTop (enabled, value), showPositive and showDummy. Alias for topRankOnly, topRankLimit, onlyPositiveRanks and includeDummyUsers, which win if you send them.

Eg"score"

enabled#booleanOPTIONAL
Alias for isEnabled. isEnabled wins if you send both.

Egtrue

previewEnabled#booleanOPTIONAL
Alias for isPreviewEnabled. isPreviewEnabled wins if you send both.

Egfalse

order#numberOPTIONAL
Alias for displayOrder. order wins if you send both.

Eg2

curl --request PATCH \
  --url https://api.returning.ai/v1/leaderboards/66f000000000000000000301 \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Top traders by trading volume each month. Prizes for the top 3.",
    "allowedTimeFilters": ["monthly", "all-time"],
    "isEnabled": true
  }'

Response#

A 200 returns the whole leaderboard after your change in data, with user, role and tag references expanded, in the same shape as Get leaderboard. Branch on the HTTP status.

meta#objectALWAYS
Status of the request. There is no meta.code on success.
status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.
message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The leaderboard after your changes, in the same shape as Get leaderboard.

Eg{ ... }

_id#string
Leaderboard ID.

Eg"66f000000000000000000301"

communityID#string
Your community ID.
kind#string
default for your community's built-in Default Leaderboard; custom for every other leaderboard.
name#string
Leaderboard name.

Eg"Monthly Trading Volume"

slug#string
URL-friendly ID.

Eg"monthly-trading-volume"

description#string
Description shown to traders.
image#string
Leaderboard image URL, when one is set.
enabled#boolean
true when the leaderboard is live.

Egtrue

displayOrder#number
Position among your leaderboards.

Eg2

order#number
Same value as displayOrder.

Eg2

rankBy#string
What traders are ranked by.
duration#object
The schedule. timeZone is minutes from UTC.

Eg{ ... }

start#string
Start date.

Eg"2026-10-01T00:00:00.000Z"

end#string
End date, or null when there is none.

RuleNullable

Egnull

noEndDate#boolean
true when the leaderboard runs with no end date.
timeZone#number
Time zone as minutes from UTC.
startTime#object
Start time of day, as hours (1-12), minutes and ampm.
endTime#object
End time of day, in the same format.
timeFilters#string[]
Period tabs.
rankedUserRoles#object
Rank lists, expanded: traders as id (numeric platform user ID), _id, username and email; roles and tags as _id and name.
viewPermissionUserRoles#object
View lists, in the same shape.
enableLeaderboardReset#boolean
true when scores restart every period.

Egtrue

leaderboardResetFrequency#string
How often scores restart.

Eg"monthly"

enablePrizePool#boolean
true when prizes are paid.

Egfalse

prizes#object[]
Prize rows.

Eg[]

banner#object
Banner settings.

Eg{}

userInformationDisplay#object[]
Trader detail display settings.

Eg[]

previewEnabled#boolean
true when guests can see it.

Egfalse

selected#boolean
true for the one leaderboard your community has set as its active leaderboard.

Egfalse

updatedAt#string
When the leaderboard last changed, ISO 8601 UTC.

Eg"2026-09-27T09:00:00.000Z"

createdAt#string
When the leaderboard was created, ISO 8601 UTC.

Eg"2026-09-26T08:30:00.000Z"

widget#object
Widget settings, when set.

Eg{"enabled": true, "size": "fixed", "width": 420, "height": 640}

translations#object
Translations, when set.
leaderboardPageConfig#object
Page layout settings, when set.
configurationHistory#object[]
Log of settings changes. Present only on the Default Leaderboard after it has been changed.
displayedFields#string[]
Visible columns. user comes first.
displayFieldsOrder#string[]
Column order.
performanceDisplay#object
The display flags.
{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Update leaderboard success.",
  "data": {
    "_id": "66f000000000000000000301",
    "communityID": "66f000000000000000000010",
    "kind": "custom",
    "name": "Monthly Trading Volume",
    "slug": "monthly-trading-volume",
    "description": "Top traders by trading volume each month. Prizes for the top 3.",
    "rankBy": "tradingvolume",
    "displayedFields": ["user", "tier", "level"],
    "displayFieldsOrder": ["user", "tier", "level"],
    "timeFilters": ["monthly", "all-time"],
    "performanceDisplay": {
      "showTop": {
        "enabled": false,
        "value": 0
      },
      "showPositive": {
        "enabled": false
      },
      "showDummy": {
        "enabled": false
      }
    },
    "duration": {
      "start": "2026-10-01T00:00:00.000Z",
      "end": null,
      "noEndDate": true,
      "timeZone": 0,
      "startTime": {
        "hours": 12,
        "minutes": 0,
        "ampm": "AM"
      },
      "endTime": {
        "hours": 11,
        "minutes": 59,
        "ampm": "PM"
      }
    },
    "rankedUserRoles": {
      "users": [],
      "roles": [
        {
          "_id": "66f000000000000000000502",
          "name": "@all"
        }
      ],
      "tags": []
    },
    "viewPermissionUserRoles": {
      "users": [],
      "roles": [
        {
          "_id": "66f000000000000000000502",
          "name": "@all"
        }
      ],
      "tags": []
    },
    "banner": {},
    "enableLeaderboardReset": true,
    "leaderboardResetFrequency": "monthly",
    "enablePrizePool": false,
    "prizes": [],
    "userInformationDisplay": [],
    "enabled": true,
    "previewEnabled": false,
    "selected": false,
    "displayOrder": 2,
    "order": 2,
    "updatedAt": "2026-09-27T09:00:00.000Z",
    "createdAt": "2026-09-26T08:30:00.000Z"
  }
}

Errors#

401, 403 and 400 VALIDATION_FAILED errors carry a code in meta.code. Other errors from this endpoint have no code; branch on the HTTP status and read detail.

Fix the request05

400Fix the request
The change can't be applied. There is no meta.code; detail says why, such as Invalid rankBy value: ..., rankedUserRoles.users[0] could not be resolved for this community., an invalid date, or Update Default Leaderboard access through Leaderboard Settings (the Default Leaderboard's rank and view lists can only be changed in the dashboard). Nothing changed.
400VALIDATION_FAILEDFix the request
A field breaks a format rule, such as a malformed leaderboardID, a slug with capitals or spaces, a schedule change without startDate (detail names payload.duration.start), topRankOnly without a topRankLimit of 1 or more, or enableLeaderboardReset without leaderboardResetFrequency. detail names the field. Nothing changed.
401AUTH_API_KEY_REQUIREDFix the request
No key was sent. Send Authorization: Bearer <API_KEY>.
401AUTH_API_KEY_INVALIDFix the request
The key is unknown, expired or malformed. Use a current Community API key.
403AUTH_PERMISSION_REQUIREDFix the request
The key lacks leaderboard. Add the permission in Settings > Integration > API Keys.

Fix the data02

404Fix the data
No leaderboard with this ID in your community (Leaderboard not found: <id>). It may have been deleted, or belong to another community. Find the ID again with List leaderboards.
409Fix the data
Another leaderboard in your community already has this slug (Slug already exists: <slug>). Choose another slug.

Retry with backoff03

500Retry with backoff
The update failed unexpectedly. A displayOrder change is saved before the other fields, so read the leaderboard with Get leaderboard before you send it again.
502Retry with backoff
Leaderboards are briefly unavailable, and the outcome is unknown. Read the leaderboard with Get leaderboard, then retry with backoff if the change is missing.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now, and nothing changed. Retry with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "slug": "slug must contain only lowercase letters, numbers, and hyphens"
  },
  "solution": "Please check the request and try again"
}

Next step#

Get leaderboardGET/v1/leaderboards/{leaderboardID}Read the leaderboard back to confirm the change.