Update a lobby resource (REST-compliant unified endpoint)

PUT

lobbies

{id}

curl --request PUT \
  --url https://backend.computeflow.cloud/lobbies/{id} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "requesterId": "player123",
  "host": "newHostPlayerId",
  "status": "in_game",
  "settings": {
    "name": "Pro CTF Tournament",
    "maxPlayers": 8,
    "isPrivate": true,
    "useInviteCode": true,
    "allowLateJoin": true,
    "region": "us-west",
    "settings": {
      "gameMode": "capture-the-flag",
      "mapName": "castle",
      "scoreLimit": 10
    }
  },
  "playerState": {
    "position": {
      "x": 100,
      "y": 50
    },
    "health": 80,
    "score": 120
  }
}'

{
  "id": "e495d158-5d18-45e4-81b2-384790a8b830",
  "name": "Pro Players Only",
  "host": "player123",
  "maxPlayers": 8,
  "currentPlayers": 3,
  "region": "us-west",
  "status": "waiting",
  "isPrivate": false,
  "useInviteCode": false,
  "inviteCode": "abc123",
  "allowLateJoin": true,
  "settings": {
    "gameMode": "capture-the-flag",
    "timeLimit": 300,
    "teamSize": 4,
    "mapRotation": [
      "map1",
      "map2"
    ]
  },
  "players": [
    "player123",
    "player456",
    "player789"
  ],
  "lobbyStateRealTime": {
    "player123": {
      "position": {
        "x": 100,
        "y": 20
      },
      "health": 80
    },
    "player456": {
      "position": {
        "x": 200,
        "y": 30
      },
      "health": 95
    }
  },
  "gameServer": {
    "instance_id": "srv-a1b2c3d4",
    "name": "lobby-1698754321",
    "network_ports": [
      {
        "name": "game",
        "internal_port": 7777,
        "external_port": 30000,
        "protocol": "udp",
        "host": "203.0.113.42",
        "tls_enabled": false
      },
      {
        "name": "web",
        "internal_port": 8080,
        "external_port": 30001,
        "protocol": "tcp",
        "host": "203.0.113.42",
        "tls_enabled": true
      }
    ],
    "status": "running",
    "startup_args": "--mode capture-the-flag --map castle",
    "service_type": "match_based",
    "compute_size": "small",
    "region": "us-west",
    "version_tag": "v1.0.2",
    "started_at": "2023-10-31T15:30:00Z",
    "stopped_at": null,
    "custom_data": {
      "gameMode": "capture-the-flag",
      "mapName": "castle",
      "teamSize": 4,
      "scoreLimit": 10
    },
    "ttl": 3600
  },
  "timeout": 300,
  "createdAt": "2023-08-15T14:30:00.000Z",
  "updatedAt": "2023-08-15T15:45:00.000Z"
}

Authorizations

api-key

string

header

required

Headers

api-key

string

required

API key for authentication

client-auth-token

string

Optional client authentication token for player validation

Path Parameters

string

required

Lobby ID

Query Parameters

name

string

required

Name of the lobby configuration this lobby belongs to

Body

application/json

requesterId

string

required

ID of the player making the request (must be authorized for the operation)

Example:

"player123"

host

string

Update the host of the lobby (requesterId must be current host)

Example:

"newHostPlayerId"

status

enum<string>

Update lobby status (requesterId must be host)

Available options:

waiting,

in_game

Example:

"in_game"

settings

object

Update lobby settings (requesterId must be host)

playerState

object

Update player state for the requester

Example:

{
  "position": { "x": 100, "y": 50 },
  "health": 80,
  "score": 120
}

Response

200

application/json

Lobby updated successfully

string

required

Unique identifier for the lobby

Example:

"e495d158-5d18-45e4-81b2-384790a8b830"

name

string

required

Name of the lobby displayed to players

Maximum length: 255

Example:

"Pro Players Only"

host

string

required

ID of the player who is the current host

Maximum length: 255

Example:

"player123"

maxPlayers

number

default:8

required

Maximum number of players allowed in the lobby

Required range: 1 <= x <= 100

Example:

8

currentPlayers

number

default:0

required

Current number of players in the lobby

Example:

3

region

string

default:us-west

required

Geographic region for the lobby server

Example:

"us-west"

status

enum<string>

default:waiting

required

Current status of the lobby

Available options:

waiting,

in_game,

finished

Example:

"waiting"

isPrivate

boolean

default:false

required

Whether the lobby is private (requires invite code to join)

Example:

false

useInviteCode

boolean

default:false

required

Whether to generate an invite code for this lobby (always true for private lobbies)

Example:

false

inviteCode

string | null

required

Invite code for private lobbies or public lobbies with useInviteCode=true

Maximum length: 10

Example:

"abc123"

allowLateJoin

boolean

default:true

required

Whether players can join after the game has started

Example:

true

settings

object | null

required

Custom game settings for this lobby

