Quilt Developer Docs
QuiltDeveloper Docs

API

Authentication and Health

Authenticate correctly, check the right health endpoint, and discover each API concern safely.

If you only learn one defensive habit in Quilt, make it this one:

Check health before you mutate things.

That single habit prevents a lot of wasted debugging.

Authentication

Most protected routes accept one of these headers:

X-Api-Key: <key>
Authorization: Bearer <token>

Default base URL:

https://backend.quilt.sh

Example with an API key

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

Example with a bearer token

curl \
  -H "Authorization: Bearer $QUILT_TOKEN" \
  https://backend.quilt.sh/api/system/info

Do not send both styles unless your own client explicitly standardizes that behavior. Pick one auth scheme and stay consistent.

Health Checks: What Each One Means

Quilt uses different health endpoints for different questions.

QuestionRoute to useWhat it tells you
”Is the backend alive at all?”GET /healthLiveness only
”Is container work ready?”GET /api/containers/healthContainer concern readiness
”Can functions run?”GET /api/functions/healthFunction concern readiness
”Is elasticity healthy?”GET /api/elasticity/healthElasticity concern readiness
”Can I resolve curated runtime release metadata?”GET /api/nightly/healthCurated runtime profile-resolution readiness

Why /health Is Not Enough

GET /health is a front-door heartbeat. It does not prove that a specific subsystem is ready for your next action.

Analogy:

  • /health answers “is the building open?”
  • /api/containers/health answers “is the kitchen staffed and ready to cook?”

Both matter, but they are not the same question.

Concern Guides

Most major API families expose:

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

You can also request Markdown by adding ?format=markdown or sending Accept: text/markdown.

Example

curl \
  -H "X-Api-Key: $QUILT_API_KEY" \
  -H "Accept: text/markdown" \
  https://backend.quilt.sh/api/oci/help

Safe Startup Checklist

1

Check platform liveness

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

Check concern health

If you are about to work with containers, use:

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

Inspect help or examples if the route family is unfamiliar

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

Only then perform the mutation

This keeps troubleshooting grounded in real platform state instead of guesswork.

Common Mistakes

Because /health only proves the backend is alive. It does not guarantee container readiness, available capacity, or a healthy runtime worker.

Yes. OCI is covered by the oci concern, including GET /api/oci/help, GET /api/oci/examples, and GET /api/oci/health.

Yes. Use GET /api/nightly/help, GET /api/nightly/examples, and GET /api/nightly/health when you are debugging curated runtime profile and release resolution in the core Quilt control plane.

No. First confirm health, then inspect the returned operation or error. Blind retries can create duplicate work or hide the real problem.

Minimal Working Check

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

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

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

Next Step

Once auth and health are working, move to Containers.