Skip to main content
The Mirage HTTP API serves workspaces over JSON at /v1. The local daemon (Python or TypeScript) and the hosted API answer the same routes with the same bodies, so a client written against one works against the other.
Embedding Mirage in a Python or TypeScript program? Use the library instead: it runs the same workspaces in process, with no server. See Python or TypeScript.

​
Where it runs

The mirage CLI starts a daemon on the first command that needs one. To run one from code, see Launch a server.

​
Authenticate

Send the server’s token on every request:
GET /v1/health needs no token. A daemon with no token set accepts every request, so set one before anyone else can reach it. Tokens, JWTs and per-account workspaces are covered in Auth and Configure authentication.

​
Errors

A 200 from POST /v1/workspaces/{workspace_id}/shell means the server ran the line, not that the line succeeded: check exit_code. Other errors return JSON with a detail message, but an auth or Host refusal can be plain text, so check Content-Type before parsing. The full status table is in Errors; requests past a limit answer 429 with Retry-After (rate limits).

​
Reference and contract

  • API reference: every operation, searchable and filterable by resource.
  • openapi.yaml: the OpenAPI document the reference is generated from. Both servers are checked against it in CI.