> ## 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.

# Overview

> The Mirage HTTP API: where it runs, how to authenticate, and how errors look.

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.

> [!NOTE]
>
> Embedding Mirage in a Python or TypeScript program? Use the library instead:
> it runs the same workspaces in process, with no server. See
> [Python](https://docs.mirage.strukto.ai/python/quickstart.md) or [TypeScript](https://docs.mirage.strukto.ai/typescript/quickstart.md).

## Where it runs

| Host | Base URL | Routes |
| - | - | - |
| Local daemon | `http://127.0.0.1:8765` by default | Every route in the [reference](https://docs.mirage.strukto.ai/api/reference.md) |
| Hosted API | Your hosted API URL | Rows marked **daemon and hosted** in the reference, plus the hosted API's own account routes |

The `mirage` CLI starts a daemon on the first command that needs one. To run
one from code, see [Launch a server](https://docs.mirage.strukto.ai/home/access/http.md#launch-a-server).

## Authenticate

Send the server's token on every request:

```bash theme={null}
curl http://127.0.0.1:8765/v1/workspaces \
  -H "Authorization: Bearer $MIRAGE_AUTH_TOKEN"
```

`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](https://docs.mirage.strukto.ai/home/access/http.md#auth) and
[Configure authentication](https://docs.mirage.strukto.ai/home/access/http.md#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](https://docs.mirage.strukto.ai/home/access/http.md#errors); requests past a limit answer `429` with
`Retry-After` ([rate limits](https://docs.mirage.strukto.ai/home/access/http.md#rate-limits)).

## Reference and contract

* [API reference](https://docs.mirage.strukto.ai/api/reference.md): every operation, searchable and filterable
  by resource.
* [`openapi.yaml`](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml):
  the OpenAPI document the reference is generated from. Both servers are
  checked against it in CI.


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