# HTTP API

Call Wavedash from your own server or automation with an API key.

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

The HTTP API operates on games your team has access to, authenticated with an API key. It's the same API the [CLI](/cli) uses.

<Note>
API keys act on your behalf across every game in your team — keep them on a server you control, never in a game build. Use the [SDK](/sdk) for anything running in a player's browser.
</Note>

## Base URL

```text
https://api.wavedash.com
```

## Authentication

Send your API key as a bearer token:

```bash
-H "Authorization: Bearer $WAVEDASH_TOKEN"
```

Create a key in the Developer Portal under **API Keys**. See [Authentication](/api/authentication) for scope and handling.

## Game IDs

Game-scoped paths take your game's ID, which is the `game_id` in your [`wavedash.toml`](/cli/configuration).

## Responses

Successful calls return `200` with a JSON body. Errors return an `error` message and a stable `code` — branch on `code`, not the message text.

```json
{
  "error": "Leaderboard not found",
  "code": "not_found"
}
```

| Status | Meaning |
| --- | --- |
| `400` | `invalid_input` — the request body failed validation. |
| `401` | `unauthorized` — missing header, or the API key isn't valid. |
| `403` | `forbidden` — your team can't access that game, or the game ID is malformed. |
| `404` | `not_found` — the game or resource doesn't exist. |
| `500` | `fatal` — something broke on our side. Safe to retry. |

## Endpoints

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield" href="/api/authentication">
    API keys, scope, and handling.
  </Card>
  <Card title="Leaderboards" icon="medal" href="/api/leaderboards">
    Update a leaderboard.
  </Card>
</CardGroup>

Builds, stats, and achievements are managed through the [CLI](/cli/commands).