Example:

{
  "gameMode": "capture-the-flag",
  "timeLimit": 300,
  "teamSize": 4,
  "mapRotation": ["map1", "map2"]
}

players

string[] | null

required

Array of player IDs currently in the lobby

Example:

["player123", "player456", "player789"]

lobbyStateRealTime

object | null

required

Real-time state information for each player, indexed by player ID

Example:

{
  "player123": {
    "position": { "x": 100, "y": 20 },
    "health": 80
  },
  "player456": {
    "position": { "x": 200, "y": 30 },
    "health": 95
  }
}

gameServer

object | null

required

Game server information returned from PlayFlow API when a game is running. Contains all connection details, server state, and metadata.

Example:

{
  "instance_id": "srv-a1b2c3d4",
  "name": "lobby-1698754321",
  "network_ports": [
    {
      "name": "game",
      "internal_port": 7777,
      "external_port": 30000,
      "protocol": "udp",
      "host": "203.0.113.42",
      "tls_enabled": false
    },
    {
      "name": "web",
      "internal_port": 8080,
      "external_port": 30001,
      "protocol": "tcp",
      "host": "203.0.113.42",
      "tls_enabled": true
    }
  ],
  "status": "running",
  "startup_args": "--mode capture-the-flag --map castle",
  "service_type": "match_based",
  "compute_size": "small",
  "region": "us-west",
  "version_tag": "v1.0.2",
  "started_at": "2023-10-31T15:30:00Z",
  "stopped_at": null,
  "custom_data": {
    "gameMode": "capture-the-flag",
    "mapName": "castle",
    "teamSize": 4,
    "scoreLimit": 10
  },
  "ttl": 3600
}

timeout

number

default:300

required

Time in seconds before the lobby auto-closes due to inactivity

Required range: 60 <= x <= 3600

Example:

300

createdAt

string

required

Timestamp when this lobby was created

Example:

"2023-08-15T14:30:00.000Z"

updatedAt

string

required

Timestamp when this lobby was last updated

Example:

"2023-08-15T15:45:00.000Z"

Delete a lobby (host or admin only), scoped to a lobby configuration

curl --request PUT \
  --url https://backend.computeflow.cloud/lobbies/{id} \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "requesterId": "player123",
  "host": "newHostPlayerId",
  "status": "in_game",
  "settings": {
    "name": "Pro CTF Tournament",
    "maxPlayers": 8,
    "isPrivate": true,
    "useInviteCode": true,
    "allowLateJoin": true,
    "region": "us-west",
    "settings": {
      "gameMode": "capture-the-flag",
      "mapName": "castle",
      "scoreLimit": 10
    }
  },
  "playerState": {
    "position": {
      "x": 100,
      "y": 50
    },
    "health": 80,
    "score": 120
  }
}'

{
  "id": "e495d158-5d18-45e4-81b2-384790a8b830",
  "name": "Pro Players Only",
  "host": "player123",
  "maxPlayers": 8,
  "currentPlayers": 3,
  "region": "us-west",
  "status": "waiting",
  "isPrivate": false,
  "useInviteCode": false,
  "inviteCode": "abc123",
  "allowLateJoin": true,
  "settings": {
    "gameMode": "capture-the-flag",
    "timeLimit": 300,
    "teamSize": 4,
    "mapRotation": [
      "map1",
      "map2"
    ]
  },
  "players": [
    "player123",
    "player456",
    "player789"
  ],
  "lobbyStateRealTime": {
    "player123": {
      "position": {
        "x": 100,
        "y": 20
      },
      "health": 80
    },
    "player456": {
      "position": {
        "x": 200,
        "y": 30
      },
      "health": 95
    }
  },
  "gameServer": {
    "instance_id": "srv-a1b2c3d4",
    "name": "lobby-1698754321",
    "network_ports": [
      {
        "name": "game",
        "internal_port": 7777,
        "external_port": 30000,
        "protocol": "udp",
        "host": "203.0.113.42",
        "tls_enabled": false
      },
      {
        "name": "web",
        "internal_port": 8080,
        "external_port": 30001,
        "protocol": "tcp",
        "host": "203.0.113.42",
        "tls_enabled": true
      }
    ],
    "status": "running",
    "startup_args": "--mode capture-the-flag --map castle",
    "service_type": "match_based",
    "compute_size": "small",
    "region": "us-west",
    "version_tag": "v1.0.2",
    "started_at": "2023-10-31T15:30:00Z",
    "stopped_at": null,
    "custom_data": {
      "gameMode": "capture-the-flag",
      "mapName": "castle",
      "teamSize": 4,
      "scoreLimit": 10
    },
    "ttl": 3600
  },
  "timeout": 300,
  "createdAt": "2023-08-15T14:30:00.000Z",
  "updatedAt": "2023-08-15T15:45:00.000Z"
}

Servers

Lobbies & Matchmaking

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response