> ## Documentation Index > Fetch the complete documentation index at: https://docs.playflowcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Update project settings > Updates project-level configuration. All fields are optional — only include what you want to change. Omitted fields remain unchanged. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.** **port_configs:** Network ports allocated for every server (max 10). Define game ports, query ports, etc. **auth_config:** Player authentication provider (none, custom_jwt, playfab, steam). **environment_variables:** Default env vars injected into every game server. **pool_config:** Pre-provisioned server pool sizes per region and compute size. **lobby_configs:** Lobby types with matchmaking rules, team structures, and invite codes (max 20). ## OpenAPI ````yaml https://api.computeflow.cloud/api/doc post /api/v3/projects/settings openapi: 3.1.0 info: title: PlayFlow API version: 3.0.0 description: > PlayFlow is a game server hosting and orchestration platform. Deploy, manage, and scale multiplayer game servers globally with built-in matchmaking, lobby management, and billing. ## Authentication All API endpoints (except Health) require the `api-key` header: ``` api-key: pf_your_project_api_key ``` Find your API key in the PlayFlow dashboard under **Project Settings**. Each project has two keys, both sent in the `api-key` header: - **Server key** (`pf_...`) — full access. Keep it secret (server-side only). - **Client key** (`pfclient_...`) — safe to embed in shipped game clients. It has access to all player-facing lobby, matchmaking, and read endpoints, but is **rejected with `403`** from admin/privileged routes: admin lobby get/force-delete (`GET`/`DELETE /v3/lobbies/{config}/{id}`), build deletion (`DELETE /v3/builds/{id}`), and project settings (`POST /v3/projects/settings`). Server lifecycle mutations (start/stop/restart/update) are allowed for client keys by default but can be locked to server-key-only per project via the `client_key_server_control` setting. ## Quick Start 1. **Upload a build**: `POST /v3/builds/upload-url` → get presigned URL → `PUT` your ZIP → processing starts automatically 2. **Start a server**: `POST /v3/servers/start` → get connection info in `network_ports` 3. **Connect your game client**: Use `host:external_port` from the response ## Key Concepts - **Builds**: Your game server binary packaged as a ZIP or Docker image. Versioned per name per project. - **Servers**: Running game server instances. Each gets dedicated compute and network ports with automatic health monitoring. - **Pool Servers**: Pre-provisioned servers for instant startup (~5s vs ~30s cold start). - **Regions**: 13 global regions (us-east, us-south, us-west, eu-north, eu-west, eu-uk, ap-south, sea, ap-north, ap-southeast, south-africa, south-america-brazil, south-america-chile). - **Compute Sizes**: From micro (512MB) to dedicated-xlarge (16GB dedicated CPU). ## Server Lifecycle `launching` → `running` (game ports open) → `stopped` (game exits, TTL expires, or manual stop) ## Build Lifecycle `uploading` → `processing` (build pipeline creates deployable image) → `ready` | `failed` ## Rate Limits - General reads: 100 req/sec per API key - Write operations (start server, upload build): 10 req/sec per API key - Player-facing lobby writes (join, matchmaking, start): 10 req/sec **per player** (keyed by `x-player-id`), so a game's whole player base doesn't share one bucket - Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining` ## Plan Limits - **Free**: 1 server max, forced 1hr TTL, small size only - **Pro**: Unlimited servers, all sizes, custom TTL, pool servers ## Error Format All errors return: `{ "error": "message", "detail": "context", "status": 404 }` servers: - url: https://api.computeflow.cloud security: - ApiKeyAuth: [] tags: - name: Servers description: >- Create, manage, and monitor game server instances. Each server gets dedicated compute, network ports, and automatic health monitoring with TTL enforcement. Servers start in `launching` status and transition to `running` when the game opens its ports. - name: Builds description: >- Upload and manage game server builds. Supports ZIP uploads (automatically processed into deployable images) and direct Docker image references. Builds are versioned per name per project — uploading a new build with the same name auto-increments the version. Servers always use the latest `ready` build unless a specific version is pinned. - name: Projects description: >- Configure project-level settings including network ports, player authentication, environment variables, server pooling, and lobby/matchmaking rules. Settings apply as defaults to all servers in the project and can be overridden per-server at start time. - name: Lobbies description: >- Player-centric lobby and matchmaking system. Every request identifies the player via the `x-player-id` header. Use `/me` endpoints to interact with your current lobby — the API resolves which lobby you're in automatically. **Quick start:** `POST /v3/lobbies/default` creates a lobby with sensible defaults (no dashboard config needed). Share the invite `code` with friends, or use `POST /v3/lobbies/default/me/matchmaking` to find opponents automatically. **Matchmaking** supports symmetric teams (2v2, 5v5), asymmetric roles (1 monster vs 5 hunters), FFA, battle royale duos, and skill-based matching with auto-expanding MMR buckets. paths: /api/v3/projects/settings: post: tags: - Projects summary: Update project settings description: >- Updates project-level configuration. All fields are optional — only include what you want to change. Omitted fields remain unchanged. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.** **port_configs:** Network ports allocated for every server (max 10). Define game ports, query ports, etc. **auth_config:** Player authentication provider (none, custom_jwt, playfab, steam). **environment_variables:** Default env vars injected into every game server. **pool_config:** Pre-provisioned server pool sizes per region and compute size. **lobby_configs:** Lobby types with matchmaking rules, team structures, and invite codes (max 20). operationId: updateProjectSettings requestBody: required: true content: application/json: schema: type: object properties: port_configs: type: array items: type: object properties: id: type: string description: >- Auto-generated unique identifier for this port config entry. Omit when creating new configs. name: type: string minLength: 1 maxLength: 30 description: >- Human-readable name for this port (1–30 chars). Example: "game_udp", "query_tcp", "voice". internal_port: type: integer minimum: 1 maximum: 65535 description: >- Port number your game server listens on inside the container (1–65535). Must be unique per protocol within the project. protocol: type: string enum: - udp - tcp description: >- Network protocol. "udp" for real-time game traffic, "tcp" for reliable connections and WebSocket. tls_enabled: type: boolean description: >- Enable automatic TLS termination. Only valid for TCP ports. When enabled, clients connect via TLS and PlayFlow handles certificate management. required: - name - internal_port - protocol - tls_enabled description: >- Defines a network port that PlayFlow allocates for every server in this project. maxItems: 10 description: >- Network port configuration for all servers in this project (max 10 ports). Defines which ports PlayFlow allocates for each server. auth_config: oneOf: - type: object properties: provider: type: string enum: - none description: >- No player authentication. Any token (or no token) is accepted. Use only for development or trusted environments. required: - provider description: >- Disable player authentication verification. Not recommended for production. - type: object properties: provider: type: string enum: - custom_jwt description: >- Verify player tokens as JWTs using a JWKS endpoint. Works with Auth0, Firebase Auth, Supabase Auth, Clerk, and any OIDC-compliant provider. jwks_url: type: string format: uri description: >- JWKS endpoint URL for verifying JWT signatures. Example: "https://your-domain.auth0.com/.well-known/jwks.json". issuer: type: string description: >- Expected JWT issuer (iss claim). Tokens with a different issuer are rejected. Example: "https://your-domain.auth0.com/". audience: type: string description: >- Expected JWT audience (aud claim). Example: "your-api-identifier". required: - provider - jwks_url description: >- Verify player tokens as JWTs using a JWKS endpoint. Compatible with Auth0, Firebase, Supabase Auth, Clerk, and any OIDC-compliant provider. - type: object properties: provider: type: string enum: - playfab description: Verify player tokens using PlayFab entity tokens. title_id: type: string minLength: 1 description: >- Your PlayFab Title ID. Found in the PlayFab dashboard under Settings > API Keys. required: - provider - title_id description: >- Verify player tokens using PlayFab's entity token system. - type: object properties: provider: type: string enum: - steam description: >- Verify player tokens using Steam session tickets via the Steamworks Web API. app_id: type: string minLength: 1 description: >- Your Steam App ID. Found in the Steamworks dashboard. web_api_key: type: string minLength: 1 description: >- Your Steamworks Web API key for server-side ticket verification. required: - provider - app_id - web_api_key description: >- Verify player tokens using Steam session tickets via the Steamworks Web API. description: >- Player authentication provider configuration. Determines how player tokens are verified. environment_variables: type: object additionalProperties: type: string description: >- Default environment variables injected into every game server. Can be overridden per-server at start time. pool_config: type: object properties: enabled: type: boolean description: >- Whether server pooling is active. When enabled, PlayFlow maintains pre-provisioned stopped machines that can be claimed instantly (~5s vs ~30s cold start). regions: type: object additionalProperties: type: object additionalProperties: type: integer minimum: 0 maximum: 10 description: >- Pool size configuration per region and compute size. Structure: { "region": { "compute_size": count } }. Example: { "us-east": { "small": 3, "medium": 1 }, "eu-west": { "small": 2 } }. Max 10 machines per region/size combination. build_name: type: string description: >- Build name to pre-warm pool machines with. When set, pool-sweep provisions machines using the latest ready version of this build. When omitted, uses the latest ready build regardless of name. build_version: type: integer minimum: 1 description: >- Specific build version to pin pool machines to. Only used when build_name is also set. When omitted, the latest version of the named build is used. required: - enabled - regions description: >- Server pool configuration for reducing cold-start latency. Set to { enabled: false, regions: {} } to disable pooling. lobby_configs: type: array items: type: object properties: id: type: string minLength: 1 description: >- Unique identifier for this lobby configuration (e.g., "ranked-2v2", "casual-ffa"). name: type: string minLength: 1 maxLength: 255 description: >- Human-readable lobby name displayed to players (e.g., "Ranked 2v2", "Casual Free-for-All"). enabled: type: boolean description: Whether this lobby is active and accepting players. timeout: type: integer minimum: 1 description: >- Lobby timeout in seconds. Lobbies are cleaned up after this duration of inactivity. heartbeat: type: boolean description: >- Whether lobbies require periodic heartbeat signals to stay alive. heartbeatTimeout: type: integer description: >- Seconds of missed heartbeats before a lobby is considered dead. hostLeaveBehavior: type: string enum: - promote - delete default: promote description: >- What happens when the host leaves a lobby. `promote` (default) transfers host duty to the next player; `delete` destroys the lobby and evicts all remaining players. Use `delete` for one-shot private rooms where the host's session IS the room. customProperties: type: object additionalProperties: {} default: {} description: >- Arbitrary properties attached to lobbies of this type. Accessible by game clients for filtering. inviteCodeConfig: type: object properties: type: type: string enum: - numeric - alphanumeric - alphabetic description: Character set for generated invite codes. length: type: integer minimum: 1 maximum: 16 description: >- Length of generated invite codes (1–16 characters). prefix: type: string description: >- Optional prefix prepended to all invite codes (e.g., "PF-" produces codes like "PF-A3B7"). required: - type - length description: >- Configuration for auto-generated invite codes. Omit to disable invite codes for this lobby type. serverSettings: type: object properties: gameBuild: type: string description: >- Build name to use for servers created by this lobby/mode (e.g., "default", "ranked"). gameBuildVersion: type: integer description: >- Specific build version number. Pin to an exact version for consistency. serverSize: type: string description: >- Compute size for servers created by this lobby (e.g., "small", "medium", "large"). maxGameTime: type: integer description: >- Maximum game duration in seconds. Server auto-stops after this time. default: {} description: >- Default server configuration for servers created by this lobby type. matchmaking: type: object properties: modes: type: object additionalProperties: type: object properties: teams: type: integer minimum: 1 description: >- Number of teams in a match (e.g., 2 for team deathmatch, 1 for FFA). playersPerTeam: type: integer minimum: 1 description: Maximum players per team. minPlayersPerTeam: type: integer minimum: 1 description: >- Minimum players per team required to start the match. minTeams: type: integer minimum: 1 description: >- Minimum number of teams required to start. Defaults to the value of teams. teamComposition: type: object additionalProperties: type: object additionalProperties: type: number description: >- Custom team composition. Structure: { teamName: { roleName: count } }. Omit or leave empty for standard teams × playersPerTeam matches. Supports asymmetric teams (e.g. { monsters: { boss: 1 }, hunters: { medic: 1, assault: 2 } }). excludedFromQueue: type: array items: type: string description: >- List of player attribute field names that exclude players from this queue (e.g., ["banned", "cooldown"]). allowBackfill: type: boolean description: >- DEPRECATED alias for `backfill: { enabled: true }`. When true, newly-queued players are routed into an already-running match with open slots instead of always launching a new server. Prefer the structured `backfill` object; this flag is kept for backwards compatibility and maps to `{ enabled: true }`. backfill: type: object properties: enabled: type: boolean description: >- Master switch. When true, newly-queued lobbies can join an already-running match with open slots (real backfill) before a fresh server is launched. windowSeconds: type: integer minimum: 1 description: >- How long after match formation the match stays open to joiners. Omit for the engine default. closeWhenFull: type: boolean description: >- Close backfill automatically once the match reaches capacity. Defaults to true. skill: type: object properties: field: type: string description: >- Player-state field to gate joiners on (e.g., "mmr"). maxDifference: type: number description: >- A joining lobby's average value on `field` must be within this distance of the running match's band to be admitted. required: - field - maxDifference description: >- Optional skill gate for backfill joiners. required: - enabled description: >- Backfill configuration. Omit or set enabled:false to disable — non-backfill modes behave exactly as before. Takes precedence over the deprecated `allowBackfill` flag. timeout: type: integer minimum: 1 description: >- Matchmaking timeout in seconds. Players are removed from the queue if not matched within this time. maxPartySize: type: integer minimum: 1 description: >- Maximum number of players that can queue together as a party. rules: type: array items: oneOf: - type: object properties: type: type: string enum: - difference field: type: string minLength: 1 description: >- Numeric player attribute field to compare (e.g., "mmr", "level"). maxDifference: type: number minimum: 0 description: >- Max |A.field - B.field|. Auto-expands with wait time. required: - type - field - maxDifference description: >- Match only if both lobbies' averaged numeric field values are within tolerance. - type: object properties: type: type: string enum: - equals field: type: string minLength: 1 description: >- Field whose value must match on both sides (e.g., "gameVersion"). required: - type - field description: >- Match only if both lobbies have the same value for a field (strings/bools; unanimous across party). - type: object properties: type: type: string enum: - not_equals field: type: string minLength: 1 description: >- Field whose values must differ (e.g., "lastOpponent" — anti-rematch). required: - type - field description: >- Match only if both lobbies differ on a field value. - type: object properties: type: type: string enum: - region minOverlap: type: integer minimum: 1 description: Minimum shared regions. Default 1. required: - type description: >- Match only if acceptable regions overlap by at least `minOverlap` entries. - type: object properties: type: type: string enum: - expression cel: type: string minLength: 1 description: >- CEL expression. Tickets `a` and `b` plus `ctx` are in scope. e.g., `a.state.mmr > 1000 && b.state.mmr > 1000`. required: - type - cel description: >- CEL expression escape hatch for custom match logic. description: >- One of five rule primitives (difference, equals, not_equals, region, expression). See docs. description: >- Declarative match rules. All must pass for two lobbies to match. See docs for full primitive grammar. useVersionFromState: type: string description: >- When set, the server's build name (`version_tag`) is taken from this field in the matched players' state. Lets you run multiple game versions simultaneously with no rolling updates. REQUIRED: an `equals` rule on the same field, so matched players always share the version. matchConfirmation: type: object properties: enabled: type: boolean description: >- When true, matches enter `match_found` and await player acceptance. timeoutSeconds: type: integer minimum: 1 description: >- Seconds players have to confirm before the match cancels. requireAllPlayers: type: boolean description: >- When true (default), every participating lobby must confirm. When false, partial confirmations can proceed. required: - enabled - timeoutSeconds description: >- Optional 'Accept Match' flow. Matches pause at `match_found` for player confirmation before launching. serverOverrides: type: object properties: gameBuild: type: string description: >- Build name to use for servers created by this lobby/mode (e.g., "default", "ranked"). gameBuildVersion: type: integer description: >- Specific build version number. Pin to an exact version for consistency. serverSize: type: string description: >- Compute size for servers created by this lobby (e.g., "small", "medium", "large"). maxGameTime: type: integer description: >- Maximum game duration in seconds. Server auto-stops after this time. description: >- Override the lobby's default server settings for this specific mode. required: - teams - playersPerTeam - minPlayersPerTeam - timeout - maxPartySize description: >- Configuration for a matchmaking mode within a lobby. Defines team structure, player limits, and matching rules. description: >- Named matchmaking modes. Keys are mode identifiers (e.g., "ranked", "casual"). Values define team structure and rules. required: - modes description: >- Matchmaking configuration. Omit to create a lobby without automated matchmaking. required: - id - name - enabled - timeout description: >- Configuration for a lobby type. Defines player limits, matchmaking rules, and server settings. maxItems: 20 description: >- Lobby and matchmaking configuration. Defines lobby types, team structures, and matching rules (max 20). description: >- Project settings to update. All fields are optional — only include what you want to change. Omitted fields remain unchanged. responses: '200': description: >- Updated project settings (returns all fields, including unchanged ones). content: application/json: schema: type: object properties: port_configs: type: array items: type: object properties: id: type: string description: >- Auto-generated unique identifier for this port config entry. Omit when creating new configs. name: type: string minLength: 1 maxLength: 30 description: >- Human-readable name for this port (1–30 chars). Example: "game_udp", "query_tcp", "voice". internal_port: type: integer minimum: 1 maximum: 65535 description: >- Port number your game server listens on inside the container (1–65535). Must be unique per protocol within the project. protocol: type: string enum: - udp - tcp description: >- Network protocol. "udp" for real-time game traffic, "tcp" for reliable connections and WebSocket. tls_enabled: type: boolean description: >- Enable automatic TLS termination. Only valid for TCP ports. When enabled, clients connect via TLS and PlayFlow handles certificate management. required: - name - internal_port - protocol - tls_enabled description: >- Defines a network port that PlayFlow allocates for every server in this project. description: Current network port configuration for the project. auth_config: oneOf: - type: object properties: provider: type: string enum: - none description: >- No player authentication. Any token (or no token) is accepted. Use only for development or trusted environments. required: - provider description: >- Disable player authentication verification. Not recommended for production. - type: object properties: provider: type: string enum: - custom_jwt description: >- Verify player tokens as JWTs using a JWKS endpoint. Works with Auth0, Firebase Auth, Supabase Auth, Clerk, and any OIDC-compliant provider. jwks_url: type: string format: uri description: >- JWKS endpoint URL for verifying JWT signatures. Example: "https://your-domain.auth0.com/.well-known/jwks.json". issuer: type: string description: >- Expected JWT issuer (iss claim). Tokens with a different issuer are rejected. Example: "https://your-domain.auth0.com/". audience: type: string description: >- Expected JWT audience (aud claim). Example: "your-api-identifier". required: - provider - jwks_url description: >- Verify player tokens as JWTs using a JWKS endpoint. Compatible with Auth0, Firebase, Supabase Auth, Clerk, and any OIDC-compliant provider. - type: object properties: provider: type: string enum: - playfab description: Verify player tokens using PlayFab entity tokens. title_id: type: string minLength: 1 description: >- Your PlayFab Title ID. Found in the PlayFab dashboard under Settings > API Keys. required: - provider - title_id description: >- Verify player tokens using PlayFab's entity token system. - type: object properties: provider: type: string enum: - steam description: >- Verify player tokens using Steam session tickets via the Steamworks Web API. app_id: type: string minLength: 1 description: >- Your Steam App ID. Found in the Steamworks dashboard. web_api_key: type: string minLength: 1 description: >- Your Steamworks Web API key for server-side ticket verification. required: - provider - app_id - web_api_key description: >- Verify player tokens using Steam session tickets via the Steamworks Web API. description: Current player authentication configuration. environment_variables: type: object additionalProperties: type: string description: Current default environment variables for all servers. pool_config: type: - object - 'null' properties: enabled: type: boolean description: >- Whether server pooling is active. When enabled, PlayFlow maintains pre-provisioned stopped machines that can be claimed instantly (~5s vs ~30s cold start). regions: type: object additionalProperties: type: object additionalProperties: type: integer minimum: 0 maximum: 10 description: >- Pool size configuration per region and compute size. Structure: { "region": { "compute_size": count } }. Example: { "us-east": { "small": 3, "medium": 1 }, "eu-west": { "small": 2 } }. Max 10 machines per region/size combination. build_name: type: string description: >- Build name to pre-warm pool machines with. When set, pool-sweep provisions machines using the latest ready version of this build. When omitted, uses the latest ready build regardless of name. build_version: type: integer minimum: 1 description: >- Specific build version to pin pool machines to. Only used when build_name is also set. When omitted, the latest version of the named build is used. required: - enabled - regions description: >- Current server pool configuration. Null if pooling has never been configured. lobby_configs: type: array items: type: object properties: id: type: string minLength: 1 description: >- Unique identifier for this lobby configuration (e.g., "ranked-2v2", "casual-ffa"). name: type: string minLength: 1 maxLength: 255 description: >- Human-readable lobby name displayed to players (e.g., "Ranked 2v2", "Casual Free-for-All"). enabled: type: boolean description: Whether this lobby is active and accepting players. timeout: type: integer minimum: 1 description: >- Lobby timeout in seconds. Lobbies are cleaned up after this duration of inactivity. heartbeat: type: boolean description: >- Whether lobbies require periodic heartbeat signals to stay alive. heartbeatTimeout: type: integer description: >- Seconds of missed heartbeats before a lobby is considered dead. hostLeaveBehavior: type: string enum: - promote - delete default: promote description: >- What happens when the host leaves a lobby. `promote` (default) transfers host duty to the next player; `delete` destroys the lobby and evicts all remaining players. Use `delete` for one-shot private rooms where the host's session IS the room. customProperties: type: object additionalProperties: {} default: {} description: >- Arbitrary properties attached to lobbies of this type. Accessible by game clients for filtering. inviteCodeConfig: type: object properties: type: type: string enum: - numeric - alphanumeric - alphabetic description: Character set for generated invite codes. length: type: integer minimum: 1 maximum: 16 description: >- Length of generated invite codes (1–16 characters). prefix: type: string description: >- Optional prefix prepended to all invite codes (e.g., "PF-" produces codes like "PF-A3B7"). required: - type - length description: >- Configuration for auto-generated invite codes. Omit to disable invite codes for this lobby type. serverSettings: type: object properties: gameBuild: type: string description: >- Build name to use for servers created by this lobby/mode (e.g., "default", "ranked"). gameBuildVersion: type: integer description: >- Specific build version number. Pin to an exact version for consistency. serverSize: type: string description: >- Compute size for servers created by this lobby (e.g., "small", "medium", "large"). maxGameTime: type: integer description: >- Maximum game duration in seconds. Server auto-stops after this time. default: {} description: >- Default server configuration for servers created by this lobby type. matchmaking: type: object properties: modes: type: object additionalProperties: type: object properties: teams: type: integer minimum: 1 description: >- Number of teams in a match (e.g., 2 for team deathmatch, 1 for FFA). playersPerTeam: type: integer minimum: 1 description: Maximum players per team. minPlayersPerTeam: type: integer minimum: 1 description: >- Minimum players per team required to start the match. minTeams: type: integer minimum: 1 description: >- Minimum number of teams required to start. Defaults to the value of teams. teamComposition: type: object additionalProperties: type: object additionalProperties: type: number description: >- Custom team composition. Structure: { teamName: { roleName: count } }. Omit or leave empty for standard teams × playersPerTeam matches. Supports asymmetric teams (e.g. { monsters: { boss: 1 }, hunters: { medic: 1, assault: 2 } }). excludedFromQueue: type: array items: type: string description: >- List of player attribute field names that exclude players from this queue (e.g., ["banned", "cooldown"]). allowBackfill: type: boolean description: >- DEPRECATED alias for `backfill: { enabled: true }`. When true, newly-queued players are routed into an already-running match with open slots instead of always launching a new server. Prefer the structured `backfill` object; this flag is kept for backwards compatibility and maps to `{ enabled: true }`. backfill: type: object properties: enabled: type: boolean description: >- Master switch. When true, newly-queued lobbies can join an already-running match with open slots (real backfill) before a fresh server is launched. windowSeconds: type: integer minimum: 1 description: >- How long after match formation the match stays open to joiners. Omit for the engine default. closeWhenFull: type: boolean description: >- Close backfill automatically once the match reaches capacity. Defaults to true. skill: type: object properties: field: type: string description: >- Player-state field to gate joiners on (e.g., "mmr"). maxDifference: type: number description: >- A joining lobby's average value on `field` must be within this distance of the running match's band to be admitted. required: - field - maxDifference description: >- Optional skill gate for backfill joiners. required: - enabled description: >- Backfill configuration. Omit or set enabled:false to disable — non-backfill modes behave exactly as before. Takes precedence over the deprecated `allowBackfill` flag. timeout: type: integer minimum: 1 description: >- Matchmaking timeout in seconds. Players are removed from the queue if not matched within this time. maxPartySize: type: integer minimum: 1 description: >- Maximum number of players that can queue together as a party. rules: type: array items: oneOf: - type: object properties: type: type: string enum: - difference field: type: string minLength: 1 description: >- Numeric player attribute field to compare (e.g., "mmr", "level"). maxDifference: type: number minimum: 0 description: >- Max |A.field - B.field|. Auto-expands with wait time. required: - type - field - maxDifference description: >- Match only if both lobbies' averaged numeric field values are within tolerance. - type: object properties: type: type: string enum: - equals field: type: string minLength: 1 description: >- Field whose value must match on both sides (e.g., "gameVersion"). required: - type - field description: >- Match only if both lobbies have the same value for a field (strings/bools; unanimous across party). - type: object properties: type: type: string enum: - not_equals field: type: string minLength: 1 description: >- Field whose values must differ (e.g., "lastOpponent" — anti-rematch). required: - type - field description: >- Match only if both lobbies differ on a field value. - type: object properties: type: type: string enum: - region minOverlap: type: integer minimum: 1 description: Minimum shared regions. Default 1. required: - type description: >- Match only if acceptable regions overlap by at least `minOverlap` entries. - type: object properties: type: type: string enum: - expression cel: type: string minLength: 1 description: >- CEL expression. Tickets `a` and `b` plus `ctx` are in scope. e.g., `a.state.mmr > 1000 && b.state.mmr > 1000`. required: - type - cel description: >- CEL expression escape hatch for custom match logic. description: >- One of five rule primitives (difference, equals, not_equals, region, expression). See docs. description: >- Declarative match rules. All must pass for two lobbies to match. See docs for full primitive grammar. useVersionFromState: type: string description: >- When set, the server's build name (`version_tag`) is taken from this field in the matched players' state. Lets you run multiple game versions simultaneously with no rolling updates. REQUIRED: an `equals` rule on the same field, so matched players always share the version. matchConfirmation: type: object properties: enabled: type: boolean description: >- When true, matches enter `match_found` and await player acceptance. timeoutSeconds: type: integer minimum: 1 description: >- Seconds players have to confirm before the match cancels. requireAllPlayers: type: boolean description: >- When true (default), every participating lobby must confirm. When false, partial confirmations can proceed. required: - enabled - timeoutSeconds description: >- Optional 'Accept Match' flow. Matches pause at `match_found` for player confirmation before launching. serverOverrides: type: object properties: gameBuild: type: string description: >- Build name to use for servers created by this lobby/mode (e.g., "default", "ranked"). gameBuildVersion: type: integer description: >- Specific build version number. Pin to an exact version for consistency. serverSize: type: string description: >- Compute size for servers created by this lobby (e.g., "small", "medium", "large"). maxGameTime: type: integer description: >- Maximum game duration in seconds. Server auto-stops after this time. description: >- Override the lobby's default server settings for this specific mode. required: - teams - playersPerTeam - minPlayersPerTeam - timeout - maxPartySize description: >- Configuration for a matchmaking mode within a lobby. Defines team structure, player limits, and matching rules. description: >- Named matchmaking modes. Keys are mode identifiers (e.g., "ranked", "casual"). Values define team structure and rules. required: - modes description: >- Matchmaking configuration. Omit to create a lobby without automated matchmaking. required: - id - name - enabled - timeout description: >- Configuration for a lobby type. Defines player limits, matchmaking rules, and server settings. description: Current lobby and matchmaking configurations. updated_at: type: string format: date-time description: ISO 8601 timestamp of the last settings update. required: - port_configs - auth_config - environment_variables - pool_config - lobby_configs - updated_at description: >- Complete current project settings including ports, auth, environment, pool, and lobby configurations. '400': description: >- Invalid input (e.g., duplicate port config, TLS on UDP port, invalid auth provider). content: application/json: schema: type: object properties: error: type: string description: Human-readable error message describing what went wrong. detail: type: string description: >- Additional error context. May contain the same text as error or more specific technical details. status: type: number description: HTTP status code (matches the response status code). required: - error - status description: >- Standard error response returned by all API endpoints on failure. '403': description: >- A client key (pfclient_*) was used. Updating project settings requires a server key (pf_...). content: application/json: schema: type: object properties: error: type: string description: Human-readable error message describing what went wrong. detail: type: string description: >- Additional error context. May contain the same text as error or more specific technical details. status: type: number description: HTTP status code (matches the response status code). required: - error - status description: >- Standard error response returned by all API endpoints on failure. '500': description: Internal server error while updating settings. content: application/json: schema: type: object properties: error: type: string description: Human-readable error message describing what went wrong. detail: type: string description: >- Additional error context. May contain the same text as error or more specific technical details. status: type: number description: HTTP status code (matches the response status code). required: - error - status description: >- Standard error response returned by all API endpoints on failure. components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: api-key ````