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 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):

QUICKBACK_API_URL=http://localhost:3020 quickback compile

See 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": "..." }