curl --request POST \
  --url https://api.simpl.gg/v1/lobbies/{lobby_id}/start \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'x-player-id: <x-player-id>' \
  --data '
{
  "region": "lhr"
}
'

{
  "lobby_id": "lobby_456",
  "queue_id": "ranked_2v2",
  "status": "waiting",
  "host_player_id": "player_1",
  "is_private": true,
  "max_players": 4,
  "current_players": 2,
  "players": [
    {
      "player_id": "player_1",
      "is_host": true,
      "joined_at": "2026-09-21T14:00:00Z",
      "state": {
        "mmr": 1500,
        "team": "team_1",
        "regions": [
          "iad",
          "dfw"
        ]
      }
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "Austin's lobby",
  "region": "iad",
  "invite_code": "SIMPL-K7Q2F1",
  "settings": {
    "map": "forest",
    "mode": "ctf",
    "difficulty": "hard"
  },
  "server": {
    "instance_id": "abc123",
    "region": "iad",
    "status": "launching",
    "match_id": "xyz789",
    "network_ports": [
      {
        "name": "game",
        "protocol": "udp",
        "internal_port": 7777,
        "external_port": 30412,
        "host": "37.16.24.10",
        "tls_enabled": false
      }
    ]
  },
  "match_id": "xyz789"
}

Lobbies

Start the match directly

Host only. Skips matchmaking entirely and launches a server for this lobby alone: the private-match path. The lobby moves waiting → starting, then in_game once the server reports ready, or back to waiting with SERVER_CREATE_FAILED (5002) if the machine could not be created. Subscribers receive server_ready with connection details.

Either key can start a lobby, but only a server key can choose its tier or startup_args: a client key that sends either gets 403 INSUFFICIENT_PERMISSIONS, and the lobby is left as it was. See LobbyStartRequest.

POST

lobbies

{lobby_id}

start

curl --request POST \
  --url https://api.simpl.gg/v1/lobbies/{lobby_id}/start \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'x-player-id: <x-player-id>' \
  --data '
{
  "region": "lhr"
}
'

{
  "lobby_id": "lobby_456",
  "queue_id": "ranked_2v2",
  "status": "waiting",
  "host_player_id": "player_1",
  "is_private": true,
  "max_players": 4,
  "current_players": 2,
  "players": [
    {
      "player_id": "player_1",
      "is_host": true,
      "joined_at": "2026-09-21T14:00:00Z",
      "state": {
        "mmr": 1500,
        "team": "team_1",
        "regions": [
          "iad",
          "dfw"
        ]
      }
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "Austin's lobby",
  "region": "iad",
  "invite_code": "SIMPL-K7Q2F1",
  "settings": {
    "map": "forest",
    "mode": "ctf",
    "difficulty": "hard"
  },
  "server": {
    "instance_id": "abc123",
    "region": "iad",
    "status": "launching",
    "match_id": "xyz789",
    "network_ports": [
      {
        "name": "game",
        "protocol": "udp",
        "internal_port": 7777,
        "external_port": 30412,
        "host": "37.16.24.10",
        "tls_enabled": false
      }
    ]
  },
  "match_id": "xyz789"
}

Authorizations

api-key

string

header

required

Per-project client key, prefixed ck_live_. Player-facing endpoints only, and browse never returns private lobbies. Safe to ship in a game binary: a leak exposes one project's player surface, nothing else.

Headers

x-player-id

string

required

Identifies the acting player. Trusted verbatim: Simpl performs no authentication or token verification on this value. Bring your own identity system and pass whatever stable id it produces.

Required string length: 1 - 128

Example:

"player_1"

Path Parameters

lobby_id

string

required

Lobby identifier.

Example:

"lobby_456"

Body

application/json

Host only. Settings for the server created for this match. Anything omitted falls back to the queue's server_settings.

A client key ships inside the game, so anyone holding the game holds it. It may choose region and version_tag, but not what the account is billed for or what runs: tier and startup_args need a server key, and a client key that sends either gets 403 INSUFFICIENT_PERMISSIONS.

A lobby with no queue has no server_settings to fall back on: region is required, and with a server key so is tier. A client-key start of such a lobby runs on 1x-1g.

region

enum<string>

Any key. Overrides the queue's region. Limited to the plan's regions.

Available options:

ams,

arn,

cdg,

dfw,

ewr,

fra,

iad,

lax,

lhr,

nrt,

ord,

sin,

sjc,

syd,

yyz

Example:

"iad"

version_tag

string

Any key. Build name to run, for a lobby with no queue. A lobby with a queue runs the queue's version_tag.

tier

enum<string>

Server key only; a client key gets 403 INSUFFICIENT_PERMISSIONS. Required for a lobby with no queue. A lobby with a queue runs the queue's tier.

Available options:

1x-512,

1x-1g,

1x-2g,

2x-2g,

4x-4g,

1p-2g,

1p-4g,

2p-4g,

2p-8g

Example:

"2x-2g"

startup_args

string[]

Server key only; a client key gets 403 INSUFFICIENT_PERMISSIONS. Replaces the queue's server_settings.startup_args for this server.

Maximum array length: 64

Maximum string length: 1024

Example:

["-port={{PORT}}"]

version

integer

Not applied yet.

custom_data

object

Not applied yet.

Example:

{ "map": "forest", "mode": "ctf" }

Response

The lobby, now starting.

lobby_id

string

required

Example:

"lobby_456"

queue_id

string

required

Example:

"ranked_2v2"

status

enum<string>

required

Lobby lifecycle:

waiting → in_queue → matched → in_game → waiting (rematch-ready)
        ↓
        → waiting (timeout/cancel/no opponents)
waiting → starting → in_game (host started directly)
                   → waiting (server create failed)

Available options:

waiting,

in_queue,

matched,

starting,

in_game

host_player_id

string

required

Example:

"player_1"

is_private

boolean

required

Private lobbies never appear in GET /v1/lobbies for client keys, and are joinable by invite code only.

max_players

integer

required

Required range: 1 <= x <= 100

Example:

4

current_players

integer

required

Required range: x >= 0

Example:

2

players

object[]

required

Show child attributes

created_at

string<date-time>

required

updated_at

string<date-time>

required

name

string

Example:

"Austin's lobby"

region

enum<string>

Datacenter region a server runs in. 15 regions are supported.

code	location
`ams`	Amsterdam, Netherlands
`arn`	Stockholm, Sweden
`cdg`	Paris, France
`dfw`	Dallas, Texas (US)
`ewr`	Secaucus, NJ (US)
`fra`	Frankfurt, Germany
`iad`	Ashburn, Virginia (US)
`lax`	Los Angeles, California (US)
`lhr`	London, United Kingdom
`nrt`	Tokyo, Japan
`ord`	Chicago, Illinois (US)
`sin`	Singapore, Singapore
`sjc`	San Jose, California (US)
`syd`	Sydney, Australia
`yyz`	Toronto, Canada

Every region is available to every project. Capacity is Simpl's problem, not yours: pick the region closest to your players.

Available options:

ams,

arn,

cdg,

dfw,

ewr,

fra,

iad,

lax,

lhr,

nrt,

ord,

sin,

sjc,

syd,

yyz

Example:

"iad"

invite_code

string | null

Generated per the queue's invite_code_config. Null when the queue has invite codes disabled.

Example:

"SIMPL-K7Q2F1"

settings

object

Free-form, game-specific lobby settings: map, mode, difficulty, whatever the game needs. Host-writable via PATCH /v1/lobbies/{lobby_id}/settings.

Example:

{
  "map": "forest",
  "mode": "ctf",
  "difficulty": "hard"
}

server

object | null

Connection details for the game server backing this lobby. Present once the server is running. Connection-relevant fields only: players never see the server's configuration (startup arguments, custom data, tier) or anything about its build. Call GET /v1/servers/{instance_id} with a server key for the full object.

Show child attributes

match_id

string | null

Example:

"xyz789"

API Reference

Auth

Projects

Servers

Builds

Queues

Lobbies

Events

Start the match directly

Authorizations

Headers

Path Parameters

Body

Response