PlayFlow Cloud Documentation

The PlayFlow Cloud API gives you full programmatic control over your game server infrastructure. You can start and stop servers, upload and manage builds, configure project settings, and monitor server health — all through standard HTTP requests. The API is designed for consumption by game clients, backend services, CI/CD pipelines, and AI agents alike. Every endpoint returns predictable JSON with machine-readable status fields and clear error messages.

Full OpenAPI Reference

Explore the interactive API reference with schemas, parameters, and try-it-out functionality for every endpoint.

Authentication

All API endpoints (except /api/health) require an API key passed via the api-key HTTP header.

curl https://app.playflowcloud.com/api/v3/servers \
  -H "api-key: pf_your_server_api_key"

API Key Types

PlayFlow projects have two API keys, each with a different access level:

Key Type	Prefix	Access Level	Use Case
Server API Key	`pf_*`	Full read/write	Backend services, CI/CD, admin tools
Client API Key	`pfclient_*`	Limited client-safe operations	Game clients, browser apps

You can find and regenerate your API keys in the PlayFlow Dashboard under Project Settings.

Never expose your Server API Key in client-side code or public repositories. Use the Client API Key for any code that ships to players.

Base URL

All API requests are made to:

https://app.playflowcloud.com/api

The canonical API version is v3. A v2 compatibility layer is available for legacy SDKs but all new integrations should target v3.

Version	Path Prefix	Notes
V3 (canonical)	`/api/v3/*`	Zod-validated, OpenAPI spec, clean response shapes
V2 (legacy)	`/api/v2/*`	Compatibility layer for older SDKs

Endpoints Overview

Servers

Manage the full lifecycle of your game servers — create, inspect, update, restart, and stop.

Method	Endpoint	Description
`GET`	`/v3/servers`	List servers for your project
`POST`	`/v3/servers/start`	Launch a new game server
`GET`	`/v3/servers/:instance_id`	Get details for a specific server
`POST`	`/v3/servers/:instance_id/update`	Update a server’s `custom_data`
`DELETE`	`/v3/servers/:instance_id`	Stop a running server
`POST`	`/v3/servers/:instance_id/restart`	Restart a server
`GET`	`/v3/servers/:instance_id/logs`	Retrieve server logs
`GET`	`/v3/servers/:instance_id/metrics`	Retrieve server resource metrics

Builds

Upload game server binaries and manage the build pipeline.

Method	Endpoint	Description
`GET`	`/v3/builds`	List builds for your project
`POST`	`/v3/builds/upload-url`	Get a presigned URL for ZIP upload
`POST`	`/v3/builds/docker-image`	Create a build from a Docker image
`POST`	`/v3/builds/:build_id/process`	Trigger build processing
`GET`	`/v3/builds/:build_id`	Get build details
`DELETE`	`/v3/builds/:build_id`	Soft-delete a build
`GET`	`/v3/builds/:build_id/logs`	Get build processing logs

Projects

Read and update project-level configuration, and query logs across all servers.

Method	Endpoint	Description
`GET`	`/v3/projects/settings`	Get project configuration
`POST`	`/v3/projects/settings`	Update project configuration
`GET`	`/v3/projects/logs`	Query logs across all servers

Common Operations

List Servers

Retrieve all running servers for your project. By default, only servers with status running are returned.

curl "https://app.playflowcloud.com/api/v3/servers?include_launching=true&limit=20" \
  -H "api-key: pf_your_server_api_key"

Query parameters:

include_launching

boolean

default:"false"

Include servers that are still in the launching state.

include_pool

boolean

default:"false"

Include pre-warmed pool servers in the results.

limit

integer

default:"50"

Maximum number of servers to return (1-100).

offset

integer

default:"0"

Number of servers to skip for pagination.

Response:

