> ## 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. # Start a new server > Creates and launches a new game server instance. The server starts in `launching` status and transitions to `running` when the game process opens its configured ports (typically 10–30 seconds, or ~5 seconds if a pool server is available). The response includes `network_ports` with the connection details (host + external_port) that game clients need to connect. **Plan limits:** Free plan allows 1 active server with a 1-hour TTL and `small` compute. Pro plan unlocks unlimited servers with all compute sizes. **Build resolution:** Uses the latest `ready` build matching `version_tag` (defaults to `"default"`). Pin to a specific build with the `version` parameter. ## OpenAPI ````yaml https://api.computeflow.cloud/api/doc post /api/v3/servers/start 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/servers/start: post: tags: - Servers summary: Start a new server description: >- Creates and launches a new game server instance. The server starts in `launching` status and transitions to `running` when the game process opens its configured ports (typically 10–30 seconds, or ~5 seconds if a pool server is available). The response includes `network_ports` with the connection details (host + external_port) that game clients need to connect. **Plan limits:** Free plan allows 1 active server with a 1-hour TTL and `small` compute. Pro plan unlocks unlimited servers with all compute sizes. **Build resolution:** Uses the latest `ready` build matching `version_tag` (defaults to `"default"`). Pin to a specific build with the `version` parameter. operationId: startServer requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 description: >- Display name for this server instance. Visible in the dashboard and API responses. Example: "ranked-match-1", "lobby-eu-west". region: type: string minLength: 1 description: >- Deployment region. Determines where the server runs physically. Case-insensitive. Available regions: us-east, us-south, us-west, eu-north, eu-west, eu-uk, ap-south, sea, ap-north, ap-southeast, south-america-brazil, south-america-chile, south-america, south-africa, ea. Note: south-america and ea are legacy aliases for south-america-brazil and ap-north. startup_args: type: string description: >- Command-line arguments passed to your game executable. Accessible in your game via PLAYFLOW_STARTUP_ARGS env var or the config API. Example: "-map forest -maxplayers 16 -tickrate 64". compute_size: type: string enum: - micro - small - medium - large - xlarge - dedicated-small - dedicated-medium - dedicated-large - dedicated-xlarge - persistent-small - persistent-medium - persistent-large - persistent-xlarge default: small description: >- Machine size for the server. Shared CPU: micro (512MB), small (1GB), medium (2GB), large (4GB), xlarge (8GB). Dedicated CPU: dedicated-small (2GB), dedicated-medium (4GB), dedicated-large (8GB), dedicated-xlarge (16GB). Free plan is limited to "small". version_tag: type: string description: >- Build name to deploy (e.g., "default", "beta", "staging"). Uses the latest ready build with this name. If omitted, defaults to "default". version: type: integer description: >- Specific build version number to deploy. Overrides version_tag to pin to an exact build version. Useful for rollbacks or testing specific builds. ttl: type: integer minimum: 60 maximum: 86400 description: >- Time-to-live in seconds (60–86400). The server automatically stops after this duration. Free plan servers are forced to 3600 (1 hour). Omit for no auto-shutdown. auto_restart: type: boolean default: false description: >- Automatically restart the game process if it crashes or exits unexpectedly. Uses on-failure restart policy with max 10 retries. After 10 failures, the machine is destroyed. custom_data: type: object additionalProperties: {} description: >- Arbitrary key-value data attached to this server. Accessible in your game via PLAYFLOW_CUSTOM_DATA env var or the config API at localhost:9090/v1/config. Example: {"map": "forest", "mode": "ranked"}. match_id: type: string description: >- Match identifier for matchmaking integration. Auto-generated if not provided. Use this to link servers to your matchmaking system. environment_variables: type: object additionalProperties: type: string description: >- Additional environment variables injected into the game container. Merged with project-level defaults (server-level values override project defaults). Example: {"LOG_LEVEL": "debug"}. port_configs: type: array items: type: object properties: name: type: string description: >- Unique name for this port (e.g., "game_udp", "voice_tcp"). Used to identify the port in network_ports responses. internal_port: type: integer minimum: 1 maximum: 65535 description: >- Port number your game server listens on inside the container (1–65535). This is the port your game code binds to. protocol: type: string enum: - udp - tcp description: >- Network protocol. Use "udp" for real-time game traffic (FPS, racing) or "tcp" for reliable connections (turn-based, WebSocket). tls_enabled: type: boolean default: false description: >- Enable automatic TLS termination for this port. Only valid for TCP ports. Clients connect with TLS and PlayFlow terminates it before forwarding to your server. required: - name - internal_port - protocol description: >- Override the project-level port configuration for a specific server. Allows customizing ports on a per-server basis at start time. description: >- Override the project-level port configuration for this specific server. If omitted, the project's default port_configs are used. required: - name - region description: Configuration for starting a new game server instance. responses: '201': description: >- Server created and launching. The `network_ports` array contains connection details for game clients. Poll `GET /servers/{instance_id}` until status is `running`. content: application/json: schema: type: object properties: instance_id: type: string description: >- Unique identifier for this server instance (UUID). Use this to reference the server in all other API calls. name: type: string description: Display name of the server, as provided when starting. status: type: string enum: - launching - running - stopped description: >- Current server status. "launching": machine is being created and game is starting up. "running": game is ready and accepting connections. "stopped": server has been shut down. network_ports: type: array items: type: object properties: name: type: string description: >- Port name matching the port_configs entry (e.g., "game_udp"). internal_port: type: number description: >- Port number the game server listens on inside the container. external_port: type: number description: >- Public port number that players connect to from outside. protocol: type: string enum: - udp - tcp description: Network protocol for this port. host: type: string description: >- Hostname or IP address players connect to. For UDP: a proxy IPv4 address. For TCP: "connect.computeflow.cloud" (Fly.io L7 routing). tls_enabled: type: boolean description: >- Whether TLS termination is enabled for this port (TCP only). required: - name - internal_port - external_port - protocol - host - tls_enabled description: >- A network port mapping showing how external traffic reaches your game server. Use host:external_port as the connection address for game clients. description: >- List of allocated network ports with connection details. Give host:external_port to game clients for connecting. Empty if the server has stopped. startup_args: type: - string - 'null' description: >- Command-line arguments passed to the game executable. Null if none were provided. service_type: type: string enum: - match_based - persistent_world description: >- Server type. "match_based" (default): short-lived servers for individual matches. "persistent_world": long-running servers for persistent game worlds. compute_size: type: string description: >- Machine size this server is running on (e.g., "small", "medium", "dedicated-large"). region: type: string description: >- Region where this server is deployed (e.g., "us-east", "eu-west"). version_tag: type: string description: >- Build name this server was started with (e.g., "default", "beta"). version: type: - number - 'null' description: >- Build version number this server is running. Null if no specific version was resolved. started_at: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp when the server transitioned to "running" status (game ports opened). Null if still launching or never reached running state. stopped_at: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp when the server was stopped. Null if the server is still active. auto_restart: type: boolean description: >- Whether the game process auto-restarts on crash (max 10 retries). custom_data: type: - object - 'null' additionalProperties: {} description: >- Arbitrary metadata attached to this server. Null if no custom data was provided. ttl: type: - number - 'null' description: >- Time-to-live in seconds. The server auto-stops after this duration from start. Null if no TTL was set (server runs until explicitly stopped). is_pool_server: type: boolean description: >- Whether this server was claimed from the pre-provisioned pool. Pool servers have faster startup times (~5s vs ~30s). pool_claimed_at: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp when this pool server was claimed for use. Null for non-pool servers or unclaimed pool machines. match_id: type: - string - 'null' description: >- Match identifier for matchmaking integration. Auto-generated if not provided at start time. created_at: type: string format: date-time description: >- ISO 8601 timestamp when the server instance was created in the database. updated_at: type: string format: date-time description: >- ISO 8601 timestamp of the last update to this server record. required: - instance_id - name - status - network_ports - startup_args - service_type - compute_size - region - version_tag - version - started_at - stopped_at - auto_restart - custom_data - ttl - is_pool_server - pool_claimed_at - match_id - created_at - updated_at description: >- Complete details of a game server instance, including connection info, status, and configuration. components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: api-key ````