# LobbyLab Multiplayer API reference

Status: private alpha. `https://api.lobbylab.gg` answers once the alpha opens; request a key at https://lobbylab.gg/developers. The routes below are the published contract and may still change before then.

## Conventions

- Base URL `https://api.lobbylab.gg`. JSON bodies, `Authorization: Bearer <key or token>`.
- Keys: a publishable key (`llpk_...`) for clients, checked against the project's allowed origins, and a secret key (`llsk_...`) for your backend only. Players act with short-lived player tokens.
- Creates accept an `Idempotency-Key` header (a UUID): a retry with the same key and body returns the first answer.
- Every error is a JSON body with a stable `error` code, a `detail`, usually a `next` step and a `docsUrl`. See [every error code](/docs/errors).

## Client routes

| Method | Path | Auth | Ships |
|---|---|---|---|
| POST | `/v1/auth/anonymous` | publishable key | alpha |
| POST | `/v1/rooms` | player token | alpha |
| POST | `/v1/rooms/join` | player token | alpha |
| POST | `/v1/rooms/{roomId}/join` | player token | alpha |
| POST | `/v1/matchmake` | player token | alpha |
| GET | `/v1/rooms` | publishable key | alpha |
| GET | `/v1/rooms/{roomId}` | player token | alpha |
| POST | `/v1/rooms/{roomId}/seat` | player token | alpha |
| POST | `/v1/rooms/{roomId}/leave` | player token | alpha |
| POST | `/v1/rooms/{roomId}/reports` | player token | after the alpha |
| GET | `/v1/plans` | none | alpha |

## Server routes

| Method | Path | Auth | Ships |
|---|---|---|---|
| POST | `/v1/player-tokens` | secret key (backend only) | alpha |
| POST | `/v1/rooms` | secret key (backend only) | alpha |
| GET | `/v1/rooms` | secret key (backend only) | alpha |
| GET | `/v1/rooms/{roomId}` | secret key (backend only) | alpha |
| GET | `/v1/config` | secret key (backend only) | alpha |
| PUT | `/v1/config` | secret key (backend only) | alpha |
| GET | `/v1/usage` | secret key (backend only) | alpha |
| DELETE | `/v1/rooms/{roomId}` | secret key (backend only) | after the alpha |
| GET | `/v1/rooms/{roomId}/state` | secret key (backend only) | after the alpha |
| PATCH | `/v1/rooms/{roomId}/state` | secret key (backend only) | after the alpha |
| POST | `/v1/rooms/{roomId}/messages` | secret key (backend only) | after the alpha |
| POST | `/v1/rooms/{roomId}/members/{memberId}/kick` | secret key (backend only) | after the alpha |

## After you have a seat

Open the seat's `wsUrl` and speak `multiplayer-wire/v0`: see the [wire protocol](/docs/protocol) and the [room lifecycle](/docs/rooms).