Start matchmaking

curl --request POST \
  --url https://api.computeflow.cloud/api/v3/lobbies/{config}/me/matchmaking \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'x-player-id: <x-player-id>' \
  --data '
{
  "mode": "<string>"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "config": "<string>",
  "host": "<string>",
  "maxPlayers": 123,
  "currentPlayers": 123,
  "region": "<string>",
  "isPrivate": true,
  "allowLateJoin": true,
  "settings": {},
  "players": [
    {
      "id": "<string>",
      "state": {},
      "isHost": true
    }
  ],
  "server": {
    "instance_id": "<string>",
    "name": "<string>",
    "network_ports": [
      {
        "name": "<string>",
        "internal_port": 123,
        "external_port": 123,
        "host": "<string>",
        "tls_enabled": true
      }
    ],
    "startup_args": "<string>",
    "compute_size": "<string>",
    "region": "<string>",
    "version_tag": "<string>",
    "version": 123,
    "started_at": "2023-11-07T05:31:56Z",
    "stopped_at": "2023-11-07T05:31:56Z",
    "auto_restart": true,
    "custom_data": {},
    "ttl": 123,
    "is_pool_server": true,
    "pool_claimed_at": "2023-11-07T05:31:56Z",
    "match_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "matchmaking": {
    "mode": "<string>",
    "startedAt": "<string>",
    "queueStats": {
      "playersSearching": 123,
      "lobbiesInQueue": 123,
      "avgWaitSeconds": 123
    },
    "confirmation": {
      "deadline": "<string>",
      "confirmed": true
    }
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Lobbies

Start matchmaking

Host only. Enters the lobby into the matchmaking queue for the specified mode.

The mode must be a matchmaking mode defined in the lobby config (e.g. "ranked_2v2", "casual_ffa").

How it works:

Lobby status transitions to in_queue
The matchmaking system immediately attempts to find compatible opponents
If no immediate match, the lobby waits in the queue
When matched, status transitions to match_found and a game server is started

Queue stats: The response includes matchmaking.queueStats with the number of players searching and average wait time. Players receive live updates via SSE (queue_stats events every 10 seconds).

Cancel: Use DELETE /{config}/me/matchmaking to leave the queue and return to waiting.

POST

api

lobbies

{config}

matchmaking

Start matchmaking

curl --request POST \
  --url https://api.computeflow.cloud/api/v3/lobbies/{config}/me/matchmaking \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'x-player-id: <x-player-id>' \
  --data '
{
  "mode": "<string>"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "config": "<string>",
  "host": "<string>",
  "maxPlayers": 123,
  "currentPlayers": 123,
  "region": "<string>",
  "isPrivate": true,
  "allowLateJoin": true,
  "settings": {},
  "players": [
    {
      "id": "<string>",
      "state": {},
      "isHost": true
    }
  ],
  "server": {
    "instance_id": "<string>",
    "name": "<string>",
    "network_ports": [
      {
        "name": "<string>",
        "internal_port": 123,
        "external_port": 123,
        "host": "<string>",
        "tls_enabled": true
      }
    ],
    "startup_args": "<string>",
    "compute_size": "<string>",
    "region": "<string>",
    "version_tag": "<string>",
    "version": 123,
    "started_at": "2023-11-07T05:31:56Z",
    "stopped_at": "2023-11-07T05:31:56Z",
    "auto_restart": true,
    "custom_data": {},
    "ttl": 123,
    "is_pool_server": true,
    "pool_claimed_at": "2023-11-07T05:31:56Z",
    "match_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "matchmaking": {
    "mode": "<string>",
    "startedAt": "<string>",
    "queueStats": {
      "playersSearching": 123,
      "lobbiesInQueue": 123,
      "avgWaitSeconds": 123
    },
    "confirmation": {
      "deadline": "<string>",
      "confirmed": true
    }
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

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.

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.

Show child attributes

players

object[]

required

Players in the lobby with their state.

Show child attributes

server

object

required

Game server info (null when no game running).

Show child attributes

matchmaking

object

required

Matchmaking info (null when not searching).

Show child attributes

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last update timestamp.

Start the game Cancel matchmaking

Documentation Index

Authorizations

Headers

Path Parameters

Body

Response