# API reference

> The Flax Cloud REST API: base URL, authentication, response conventions, error shape, and the full interactive endpoint reference.

The Flax Cloud REST API is the foundation under the SDKs, the CLI, and the dashboard. Anything
you can do in the product, you can do over HTTP. The full, interactive endpoint reference (every
route, request body, and response, generated from the live OpenAPI spec) is at the bottom of this
page.

## Base URL

```
https://flaxcloud.com
```

All endpoints below are under `/v1/*`. `/health` and `/v1/auth/*` are public; everything else
requires a credential.

## Authentication

Send your API key as a bearer token on every request:

```http
Authorization: Bearer flax_live_xxxxx
```

Mint keys in the dashboard (**API Keys**) or with the CLI (`flax login` then manage keys). The
full key is shown once; only its SHA-256 hash is stored. The dashboard itself authenticates with
an httpOnly session cookie set after signing in through WorkOS. If an `Authorization` header is
present it takes precedence over the cookie.

Missing, malformed, unknown, or revoked credentials return `401` with a code of
`missing_credentials`, `invalid_api_key`, or `invalid_session`.

```bash
curl https://flaxcloud.com/v1/me -H "Authorization: Bearer $FLAX_API_KEY"
```

## Conventions

- **Resource IDs** are prefixed and opaque: `sbx_…` (sandbox), `cmd_…` (command), `ses_…`
  (session), `tpl_…` (template), `snap_…` (snapshot). Always store the immutable id.
- **Content types** are JSON in and JSON out. File contents are base64-encoded in the JSON body.
- **Timestamps** are ISO-8601 UTC.
- Each request resolves to one account; you only ever see your own resources.

## Health

A public, unauthenticated liveness check for uptime monitors. Returns `200` with `"ok"` when the
service is healthy and `503` with `"degraded"` when its hard dependency (the database) is down.

```http
GET /health
```

```json
{ "status": "ok" }
```

## Errors

Every error response shares one shape:

```json
{ "error": { "code": "concurrency_limit", "message": "Too many sandboxes at once." } }
```

Match on the stable `code` (not the human `message`). Common families:

| Status | Example codes | Meaning |
|--------|---------------|---------|
| `400` | `invalid_template`, `template_not_ready` | Bad request input. |
| `401` | `missing_credentials`, `invalid_api_key` | Auth failed. |
| `402` | `concurrency_limit`, `memory_limit`, `runtime_limit`, `storage_limit` | A [plan limit](./plans-and-limits.md) was hit. |
| `403` | `account_suspended` | Access blocked. |
| `404` | `sandbox_not_found`, `file_not_found` | Resource missing. |
| `409` | `preview_unavailable` | Conflicts with current state. |
| `429` | `rate_limited` | Back off and honor `Retry-After`. |
| `503` | `capacity_unavailable`, `server_busy` | Capacity or temporary API saturation. Back off and retry. |
| `5xx` | `internal_error` | Transient; idempotent calls are safe to retry. |

See [Plans & limits](./plans-and-limits.md) for the full quota error table.

## Client libraries

Most users drive the API through a client rather than raw HTTP:

- **[Python SDK & CLI](./sdk.md)** - `pip install flaxcloud`
- **[JavaScript / TypeScript SDK](./sdk-js.md)** - `npm install @flaxcloud/sdk`

## Full endpoint reference