HTTP API

The HTTP API is available unless the relay starts with --disable-http. It listens on port 7771 by default.

All endpoints except GET /health require a bearer token:

Authorization: Bearer <BLITZ_RELAY_HTTP_ADMIN_TOKEN>

The server-wide admin token authorises every protected endpoint. DELETE /rooms/{roomCode}, PATCH /rooms/{roomCode}, and DELETE /rooms/{roomCode}/clients/{virtualClientId} also accept the room host token returned to the active UDP host in RoomCreated.

Endpoints

Method	Path	Authentication	Result
GET	/health	None	200 OK when the API is running.
POST	/rooms	Admin	Creates a persistent reserved room.
GET	/rooms	Admin	Lists room snapshots.
GET	/rooms/{roomCode}	Admin	Returns a room snapshot.
DELETE	/rooms/{roomCode}	Admin or room host	Closes the room and disconnects its peers.
PATCH	/rooms/{roomCode}	Admin or room host	Updates the display name and metadata.
DELETE	/rooms/{roomCode}/clients/{virtualClientId}	Admin or room host	Disconnects the selected client.

Room codes are case-insensitive.

Room snapshot

Room endpoints return this shape:

{
  "code": "ABC12345",
  "kind": "PersistentReserved",
  "isPublic": true,
  "displayName": "Ranked match",
  "maximumClients": 8,
  "connectedClientCount": 3,
  "hasHost": true,
  "hasPendingHostClaim": false,
  "metadata": {
    "region": "eu"
  }
}

connectedClientCount counts clients, not the active host or a client currently transitioning through host promotion.

Create a room

POST /rooms
Content-Type: application/json

{
  "maximumClients": 8,
  "displayName": "Ranked match",
  "isPublic": true,
  "metadata": {
    "region": "eu"
  }
}

All properties are optional. maximumClients defaults to 4096, displayName to an empty string, isPublic to false, and metadata to an empty dictionary. The client limit must be between 1 and 65,535 because the request field is an unsigned 16-bit integer. The display name must be no more than 255 UTF-8 bytes.

Success returns 200 OK with the new room snapshot. Invalid input returns 400 Bad Request; a missing or invalid token returns 401 Unauthorized.

List and get rooms

GET /rooms returns 200 OK with an array containing every room, including ephemeral rooms. GET /rooms/{roomCode} returns one snapshot or 404 Not Found.

Both endpoints require the server-wide admin token. Room host tokens cannot read room snapshots.

Update room metadata

PATCH /rooms/ABC12345
Content-Type: application/json

{
  "displayName": "Ranked match 2",
  "metadataToAdd": {
    "mode": "ranked"
  },
  "metadataToRemove": ["region"]
}

Every property is optional. A non-null displayName replaces the current value and must be no more than 255 UTF-8 bytes. metadataToRemove is applied before metadataToAdd; metadata keys are case-insensitive.

Success returns 200 OK with the updated snapshot. An unknown room returns 404 Not Found.

Close a room or disconnect a client

Closing a room sends an Error frame with RoomClosed to its host and clients, then disconnects them. Kicking a client sends Disconnected with that client’s virtual ID before disconnecting it.

Both operations return 204 No Content on success and 404 Not Found when the requested room or client does not exist. A token that is valid for another room returns 401 Unauthorized.