> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Access Mirage workspaces through the open-source HTTP server.

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](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml).

## 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](https://docs.mirage.strukto.ai/home/access/http.md#launch-a-server), then list its workspaces.
Set `MIRAGE_AUTH_TOKEN` to the token configured on your server:

```bash theme={null}
curl --request GET \
  --url 'http://127.0.0.1:8765/v1/workspaces' \
  --header "Authorization: Bearer $MIRAGE_AUTH_TOKEN"
```

Local mode without a configured token accepts requests without the authorization
header. See [Authentication](https://docs.mirage.strukto.ai/api/authentication.md) for token and JWT settings.

## Start here

> [card] [Quickstart](https://docs.mirage.strukto.ai/api/quickstart.md)
>
> Create a workspace and run a shell command.

> [card] [API reference](https://docs.mirage.strukto.ai/api/reference.md)
>
> Find an endpoint by resource, parameter, or response field.

> [card] [HTTP](https://docs.mirage.strukto.ai/home/access/http.md)
>
> Start a server and configure authentication and limits.

> [card] [Errors](https://docs.mirage.strukto.ai/api/errors.md)
>
> 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`](https://github.com/strukto-ai/mirage/blob/main/docs/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.