Skip to main content
POST
Start matchmaking

Authorizations

api-key
string
header
required

Headers

x-player-id
string
required

Unique player identifier. Must be the lobby host.

Path Parameters

config
string
required

Lobby configuration name or ID.

Body

application/json

Start matchmaking. The lobby enters the queue and is matched with compatible opponents.

mode
string
required

Matchmaking mode name from the lobby config (e.g. "ranked_2v2", "casual_ffa").

Minimum string length: 1

Response

Matchmaking started. Status is in_queue. The matchmaking field includes mode, startedAt, and queueStats.

Full lobby state including players, server, and matchmaking info.

id
string<uuid>
required

Lobby ID.

code
string | null
required

Invite code for joining (null if private mode is disabled).

config
string
required

Lobby config name.

status
enum<string>
required

Current lobby status.

Available options:
waiting,
in_queue,
starting,
matched,
match_found,
in_game
host
string
required

Player ID of the host.

maxPlayers
number
required

Maximum player capacity.

currentPlayers
number
required

Current number of players.

region
string | null
required

Preferred game server region.

isPrivate
boolean
required

Whether the lobby is hidden from browsing.

allowLateJoin
boolean
required

Whether players can join mid-game.

settings
object
required

Custom game settings.

players
object[]
required

Players in the lobby with their state.

server
object | null
required

Game server info (null when no game running).

matchmaking
object | null
required

Matchmaking info (null when not searching).

createdAt
string
required

ISO 8601 creation timestamp.

updatedAt
string
required

ISO 8601 last update timestamp.

matchmakingError
string | null

Set when a queue entry was failed after repeated server-create failures. Explains why the match never formed; the lobby is returned to waiting so the player can retry.