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

# API Introduction

> Authenticate, explore endpoints, and download the OpenAPI spec for the PlayFlow REST API.

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.

> [card] [OpenAPI Spec (JSON)](https://api.computeflow.cloud/api/doc)
>
> Download the machine-readable OpenAPI 3.1 spec for use with Postman, code generators, or custom tooling.

> [card] [Interactive Reference](https://api.computeflow.cloud/api/reference)
>
> Try out endpoints directly in the Scalar API playground with live request/response previews.

***

## Authentication

All API endpoints (except Health) require the `api-key` header:

```bash theme={null}
curl https://api.computeflow.cloud/api/v3/servers \
  -H "api-key: pf_your_project_api_key"
```

Each project has two keys:

| Key Type | Prefix | Use Case |
| :- | :- | :- |
| Server API Key | `pf_*` | Backend services, CI/CD, admin tools |
| Client API Key | `pfclient_*` | Game clients, browser apps |

> [!NOTE]
>
> Find your API keys in the [PlayFlow Dashboard](https://app.playflowcloud.com) under **Project Settings**.

> [!WARNING]
>
> Never expose your **Server API Key** in client-side code. Use the **Client API Key** for anything that ships to players.

> [!NOTE]
>
> A few operations — deleting builds and updating project settings — require a **Server API Key**. A Client API Key on these endpoints returns `403`.

***

## Quick Start

**1. Upload a build**

`POST /v3/builds/upload-url` — get a presigned URL, then `PUT` your ZIP to it. Processing starts automatically when the upload completes.

**2. Wait for it to be ready**

Poll `GET /v3/builds/{id}` until `status` is `ready`.

**3. Start a server**

`POST /v3/servers/start` with a `name`, a `region`, and the build's `version_tag` (its name). The response includes a `network_ports` array with the connection details.

**4. Connect your game client**

Read `host` and `external_port` from `network_ports[]` in the response to connect players. Ports are proxy-allocated, so always read them from the response rather than hardcoding a fixed port.

For detailed examples with cURL, C#, and Python, see the [full API guide](https://docs.playflowcloud.com/fundamentals/api.md).

***

## 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. Servers launch on-demand and cold-start.
* **Regions** — 13 global regions. `region` is required when you start a server. See [Server Regions](https://docs.playflowcloud.com/fundamentals/regions.md) for the full list.
* **Compute Sizes** — 9 launchable sizes, from `micro` (1 shared vCPU / 512MB) to `dedicated-xlarge` (2 perf vCPU / 16GB). The default is `small`. See [Plan & Instance Types](https://docs.playflowcloud.com/fundamentals/plan-instance-types.md).

***

## Lifecycles

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

| Endpoint Type | Limit |
| :- | :- |
| Read endpoints (list, get, logs) | 100 req/sec per API key |
| Write endpoints (start, upload) | 10 req/sec per API key |

Rate limit status is returned via `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers. Exceeding the limit returns `429`.

***

## Plan Limits

| Plan | Servers | TTL | Compute Sizes |
| :- | :- | :- | :- |
| **Free** | 1 active max | Forced 1 hour (3600s) | `small` only |
| **Pro** (\$20/mo) | Unlimited | Up to 24 hours (86400s) | All sizes |

***

## Error Format

All errors return a consistent JSON shape:

```json theme={null}
{
  "error": "Human-readable message",
  "detail": "Additional context",
  "status": 404
}
```

Validation errors (422) include structured details:

```json theme={null}
{
  "error": "Validation error",
  "detail": [
    { "loc": ["region"], "msg": "Required", "type": "invalid_type" }
  ],
  "status": 422
}
```

***

## Base URL

```
https://api.computeflow.cloud/api
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.