Skip to main content
The Mirage HTTP API creates workspaces, runs shell commands, and reads or writes files. Run the Python or TypeScript server on your own machine or infrastructure. Both implementations follow the same OpenAPI contract.

Base URL

A local server uses http://127.0.0.1:8765 by default. Examples in this reference use that address. For a server on another machine, replace it with your server’s base URL. Routes are under /v1.

Make a request

Launch a server, then list its workspaces. Set MIRAGE_AUTH_TOKEN to the token configured on your server:
Local mode without a configured token accepts requests without the authorization header. See Authentication for token and JWT settings.

Start here

Quickstart

Create a workspace and run a shell command.

API reference

Find an endpoint by resource, parameter, or response field.

HTTP

Start a server and configure authentication and limits.

Errors

Handle HTTP failures and command exit codes.

Resource groups

Workspaces groups lifecycle operations, Shell, VFS, Agent Instructions, Approval requests, Commands, Jobs, Processes, and Machines. Each operation acts on a workspace. Configuration groups saved policies and saved VFS, CLI and machine configurations. Server groups Service health checks and Daemon readiness and shutdown operations.

OpenAPI contract

openapi.yaml defines the endpoints, request and response schemas, and examples shown in this reference. It retains every documented status code. The right pane shows successful response examples. Each endpoint’s collapsed Errors section explains its documented failures.