Skip to main content
The Mirador REST API is one HTTP API over everything a project observes: traces, OpenTelemetry logs, PromQL metrics, and dashboards. It’s the companion to the ingest surfaces — the SDKs and OTLP endpoints write telemetry, the REST API reads it back — from a backend service, a CI job, an incident bot, or an AI agent. Dashboards and metric alerts can also be managed through it, with safe conditional writes. 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.
  • Count, slice, and read logs — exact bucketed stats, filtered records, or a live SSE tail.
  • Evaluate PromQL against your metrics, or discover what metrics exist at all.
  • Correlate a trace with the logs it produced via trace_id.
  • Manage dashboards and metric alerts as code, guarded by ETags so writers can’t clobber each other.
  • Let an AI agent investigate your project with a server key and a typed contract.
Queries are all GET. The only mutations are PUT/DELETE on dashboards and metric alerts — and every mutation requires a conditional header, so nothing is overwritten by accident. To ingest traces, logs, and metrics, use the SDKs and OTLP endpoints; ingestion and the REST API use different keys — see Authentication.

​
Base URL

All data endpoints live under /v1/* and require a server API key (mir_srv_*). Responses are 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.

Swagger UI

Interactive, try-it-in-the-browser docs for every endpoint. Best starting point for a human exploring the API.

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.

OpenAPI (YAML)

The full machine-readable contract. Feed it to a code generator or API client.

OpenAPI (JSON)

The same contract in JSON, for tooling that prefers it.
Wiring up an AI agent or assistant? Give it the contents of 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 safe agent workflows — enough for an agent to query Mirador with no other context.

​
What you can call

See Endpoints & Conventions for the full parameter map, time syntax, pagination, filter grammar, and error codes.

​
A first request

Always start with /v1/identity — it confirms the key works and tells you exactly which project you’re scoped to:
A key sees exactly one project; no query parameter can widen its scope.

​
Next Steps

Authentication

Create a server key and authenticate your requests

Endpoints & Conventions

Parameter map, time windows, pagination, filters, errors

Traces

Filter traces and read event timelines

Logs

Stats, records, and the live SSE stream

Metrics

Discover metrics and evaluate PromQL

Exporting traces

Pull a full trace + events into tickets and other systems