# Delete a leaderboard

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

- Endpoint: `DELETE https://api.returning.ai/v1/leaderboards/{leaderboardID}`
- Section: Gamification / Leaderboards
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `leaderboard` (Shown in the dashboard as "Leaderboard")
- Retries: No Idempotency-Key; check with Get leaderboard first
- Guide: hand-written
- Verified: code, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/gamification-leaderboards/delete-a-leaderboard

## 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.

**Instead:** Use [Update an existing leaderboard](https://docs.returning.ai/api-reference/gamification-leaderboards/update-an-existing-leaderboard.md) instead, with `isEnabled` set to `false`, to hide a leaderboard but keep it.

**Permanent:** A deleted leaderboard can't be restored. To take one down for now, switch it off with Update an existing leaderboard.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `leaderboardID` | `string` | Yes | The leaderboard's `_id`, from List leaderboards or Create leaderboard. (24-character hex ID) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `leaderboard`. (`Bearer <API_KEY>`) |

### Example request

```bash
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.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `data` | `string` | always | The ID of the deleted leaderboard, as a string. |
| `meta` | `object` | always | Status of the request. There is no `meta.code` on success. |
| `meta.status` | `string` | always | Result of the request. (`success`) |
| `meta.statusCode` | `integer` | always | The HTTP status, repeated. |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 403 | - | The key lacks `leaderboard` (`meta.code` is `AUTH_PERMISSION_REQUIRED`). Add the permission in Settings > Integration > API Keys. |
| 400 | `VALIDATION_FAILED` | `leaderboardID` isn't a 24-character hex ID. `detail` names it. Nothing was deleted. |
| 401 | `AUTH_API_KEY_REQUIRED` | No key was sent. Send `Authorization: Bearer <API_KEY>`. |
| 401 | `AUTH_API_KEY_INVALID` | The key is unknown, expired or malformed. Use a current Community API key. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | `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 backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | 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. |
| 502 | - | Leaderboards are briefly unavailable, and the outcome is unknown. Check with Get leaderboard before you retry. |
| 401 | `AUTH_API_KEY_VALIDATION_FAILED` | The key could not be checked just now, and nothing was deleted. Retry with backoff. |

**Retries:** This endpoint does not accept an `Idempotency-Key`. After a timeout, a `500` or a `502`, call Get leaderboard with the same ID: a `404` there means the leaderboard is gone and you shouldn't delete again. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [List leaderboards](https://docs.returning.ai/api-reference/gamification-leaderboards/list-leaderboards.md): `GET /v1/leaderboards`. Confirm the leaderboard is gone, and check the new display order of the rest.
- [Start a new competition with Create leaderboard](https://docs.returning.ai/api-reference/gamification-leaderboards/create-leaderboard.md): `POST /v1/leaderboards`.