# Endpoints

The cloud compiler API is hosted at `https://compiler.quickback.dev`.

## Public (No Auth)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/templates` | GET | List available templates |

## Authenticated

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/compile` | POST | Compile definitions into backend files |

The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/compiler/cloud-compiler/authentication) for details.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `QUICKBACK_API_KEY` | API key for authentication (alternative to `quickback login`) |
| `QUICKBACK_API_URL` | Override compiler API URL (default: `https://compiler.quickback.dev`) |

### Custom Compiler URL

Point the CLI to a different compiler (local or custom):

```bash
QUICKBACK_API_URL=http://localhost:3020 quickback compile
```

See [Local Compiler](/compiler/cloud-compiler/local-compiler) for running the compiler locally with Docker.

## Streaming Protocol (`POST /compile`)

By default `/compile` returns a single JSON response. If the request includes `Accept: text/event-stream`, the compiler upgrades to Server-Sent Events so the CLI can render progress while the build runs.

There are two stream protocol versions, negotiated via the `X-Quickback-Stream` request header:

| Header | Protocol | Behavior |
|--------|----------|----------|
| _(absent)_ | **v1** | Sends `progress` events during the build, then a single `result` event with the entire compilation payload (config, generated files, drizzle output, SPA bundles, etc.) JSON-encoded as one frame. |
| `X-Quickback-Stream: v2` | **v2 (chunked)** | Sends `progress` events during the build, then a `meta` event with the file count, then one `file` event per generated file, then a final `done` event with metadata, commands, and warnings. |

The server echoes the chosen version back as the response `X-Quickback-Stream` header so the CLI knows which framing to parse.

### Why v2

Multi-megabyte SPA bundles (CMS + Account, with sourcemaps) take long enough to `JSON.stringify` that the v1 single-frame `result` event blocks Cloudflare's container event loop. Two things break: Docker's `HEALTHCHECK` fails, and the CLI's 120-second connection timeout fires before the body flushes. v2 emits files one at a time and yields back to the event loop every 10 files (`setImmediate`), keeping `/health` responsive and TCP backpressure alive.

The `@quickback-dev/cli` v0.10.x and later send `X-Quickback-Stream: v2` automatically. v1 is preserved for older clients.

### Event shapes (v2)

```
event: progress
data: { "stage": "vite-cms", "message": "..." }

event: meta
data: { "fileCount": 412, "version": "0.10.3" }

event: file
data: { "path": "src/...", "content": "...", ... }
…

event: done
data: { "meta": {...}, "commands": [...], "warnings": [...] }
```

On failure, an `error` event is emitted in either protocol:

```
event: error
data: { "error": "Compilation failed", "code": "...", "message": "..." }
```
