Fuse Orchestrator API

Control plane for Fuse orchestrator. Provisions, inspects, and destroys VMs; manages snapshots. This API is consumed by the fuse CLI (via the Go SDK), the language SDKs, and operations tooling. It is the stable HTTP surface for everything that is not the in-guest agent (fused), which exposes its own HTTP API from inside the VM.

Path prefix: /v1. Backward-incompatible changes bump the prefix.

Every non-2xx response under /v1 uses the Error envelope defined below. The one exception is the unauthenticated /ready probe, which reports failure as a bare {"status","checks"} object with no error key — so a client must not assume body.error.code is present on any non-2xx it receives.

Every response carries an X-Request-ID header — either the value the client supplied on the request (when it matches [A-Za-z0-9_-]{1,128}) or a freshly generated req_<32hex> identifier. The same value is threaded through audit events and server logs for correlation. Probe endpoints (/health, /ready, /metrics, /v1/version) are mounted outside this middleware and do not carry a request ID.

Version 0.1.0

Base URLhttp://localhost:8080

health

Unauthenticated probe and identity endpoints (mounted outside auth)

auth

Session-cookie login/logout for browser callers

environments

VM provisioning and inspection

snapshots

Checkpoint / restore lifecycle

hosts

Host registry and scheduling controls

api-keys

Revocable API key management (master token only; requires Postgres). These routes exist only when the orchestrator runs with a Postgres-backed key store (DATABASE_URL). Without it they are not registered, and a call — authenticated or not — returns 404 with code route_not_found, not 401. The CIDR allowlist still applies first: it is mounted at the router level, ahead of the not-found handler, so a caller outside the allowlist gets 403 forbidden instead and never reaches the 404.