Mental Model

Quilt gets much easier once you stop thinking of it as “just containers” and start thinking of it as a runtime platform with a few durable building blocks.

If you are brand new, read this page before the route-by-route pages. It gives you the map before you start driving.

The Simple Version

Here is the shortest useful explanation:

A container is the running machine you care about.
An exec is a synchronous command you run inside that container — it blocks until the command exits and returns output inline.
An operation is Quilt’s receipt for async work like start, resume, snapshot, fork, or batch create.
A snapshot is a saved moment in time.
A fork is a writable branch from a live container.
A volume is storage that survives when containers come and go.
A terminal session is the interactive shell surface.
A cluster is the control plane for nodes, workloads, and placements.
A function is Quilt’s serverless surface.

Real-World Analogy

Think about Quilt like a movie production:

The container is the soundstage.
The volume is the props warehouse that stays around after filming ends.
The exec is a crew instruction like “run tests” or “build this project” — you give the order and get the result back directly.
The operation is the production ticket that tells you whether setup is still in progress or finished.
The snapshot is a photo of the set.
The fork is building a second copy of the set so someone can experiment without touching the original.

If you keep that framing in your head, most of the API starts to feel predictable.

Runtime Flow

Check health first

Before doing real work, confirm the platform is alive:

curl https://backend.quilt.sh/health

Find the right concern

Quilt exposes concern-specific help, examples, and health routes:

curl -H "X-Api-Key: $QUILT_API_KEY" \
  https://backend.quilt.sh/api/containers/help

Target the right resource

Resolve the container, function, workload, or cluster you actually mean.

Act

Create, exec, snapshot, scale, invoke, or deploy.

Inspect the result

If the route returned 202, follow the operation. Otherwise read the response body directly — exec, create, stop, kill, and delete all return their final result inline.

The Most Important Rule

Do not confuse “created” with “ready.”

That matters because Quilt separates lifecycle phases:

A container can exist without being exec-ready.
Network allocation is not the same as app health.
GUI workloads have an extra readiness layer.
Functions can exist before capacity is warmed.

The most common beginner mistake is to create something and immediately assume it can already accept commands or traffic.

Resource Cheat Sheet

Resource	What It Is	When to Use It
Container	Main runtime unit	Run apps, jobs, services, and dev environments
Exec	Synchronous command inside a container	Build, test, inspect, script — result returned inline
Stream	Live non-PTY output surface	Watch command output in real time
Terminal	Interactive PTY shell	Debugging and manual work
Operation	Async lifecycle handle	Track start, resume, fork, snapshot, batch create
Snapshot	Saved state	Reproducibility and safe cloning
Fork	Writable branch from a live container	Experiment without touching the original
Volume	Persistent storage	Keep files across container replacement
Function	Serverless execution surface	Event-driven workloads
Cluster	Desired-state control plane	Nodes, workloads, placements, manifests

Concern Guides

Most major surfaces expose these routes:

GET /api/<concern>/help
GET /api/<concern>/examples
GET /api/<concern>/health

That means Quilt documents itself per concern. If you are unsure where to start, ask the concern for its own contract before guessing.