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

# REST API Overview

> Read traces, events, and metadata over a simple authenticated HTTP API — built for backends, agents, and automations

The **Mirador REST API** is a read-only HTTP API for querying your traces, their event timelines, and project metadata. It's the companion to the ingest SDKs: the SDKs *write* traces, the REST API *reads* them back — from a backend service, a CI job, an incident bot, or an AI agent.

It's the right tool when you want to:

* Pull the **full JSON of a trace** (and its complete event timeline) into another system — e.g. to attach to an investigation ticket.
* List or count traces matching a filter (status, severity, tag, attribute) over a time window.
* Let an **AI agent** explore your traces with a server key and a typed contract.

<Info>
  The REST API is **read-only**. To create traces and emit events, use the [Web SDK or Node.js SDK](/quickstart). The two use **different keys** — see [Authentication](/api/authentication).
</Info>

## Base URL

```
https://api.mirador.org
```

All data endpoints live under `/v1/*` and require a server API key. Responses are always scoped to the single project that key belongs to.

## Self-serve references

The API ships its own machine- and agent-readable docs. **Point people at the Swagger UI and point AI agents at `llms.txt`** — both are always current with the deployed API.

<CardGroup cols={2}>
  <Card title="Swagger UI" icon="book-open" href="https://api.mirador.org/docs">
    Interactive, try-it-in-the-browser docs for every endpoint. Best starting point for a human exploring the API.
  </Card>

  <Card title="llms.txt" icon="robot" href="https://api.mirador.org/llms.txt">
    A single plain-text brief written for LLMs — endpoints, filter syntax, response shapes, and worked examples. Paste it into an agent's context.
  </Card>

  <Card title="OpenAPI (YAML)" icon="file-code" href="https://api.mirador.org/openapi.yaml">
    The full machine-readable contract. Feed it to a code generator or API client.
  </Card>

  <Card title="OpenAPI (JSON)" icon="brackets-curly" href="https://api.mirador.org/openapi.json">
    The same contract in JSON, for tooling that prefers it.
  </Card>
</CardGroup>

<Tip>
  Wiring up an AI agent or assistant? Give it the contents of
  [`https://api.mirador.org/llms.txt`](https://api.mirador.org/llms.txt) plus a
  server key. That single file documents the auth scheme, the filter grammar,
  pagination, every response shape, and the event-payload model — enough for an
  agent to query Mirador with no other context.
</Tip>

## What you can call

| Endpoint                            | Purpose                                                    |
| ----------------------------------- | ---------------------------------------------------------- |
| `GET /v1/identity`                  | Confirm a key resolves to an org/project                   |
| `GET /v1/metadata/tags`             | List every tag this project has used                       |
| `GET /v1/metadata/attributes`       | List every attribute key this project has emitted          |
| `GET /v1/metadata/attributes/{key}` | List the values seen for one attribute key                 |
| `GET /v1/traces`                    | List/filter/count traces, with pagination and time windows |
| `GET /v1/traces/{trace_id}`         | Full summary for one trace                                 |
| `GET /v1/traces/{trace_id}/events`  | The complete, ordered event timeline for one trace         |

See [Endpoints](/api/endpoints) for parameters, filter syntax, and response shapes.

## A first request

```bash theme={null}
curl -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  https://api.mirador.org/v1/identity
```

```json theme={null}
{ "organization_id": "org_...", "project_id": "prj_..." }
```

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Create a server key and authenticate your requests
  </Card>

  <Card title="Endpoints" icon="list" href="/api/endpoints">
    Every endpoint, filter, and response shape
  </Card>

  <Card title="Exporting traces" icon="file-export" href="/api/trace-export">
    Pull a full trace + events into tickets and other systems
  </Card>
</CardGroup>