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

# Programmatic Access

> Learn how to start, stop, and manage your game servers programmatically using the PlayFlow API.

You can control your game servers from your game client, a custom backend service, or any other application by using the PlayFlow API.

We provide two primary ways to interact with the API:

* **Unity SDK**: A convenient C# wrapper for developers using Unity.
* **REST API**: For all other game engines and custom backends.

<CardGroup cols={2}>
  <Card title="REST API Reference" icon="code" href="/fundamentals/api" arrow="true" cta="View REST guide">
    Base URL, authentication, and curl examples for every endpoint.
  </Card>

  <Card title="OpenAPI Endpoints" icon="book-open" href="/api-reference/introduction" arrow="true" cta="Browse endpoints">
    The interactive, auto-generated reference for schemas and responses.
  </Card>
</CardGroup>

## Prerequisites

Before you start, make sure you have:

* The PlayFlow Unity SDK installed. See the [installation guide](/guides/installation).
* A PlayFlow project with at least one build uploaded.
* An API key from the [PlayFlow Dashboard](https://app.playflowcloud.com) under **Project Settings**. PlayFlow issues two key types:
  * **Server key** (`pf_*`) — full access. Keep it server-side (backend, CI/CD). Required for actions like deleting builds or updating project settings.
  * **Client key** (`pfclient_*`) — safe to ship inside a game build.

<Warning>
  Never embed a server key (`pf_*`) in a client or WebGL build. Use a client key (`pfclient_*`) for anything that ships to players.
</Warning>

## Unity SDK Examples

The following examples use the `PlayflowServerApiClient` class from the SDK.

### Initialization

First, you need to initialize the client with your PlayFlow API key.

```csharp theme={null}
using PlayFlow.SDK.Servers;

// Your API key from the PlayFlow dashboard
string playflowApiKey = "YOUR_API_KEY_HERE"; 

private PlayflowServerApiClient _apiClient;

void Start()
{
    _apiClient = new PlayflowServerApiClient(playflowApiKey);
}
```

### Starting a Game Server

To start a new server, you provide a configuration that specifies the server's name, region, and any custom data you want to pass to it. Both `name` and `region` are required. Select a build with `version_tag` (the build name) plus an optional `version`.

<Info>
  On the **Free** plan every server is forced to the `small` compute size and a 1-hour TTL, and you can run one active server at a time. Upgrade to **Pro** (\$20/mo) for all compute sizes, TTLs up to 24 hours, and unlimited active servers. See [plan and instance types](/fundamentals/plan-instance-types) and [regions](/fundamentals/regions).
</Info>

```csharp theme={null}
private async void StartNewServer()
{
    var serverRequest = new ServerCreateRequest
    {
        name = "MyCustomServer",
        region = "us-east",
        custom_data = new Dictionary<string, object>
        {
            { "map_name", "castle_siege" }
        }
    };

    try
    {
        ServerStartResponse response = await _apiClient.StartServerAsync(serverRequest);
        Debug.Log($"Server is starting! Instance ID: {response.instance_id}");
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to start server: {e.Message}");
    }
}
```

<Tip>
  To connect a game client, read the host and port from the `network_ports` array on the server object once the server is `running` — do not hardcode a port. Ports are allocated by the proxy and differ from your build's internal port. Poll the server (`GetServerAsync`) or list servers until `network_ports` is populated, then use `host` + `external_port` for each entry.
</Tip>

### Stopping a Game Server

To stop a running server, you just need its unique `instance_id`.

```csharp theme={null}
private async void StopServer(string instanceId)
{
    try
    {
        ServerStopResponse response = await _apiClient.StopServerAsync(instanceId);
        // The stop endpoint returns a confirmation message, e.g. "Server stopped successfully".
        Debug.Log($"Server stop initiated: {response.status}");
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to stop server: {e.Message}");
    }
}
```

### Listing Game Servers

You can get a list of all your currently running servers. This is perfect for building a server browser.

```csharp theme={null}
private async void ListAllServers()
{
    try
    {
        ServerList response = await _apiClient.ListServersAsync(includeLaunching: true);
        Debug.Log($"Found {response.total_servers} total servers.");

        foreach (var server in response.servers)
        {
            Debug.Log($"- Server: {server.name}, Status: {server.status}");
        }
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to list servers: {e.Message}");
    }
}
```

## REST API (any engine)

If you're not using Unity, the same operations are available over plain HTTP. The API base URL is `https://api.computeflow.cloud/api`, and every request authenticates with an `api-key` header.

Starting a server with the REST API mirrors the Unity example above:

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/servers/start" \
  -H "api-key: pf_your_server_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyCustomServer",
    "region": "us-east",
    "version_tag": "my-build",
    "custom_data": { "map_name": "castle_siege" }
  }'
```

The response includes a snake\_case `instance_id`. Once the server is `running`, read `host` and `external_port` from each entry in `network_ports` to connect a client — never hardcode a port.

<Info>
  See the [REST API Reference](/fundamentals/api) for authentication, the full server-start parameter set, and curl examples for stopping, listing, and inspecting servers.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Lobbies & Matchmaking" icon="users" href="/unity/lobby-overview">
    Group players and match them into sessions before launching a server.
  </Card>

  <Card title="Uploading Builds" icon="upload" href="/unity/game-servers">
    Upload and manage the server builds you launch with `version_tag`.
  </Card>

  <Card title="Plans & Instance Types" icon="server" href="/fundamentals/plan-instance-types">
    Compare compute sizes, plan limits, and TTLs.
  </Card>

  <Card title="Regions" icon="globe" href="/fundamentals/regions">
    The regions you can launch servers in.
  </Card>
</CardGroup>