Returning.AIDevelopers
v1

API reference / Gamification / Leaderboards

.md

Delete a leaderboard

Permanently delete one leaderboard in the community that owns your API key.

Last updated 26 Sep 2026API v1

Method
DELETE
Path
https://api.returning.ai/v1/leaderboards/{leaderboardID}
Permission
leaderboard
Retries
No Idempotency-Key; check with Get leaderboard first

When to use this

  • Remove a test leaderboard you created while building your integration.
  • Clean up a finished competition you no longer want traders to see.

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 you can only delete leaderboards in that community.

Behaviour#

The leaderboard is removed straight away and can't be restored. Leaderboards after it in your display order move up one place to close the gap.

Your community's Default Leaderboard can't be deleted. Check kind with Get leaderboard: only custom leaderboards can be deleted.

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>

curl --request DELETE \
  --url https://api.returning.ai/v1/leaderboards/66f000000000000000000301 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the deleted leaderboard's ID as a string in data. Branch on the HTTP status.

data#stringALWAYS
The ID of the deleted leaderboard, as a string.

Eg"66f000000000000000000301"

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.
{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Delete leaderboard success.",
  "data": "66f000000000000000000301"
}

Errors#

401, 403 and 400 VALIDATION_FAILED errors carry a code in meta.code. Other errors have no code; branch on the HTTP status and read detail. An ID that doesn't match a leaderboard in your community returns 500, not 404.

Fix the request04

403Fix the request
The key lacks leaderboard (meta.code is AUTH_PERMISSION_REQUIRED). Add the permission in Settings > Integration > API Keys.
400VALIDATION_FAILEDFix the request
leaderboardID isn't a 24-character hex ID. detail names it. Nothing was deleted.
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.

Fix the data01

400Fix the data
detail is The Default Leaderboard cannot be deleted. Your community's built-in leaderboard (kind default) can't be deleted; switch it off with Update an existing leaderboard instead.

Retry with backoff03

500Retry with backoff
The delete failed, or no leaderboard in your community has this ID (an unknown ID returns 500, not 404). List leaderboards to check the ID before you retry.
502Retry with backoff
Leaderboards are briefly unavailable, and the outcome is unknown. Check with Get leaderboard before you retry.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now, and nothing was deleted. Retry with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 403,
    "code": "AUTH_PERMISSION_REQUIRED"
  },
  "message": "Insufficient API key permissions",
  "detail": "API key is missing required permissions: leaderboard",
  "solution": "Update the API key permissions or use a key with the required permissions"
}

Next step#

List leaderboardsGET/v1/leaderboardsConfirm the leaderboard is gone, and check the new display order of the rest.