# Leaderboards

Update a leaderboard over HTTP.

Source: https://docs.wavedash.com/api/leaderboards

## Update a leaderboard

```text
PATCH /api/games/{gameId}/leaderboards/by-name/{name}
PATCH /api/games/{gameId}/leaderboards/{leaderboardId}
```

Address the leaderboard by the `name` it was created with, or by its ID. Both forms behave identically.

Names are normalized before lookup: lowercased, whitespace collapsed to underscores, and anything outside `a-z`, `0-9`, `_`, `-` removed. `Daily Scores` resolves to `daily_scores`.

### Body

Every field is optional; only the ones you send change. An empty body returns `400`.

| Field | Description |
| --- | --- |
| `visible` | Boolean. Whether the leaderboard appears on the game's store page. |
| `displayName` | String, 1–200 characters. The label players see. |
| `sortOrder` | Integer. `0` ascending (lowest score is best), `1` descending. Changing this re-ranks existing scores. |
| `displayType` | Integer. `0` numeric, `1` seconds, `2` milliseconds, `3` game ticks. |

`name` can't be changed here — it's the identifier scores are submitted against. Rename in the Developer Portal.

### Example

```bash
curl "https://api.wavedash.com/api/games/$GAME_ID/leaderboards/by-name/$LEADERBOARD_NAME" \
  -X PATCH \
  -H "Authorization: Bearer $WAVEDASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"visible": true}'
```

### Response

Returns the leaderboard after the update.

```json
{
  "leaderboard": {
    "id": "nh723mf0hrq4gmsfxg03k4wmw98b70re",
    "name": "daily_scores",
    "displayName": "Daily Scores",
    "sortOrder": 1,
    "displayType": 0,
    "visible": true
  }
}
```

### Errors

In addition to the [standard codes](/api#responses):

| Status | When |
| --- | --- |
| `400` | `invalid_input` — no fields supplied, or a value outside its allowed range. |
| `404` | `not_found` — no leaderboard on that game with the given name or ID. |