Skip to main content
POST
/
api
/
v3
/
servers
/
{instance_id}
/
restart
Restart a server
curl --request POST \
  --url https://playflow.dev/api/api/v3/servers/{instance_id}/restart \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "startup_args": "<string>",
  "version_tag": "<string>",
  "version": 123,
  "ttl": 43230,
  "auto_restart": true,
  "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

Path Parameters

​
instance_id
string
required

Server instance ID to restart.

Body

application/json

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.

​
name
string

New display name for the restarted server. Keeps the current name if omitted.

​
startup_args
string

New command-line arguments for the game executable. Keeps current args if omitted.

​
version_tag
string

Switch to a different build name on restart. Example: upgrade from "default" to "beta".

​
version
integer

Pin to a specific build version number on restart. Useful for rollbacks.

​
ttl
integer

New time-to-live in seconds (60–86400). Resets the TTL countdown from the restart time.

Required range: 60 <= x <= 86400
​
auto_restart
boolean

Change auto-restart behavior on restart.

​
custom_data
object

Replace custom_data on restart.

​
match_id
string

New match identifier for the restarted server.

​
environment_variables
object

Replace environment variables on restart. Merged with project defaults.

​
port_configs
object[]

Override port configuration on restart. New ports are allocated.

Response

Server restarting with launching status. New network_ports are allocated.

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.

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

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