{
  "total": 3,
  "total_servers": 3,
  "servers": [
    {
      "instance_id": "abc123",
      "name": "us-east-lobby-1",
      "status": "running",
      "region": "us-east",
      "compute_size": "small",
      "version_tag": "default",
      "version": 4,
      "network_ports": [
        {
          "name": "game",
          "internal_port": 7777,
          "external_port": 12345,
          "protocol": "udp",
          "host": "connect.playflowcloud.com",
          "tls_enabled": false
        }
      ],
      "started_at": "2026-03-15T10:30:00.000Z",
      "stopped_at": null,
      "custom_data": { "map": "arena_01" },
      "ttl": 3600,
      "is_pool_server": false,
      "match_id": null,
      "auto_restart": false,
      "created_at": "2026-03-15T10:29:55.000Z",
      "updated_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Start a Server

Launch a new game server instance. The server is provisioned immediately and moves through launching to running status.

curl -X POST "https://app.playflowcloud.com/api/v3/servers/start" \
  -H "api-key: pf_your_server_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "us-east-lobby-1",
    "region": "us-east",
    "compute_size": "small",
    "version_tag": "default",
    "ttl": 3600,
    "custom_data": {
      "map": "arena_01",
      "max_players": 16
    }
  }'

Request body:

name

string

required

A display name for the server instance.

region

string

required

The deployment region. See Server Regions for the full list.

compute_size

string

default:"small"

Server instance size. One of: micro, small, medium, large, xlarge, dedicated-small, dedicated-medium, dedicated-large, dedicated-xlarge, persistent-small, persistent-medium, persistent-large, persistent-xlarge. See Pricing & Plan Types for specs.

version_tag

string

The build name to deploy. Defaults to the latest build if not specified.

version

integer

A specific build version number. If omitted, the latest version for the given version_tag is used.

startup_args

string

Command-line arguments passed to your game server executable on launch.

ttl

integer

Time-to-live in seconds (60-86400). The server automatically stops after this duration.

auto_restart

boolean

default:"false"

If true, the server restarts automatically if the game process exits.

custom_data

object

Arbitrary key-value data attached to the server. Useful for passing map names, game modes, or match metadata to your game server at runtime.

match_id

string

An optional match identifier to associate this server with a specific match or lobby.

environment_variables

object

Key-value string pairs set as environment variables on the server instance.

port_configs

array

Override the project-level port configuration for this server. Each entry specifies a name, internal_port, protocol (udp or tcp), and optional tls_enabled flag.

Response (201 Created):

{
  "instance_id": "abc123",
  "name": "us-east-lobby-1",
  "status": "launching",
  "region": "us-east",
  "compute_size": "small",
  "version_tag": "default",
  "version": 4,
  "network_ports": [
    {
      "name": "game",
      "internal_port": 7777,
      "external_port": 12345,
      "protocol": "udp",
      "host": "connect.playflowcloud.com",
      "tls_enabled": false
    }
  ],
  "startup_args": null,
  "service_type": "match_based",
  "started_at": null,
  "stopped_at": null,
  "auto_restart": false,
  "custom_data": { "map": "arena_01", "max_players": 16 },
  "ttl": 3600,
  "is_pool_server": false,
  "pool_claimed_at": null,
  "match_id": null,
  "created_at": "2026-03-15T10:29:55.000Z",
  "updated_at": "2026-03-15T10:29:55.000Z"
}

The server starts in launching status. Once the game process is ready, the status changes to running and started_at is populated. You can poll GET /v3/servers/:instance_id or use include_launching=true when listing servers to track this transition.

Stop a Server

Shut down a running server and release its resources.

curl -X DELETE "https://app.playflowcloud.com/api/v3/servers/abc123" \
  -H "api-key: pf_your_server_api_key"

Query parameters:

shutdown_reason

string

An optional reason for stopping the server, recorded for logging purposes.

Response:

{
  "status": "stopped"
}

Upload a Build

Uploading a build is a three-step process: request a presigned upload URL, upload your ZIP file, then trigger processing.

Request an upload URL

Call the upload-url endpoint to get a presigned R2 URL and a build_id.

curl -X POST "https://app.playflowcloud.com/api/v3/builds/upload-url?name=default&executable_path=GameServer.x86_64" \
  -H "api-key: pf_your_server_api_key"

Response (201 Created):

{
  "build_id": "build_abc123",
  "name": "default",
  "upload_url": "https://r2.cloudflarestorage.com/...",
  "message": "Upload your ZIP file to the provided URL, then call /process"
}

Upload your ZIP file

Use the presigned URL to upload your game server build as a ZIP archive.

curl -X PUT "https://r2.cloudflarestorage.com/..." \
  -H "Content-Type: application/zip" \
  --data-binary @my-game-server.zip

Trigger processing

Start the build processing pipeline. This compresses the build into .tar.zst format and creates a per-build Docker image.

curl -X POST "https://app.playflowcloud.com/api/v3/builds/build_abc123/process?name=default" \
  -H "api-key: pf_your_server_api_key"

Response (202 Accepted):

{
  "status": "processing",
  "build_id": "build_abc123",
  "message": "Build processing has been triggered"
}

You can track build progress by polling GET /v3/builds/:build_id or by streaming build logs from GET /v3/builds/:build_id/logs.

Create a Build from Docker Image

If you already have a containerized game server, you can create a build directly from a Docker image instead of uploading a ZIP.

curl -X POST "https://app.playflowcloud.com/api/v3/builds/docker-image" \
  -H "api-key: pf_your_server_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "image_url": "ghcr.io/my-org/game-server:latest",
    "executable_path": "/app/GameServer",
    "registry_credentials": {
      "username": "my-user",
      "password": "my-token"
    }
  }'

name

string

default:"default"

The build name (used as the version_tag when starting servers).

image_url

string

required

The full Docker image URL including tag.

executable_path

string

Path to the game server executable inside the container.

registry_credentials

object

Credentials for private registries. Include username and password fields.

Response Shapes

Server Object

Every server endpoint returns or includes the following shape:

Show Server response fields

instance_id

string

Unique identifier for the server instance.

name

string

Display name of the server.

status

string

Current server state: launching, running, or stopped.

network_ports

array

List of port mappings. Each entry contains name, internal_port, external_port, protocol, host, and tls_enabled.

startup_args

string | null

Command-line arguments passed to the game server.

service_type

string

Either match_based or persistent_world.

compute_size

string

Instance size (e.g., small, large, dedicated-medium).

region

string

Deployment region identifier.

version_tag

string

The build name deployed on this server.

version

integer | null

The build version number, if applicable.

started_at

string | null

ISO 8601 timestamp when the server became running. Null while launching.

stopped_at

string | null

ISO 8601 timestamp when the server was stopped.

auto_restart

boolean

Whether the server restarts automatically on process exit.

custom_data

object | null

Arbitrary metadata attached to the server.

ttl

integer | null

Time-to-live in seconds, if set.

is_pool_server

boolean

Whether this server was provisioned from the pre-warmed pool.

pool_claimed_at

string | null

ISO 8601 timestamp when a pool server was claimed.

match_id

string | null

Associated match or lobby identifier.

created_at

string

ISO 8601 timestamp when the instance record was created.

updated_at

string

ISO 8601 timestamp of the last update.

Build Object

Show Build response fields

build_id

string

Unique identifier for the build.

name

string

Build name, used as the version_tag when starting servers.

version

integer

Auto-incremented version number within this build name.

status

string

Build state: uploading, processing, ready, failed, or deleted.

build_type

string

Either zip (uploaded archive) or docker_image.

executable_path

string | null

Path to the game server executable.

image_url

string | null

Docker image URL, if the build was created from a container image.

created_at

string

ISO 8601 timestamp when the build was created.

updated_at

string | null

ISO 8601 timestamp of the last update.

Server Logs and Metrics

Server Logs

Retrieve stdout/stderr logs from a running or recently stopped server.

curl "https://app.playflowcloud.com/api/v3/servers/abc123/logs?limit=100" \
  -H "api-key: pf_your_server_api_key"

start_time

string

ISO 8601 timestamp to begin retrieving logs from.

limit

integer

default:"200"

Number of log entries to return (1-1000).

Response:

{
  "logs": [
    {
      "timestamp": "2026-03-15T10:30:05.123Z",
      "message": "Server started on port 7777",
      "level": "info",
      "instance": "abc123",
      "region": "us-east"
    }
  ],
  "instance_id": "abc123",
  "machine_id": "fly-machine-id",
  "next_token": null
}

Server Metrics

Retrieve CPU, memory, network, and connection metrics for a running server.

curl "https://app.playflowcloud.com/api/v3/servers/abc123/metrics?period=1h&step=60s" \
  -H "api-key: pf_your_server_api_key"

period

string

default:"1h"

Time window for metrics. One of: 5m, 15m, 1h, 6h, 24h.

step

string

default:"60s"

Resolution between data points. One of: 15s, 30s, 60s, 300s.

Response:

{
  "instance_id": "abc123",
  "machine_id": "fly-machine-id",
  "region": "us-east",
  "period": {
    "start": 1742036400,
    "end": 1742040000,
    "step": "60s"
  },
  "cpu": {
    "usage_percent": [{ "t": 1742036400, "v": 12.5 }]
  },
  "memory": {
    "used_mb": [{ "t": 1742036400, "v": 256 }],
    "total_mb": 1024
  },
  "network": {
    "rx_bytes_per_sec": [{ "t": 1742036400, "v": 1024 }],
    "tx_bytes_per_sec": [{ "t": 1742036400, "v": 2048 }]
  },
  "load": {
    "average_1m": [{ "t": 1742036400, "v": 0.5 }]
  },
  "connections": {
    "tcp": [{ "t": 1742036400, "v": 8 }]
  }
}

Error Handling

All error responses share a consistent JSON structure:

{
  "error": "Human-readable error message",
  "detail": "Same as error (for legacy SDK compatibility)",
  "status": 400
}

Common Status Codes

Status	Meaning
`200`	Success
`201`	Resource created (server started, upload URL generated)
`202`	Accepted (build processing triggered)
`401`	Missing or invalid `api-key` header
`404`	Server, build, or resource not found
`422`	Validation error (malformed request body or missing required fields)
`429`	Rate limit exceeded
`500`	Internal server error

Validation Errors

When request validation fails, the response includes structured error details:

{
  "error": "Validation error",
  "detail": [
    {
      "loc": ["region"],
      "msg": "Required",
      "type": "invalid_type"
    }
  ],
  "status": 422
}

Rate Limiting

The API uses token-bucket rate limiting per API key. Rate limit status is returned in response headers.

Endpoint Type	Limit
Read endpoints (list, get, logs, metrics)	100 requests/second
Write endpoints (start server, upload build)	10 requests/second

Response headers:

Header	Description
`X-RateLimit-Limit`	Maximum tokens in the bucket
`X-RateLimit-Remaining`	Tokens remaining before throttling

When the rate limit is exceeded, you receive a 429 response:

{
  "error": "Rate limit exceeded",
  "detail": "Rate limit exceeded. Please retry after a short wait.",
  "status": 429
}

Regions

Deploy your servers across 12 global regions for low-latency gameplay. Pass any of these region IDs to the region field when starting a server.

Region	ID
US East	`us-east`
US West	`us-west`
Europe North (Sweden)	`eu-north`
Europe West (France)	`eu-west`
Asia South (India)	`ap-south`
Southeast Asia (Singapore)	`sea`
East Asia (Hong Kong)	`ea`
Asia North (Japan)	`ap-north`
Australia	`ap-southeast`
South Africa	`south-africa`
South America (Brazil)	`south-america-brazil`
South America (Chile)	`south-america-chile`

See Server Regions for the full details on each region.

SDK and Tooling

Unity SDK

Use the PlayFlow Unity SDK for C# wrappers around the REST API, including server management from your game client.

Interactive API Reference

Explore every endpoint with the full OpenAPI specification, request/response schemas, and a try-it-out console.

Getting Started

Game Servers

Lobbies & Matchmaking

Platform

Guides

Fundamentals

REST API Reference

Full OpenAPI Reference

Authentication

API Key Types

Base URL

Endpoints Overview

Servers

Builds

Projects

Common Operations

List Servers

Start a Server

Stop a Server

Upload a Build

Create a Build from Docker Image

Response Shapes

Server Object

Build Object

Server Logs and Metrics

Server Logs

Server Metrics

Error Handling

Common Status Codes

Validation Errors

Rate Limiting

Regions

SDK and Tooling

Unity SDK

Interactive API Reference

Getting Started

Game Servers

Lobbies & Matchmaking

Platform

Guides

Fundamentals

Full OpenAPI Reference

​Authentication

​API Key Types

​Base URL

​Endpoints Overview

​Servers

​Builds

​Projects

​Common Operations

​List Servers

​Start a Server

​Stop a Server

​Upload a Build

​Create a Build from Docker Image

​Response Shapes

​Server Object

​Build Object

​Server Logs and Metrics

​Server Logs

​Server Metrics

​Error Handling

​Common Status Codes

​Validation Errors

​Rate Limiting

​Regions

​SDK and Tooling

Unity SDK

Interactive API Reference

Authentication

API Key Types

Base URL

Endpoints Overview

Servers

Builds

Projects

Common Operations

List Servers

Start a Server

Stop a Server

Upload a Build

Create a Build from Docker Image

Response Shapes

Server Object

Build Object

Server Logs and Metrics

Server Logs

Server Metrics

Error Handling

Common Status Codes

Validation Errors

Rate Limiting

Regions

SDK and Tooling