> ## 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. # Restart a server > Restarts a server with a fresh instance. The old machine is replaced and new network ports are allocated. You can optionally change the build version, compute size, TTL, startup args, and other settings during restart. All fields in the request body are optional — omitted fields keep their current values. The server returns to `launching` status. **Note:** Pool servers cannot be restarted. ## OpenAPI ````yaml https://api.computeflow.cloud/api/doc post /api/v3/servers/{instance_id}/restart 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 a server key (`pf_...`) for privileged operations and a client key (`pfclient_...`) for game client integrations. Both work in the `api-key` header. ## 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**: 12 global regions (us-east, 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 - 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/{instance_id}/restart: post: tags: - Servers summary: Restart a server description: >- Restarts a server with a fresh instance. The old machine is replaced and new network ports are allocated. You can optionally change the build version, compute size, TTL, startup args, and other settings during restart. All fields in the request body are optional — omitted fields keep their current values. The server returns to `launching` status. **Note:** Pool servers cannot be restarted. operationId: restartServer parameters: - schema: type: string description: Server instance ID to restart. required: true description: Server instance ID to restart. name: instance_id in: path requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: >- New display name for the restarted server. Keeps the current name if omitted. startup_args: type: string description: >- New command-line arguments for the game executable. Keeps current args if omitted. version_tag: type: string description: >- Switch to a different build name on restart. Example: upgrade from "default" to "beta". version: type: integer description: >- Pin to a specific build version number on restart. Useful for rollbacks. ttl: type: integer minimum: 60 maximum: 86400 description: >- New time-to-live in seconds (60–86400). Resets the TTL countdown from the restart time. auto_restart: type: boolean description: Change auto-restart behavior on restart. custom_data: type: object additionalProperties: {} description: Replace custom_data on restart. match_id: type: string description: New match identifier for the restarted server. environment_variables: type: object additionalProperties: type: string description: >- Replace environment variables on restart. Merged with project defaults. 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 port configuration on restart. New ports are allocated. description: >- Configuration overrides applied during a server restart. All fields are optional — omitted fields keep their current values. The server gets a new machine with the same instance_id. responses: '200': description: >- Server restarting with `launching` status. New network_ports are allocated. 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. '404': description: No server found with this instance_id in your project. 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 ````