Skip to main content
POST
/
api
/
v3
/
lobbies
/
{config}
Create a lobby
curl --request POST \
  --url https://api.computeflow.cloud/api/v3/lobbies/{config} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'x-player-id: <x-player-id>' \
  --data '
{
  "name": "<string>",
  "region": "us-east",
  "maxPlayers": 2,
  "isPrivate": false,
  "allowLateJoin": true,
  "settings": {},
  "state": {}
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "config": "<string>",
  "status": "waiting",
  "host": "<string>",
  "maxPlayers": 123,
  "currentPlayers": 123,
  "region": "<string>",
  "isPrivate": true,
  "allowLateJoin": true,
  "settings": {},
  "players": [
    {
      "id": "<string>",
      "state": {},
      "isHost": true
    }
  ],
  "server": {
    "instanceId": "<string>",
    "status": "<string>",
    "region": "<string>",
    "ports": [
      {
        "name": "<string>",
        "host": "<string>",
        "port": 123,
        "protocol": "udp"
      }
    ]
  },
  "matchmaking": {
    "mode": "<string>",
    "startedAt": "<string>",
    "queueStats": {
      "playersSearching": 123,
      "lobbiesInQueue": 123,
      "avgWaitSeconds": 123
    }
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

​
api-key
string
header
required

Headers

​
x-player-id
string
required

Unique player identifier. This becomes the lobby host.

Path Parameters

​
config
string
required

Lobby configuration name or ID from project settings (e.g. "casual", "ranked_2v2").

Body

application/json

Create a new lobby. The caller (x-player-id) becomes the host.

​
name
string
required

Display name for the lobby. Shown to other players when browsing.

Required string length: 1 - 100
​
region
string
default:us-east

Preferred region for the game server. Available: us-east, us-west, eu-west, eu-north, ap-south, etc.

​
maxPlayers
integer
default:2

Maximum number of players (1–100). Defaults to 2.

Required range: 1 <= x <= 100
​
isPrivate
boolean
default:false

If true, the lobby is hidden from browse and an invite code is generated.

​
allowLateJoin
boolean
default:true

If true, players can join after the game has started.

​
settings
object

Custom game settings (map, mode, difficulty, etc.). Passed to the game server as custom_data.

​
state
object

Initial player state for the host (ready status, team, loadout, etc.).

Response

Lobby created. The caller is the host. Share the id or code for others to join.

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
required

Game server info (null when no game running).

​
matchmaking
object
required

Matchmaking info (null when not searching).

​
createdAt
string
required

ISO 8601 creation timestamp.

​
updatedAt
string
required

ISO 8601 last update timestamp.