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

<CardGroup cols={2}>
  <Card title="OpenAPI Spec (JSON)" icon="download" href="https://api.computeflow.cloud/api/doc">
    Download the machine-readable OpenAPI 3.1 spec for use with Postman, code generators, or custom tooling.
  </Card>

  <Card title="Interactive Reference" icon="flask-vial" href="https://api.computeflow.cloud/api/reference">
    Try out endpoints directly in the Scalar API playground with live request/response previews.
  </Card>
</CardGroup>

***

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

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

<Warning>
  Never expose your **Server API Key** in client-side code. Use the **Client API Key** for anything that ships to players.
</Warning>

***

## Quick Start

<Steps>
  <Step title="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.
  </Step>

  <Step title="Wait for it to be ready">
    Poll `GET /v3/builds/{id}` until `status` is `ready`.
  </Step>

  <Step title="Start a server">
    `POST /v3/servers/start` — get connection info in `network_ports`.
  </Step>

  <Step title="Connect your game client">
    Use `host:external_port` from the response to connect players.
  </Step>
</Steps>

For detailed examples with cURL, C#, and Python, see the [full API guide](/fundamentals/api).

***

## 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.
* **Pool Servers** — Pre-provisioned servers for instant startup (\~5s vs \~30s cold start).
* **Regions** — 12 global regions. See [Server Regions](/fundamentals/regions) for the full list.
* **Compute Sizes** — From `micro` (512MB shared) to `dedicated-xlarge` (16GB dedicated CPU). See [Plan & Instance Types](/fundamentals/plan-instance-types).

***

## 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 | Pool |
| :------- | :-------- | :--------- | :------------ | :--- |
| **Free** | 1 max     | Forced 1hr | `small` only  | No   |
| **Pro**  | Unlimited | Custom     | All sizes     | Yes  |

***

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