Start a new server

curl --request POST \
  --url https://playflow.dev/api/api/v3/servers/start \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "region": "<string>",
  "startup_args": "<string>",
  "compute_size": "small",
  "version_tag": "<string>",
  "version": 123,
  "ttl": 43230,
  "auto_restart": false,
  "custom_data": {},
  "match_id": "<string>",
  "environment_variables": {},
  "port_configs": [
    {
      "name": "<string>",
      "internal_port": 32768,
      "protocol": "udp",
      "tls_enabled": false
    }
  ]
}
'

{
  "instance_id": "<string>",
  "name": "<string>",
  "status": "launching",
  "network_ports": [
    {
      "name": "<string>",
      "internal_port": 123,
      "external_port": 123,
      "protocol": "udp",
      "host": "<string>",
      "tls_enabled": true
    }
  ],
  "startup_args": "<string>",
  "service_type": "match_based",
  "compute_size": "<string>",
  "region": "<string>",
  "version_tag": "<string>",
  "version": 123,
  "started_at": "2023-11-07T05:31:56Z",
  "stopped_at": "2023-11-07T05:31:56Z",
  "auto_restart": true,
  "custom_data": {},
  "ttl": 123,
  "is_pool_server": true,
  "pool_claimed_at": "2023-11-07T05:31:56Z",
  "match_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Servers

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.

POST

api

servers

start

Start a new server

curl --request POST \
  --url https://playflow.dev/api/api/v3/servers/start \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "region": "<string>",
  "startup_args": "<string>",
  "compute_size": "small",
  "version_tag": "<string>",
  "version": 123,
  "ttl": 43230,
  "auto_restart": false,
  "custom_data": {},
  "match_id": "<string>",
  "environment_variables": {},
  "port_configs": [
    {
      "name": "<string>",
      "internal_port": 32768,
      "protocol": "udp",
      "tls_enabled": false
    }
  ]
}
'

{
  "instance_id": "<string>",
  "name": "<string>",
  "status": "launching",
  "network_ports": [
    {
      "name": "<string>",
      "internal_port": 123,
      "external_port": 123,
      "protocol": "udp",
      "host": "<string>",
      "tls_enabled": true
    }
  ],
  "startup_args": "<string>",
  "service_type": "match_based",
  "compute_size": "<string>",
  "region": "<string>",
  "version_tag": "<string>",
  "version": 123,
  "started_at": "2023-11-07T05:31:56Z",
  "stopped_at": "2023-11-07T05:31:56Z",
  "auto_restart": true,
  "custom_data": {},
  "ttl": 123,
  "is_pool_server": true,
  "pool_claimed_at": "2023-11-07T05:31:56Z",
  "match_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

api-key

string

header

required

Body

application/json

Configuration for starting a new game server instance.

name

string

required

Display name for this server instance. Visible in the dashboard and API responses. Example: "ranked-match-1", "lobby-eu-west".

Minimum string length: 1

region

string

required

Deployment region. Determines where the server runs physically. Available regions: us-east, us-west, eu-west, eu-north, eu-uk, ap-south, ap-north, sea, ap-southeast, south-america, south-africa.

Minimum string length: 1

startup_args

string

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

enum<string>

default:small

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".

Available options:

micro,

small,

medium,

large,

xlarge,

dedicated-small,

dedicated-medium,

dedicated-large,

dedicated-xlarge,

persistent-small,

persistent-medium,

persistent-large,

persistent-xlarge

version_tag

string

Build name to deploy (e.g., "default", "beta", "staging"). Uses the latest ready build with this name. If omitted, defaults to "default".

version

integer

Specific build version number to deploy. Overrides version_tag to pin to an exact build version. Useful for rollbacks or testing specific builds.

ttl

integer

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.

Required range: 60 <= x <= 86400

auto_restart

boolean

default:false

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

object

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"}.

Show child attributes

match_id

string

Match identifier for matchmaking integration. Auto-generated if not provided. Use this to link servers to your matchmaking system.

environment_variables

object

Additional environment variables injected into the game container. Merged with project-level defaults (server-level values override project defaults). Example: {"LOG_LEVEL": "debug"}.

Show child attributes

port_configs

object[]

Override the project-level port configuration for this specific server. If omitted, the project's default port_configs are used.

Show child attributes

Response

201 - application/json

Server created and launching. The network_ports array contains connection details for game clients. Poll GET /servers/{instance_id} until status is running.

Complete details of a game server instance, including connection info, status, and configuration.

instance_id

string

required

Unique identifier for this server instance (UUID). Use this to reference the server in all other API calls.

name

string

required

Display name of the server, as provided when starting.

status

enum<string>

required

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.

Available options:

launching,

running,

stopped

network_ports

object[]

required

List of allocated network ports with connection details. Give host:external_port to game clients for connecting. Empty if the server has stopped.

Show child attributes

startup_args

string | null

required

Command-line arguments passed to the game executable. Null if none were provided.

service_type

enum<string>

required

Server type. "match_based" (default): short-lived servers for individual matches. "persistent_world": long-running servers for persistent game worlds.

Available options:

match_based,

persistent_world

compute_size

string

required

Machine size this server is running on (e.g., "small", "medium", "dedicated-large").

region

string

required

Region where this server is deployed (e.g., "us-east", "eu-west").

version_tag

string

required

Build name this server was started with (e.g., "default", "beta").

version

number | null

required

Build version number this server is running. Null if no specific version was resolved.

started_at

string<date-time> | null

required

ISO 8601 timestamp when the server transitioned to "running" status (game ports opened). Null if still launching or never reached running state.

stopped_at

string<date-time> | null

required

ISO 8601 timestamp when the server was stopped. Null if the server is still active.

auto_restart

boolean

required

Whether the game process auto-restarts on crash (max 10 retries).

custom_data

object

required

Arbitrary metadata attached to this server. Null if no custom data was provided.

Show child attributes

ttl

number | null

required

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

boolean

required

Whether this server was claimed from the pre-provisioned pool. Pool servers have faster startup times (~5s vs ~30s).

pool_claimed_at

string<date-time> | null

required

ISO 8601 timestamp when this pool server was claimed for use. Null for non-pool servers or unclaimed pool machines.

match_id

string | null

required

Match identifier for matchmaking integration. Auto-generated if not provided at start time.

created_at

string<date-time>

required

ISO 8601 timestamp when the server instance was created in the database.

updated_at

string<date-time>

required

ISO 8601 timestamp of the last update to this server record.

List servers Get server details

Servers

Lobbies & Matchmaking

Authorizations

Body

Response