Skip to content

The API, at a glance

Examples: https://runner.example.com

View as Markdown

Durable Runner’s whole surface is nine routes on durable-server. The examples here and on the feature pages use https://runner.example.com — put your own server in.

Terminal window
curl -s https://runner.example.com/health
{"ok":true}
Route Key What it is
GET /health — liveness: process up, journal open
GET /ready — readiness: live counts, space and headroom — 503 with a code when not
POST /jobs write submit a job (op_key + spec); deduped on op_key
GET /jobs either page the run list (order, before/after, limit)
GET /jobs/{id} either one run’s state
GET /jobs/{id}/spec write the spec it was submitted with — read key refused, the input may be content
POST /jobs/{id}/cancel write stop dispatching; cannot unsend a call already made
POST /admin/compact write write a snapshot, retire older journal generations
POST /admin/backup write a consistent, checksummed copy under --backup-root
GET /admin/diagnostics write operational counters — live runs, index bytes, journal stats

“Key” means Authorization: Bearer …: the write key is DURABLE_API_KEY, the read-only key is DURABLE_READ_KEY; reads accept either. Detail: Authentication and keys.

  • Calling from your own service → the HTTP API, exactly as on Jobs. Keep the op_key stable across your own retries; it is what makes a retry safe.
  • Operating from a shell → the CLI — the same routes as one-line JSON commands, plus restore, the only offline operation.
  • Looking, not scripting → the Inspector — the same read surface in a browser; give it the read key.
  • Generating a client → the API reference renders the OpenAPI draft and serves the machine-readable document at /openapi.json.

Every error is the same envelope — {"code", "error"} — with a stable code you can branch on: Errors lists them all with real responses. The retry-safe ones (503 at_capacity, 503 no_space, 503 drain, 429) deserve a retry with the same op_key; the 4xx ones mean fix the request first.

Was this page helpful?

Either answer opens a short issue on GitHub, so you can say what worked or what was missing.