Skip to main content
Every /v1/* endpoint requires a server API key (prefix mir_srv_). Keys are scoped to a single project — a request only ever sees data from the project its key belongs to.

​
Server keys vs. other keys

Mirador uses different keys for different surfaces. Use the right one:
Web and ingest keys are rejected by the REST API. If you get a 401 with UNAUTHENTICATED or a 403 with PERMISSION_DENIED, confirm you’re using a mir_srv_* server key and not a mir_web_* web key or an SDK/ingest key.

​
What a server key can do

A server key grants read access to every trace, log, and metric in its project — and it can also create, replace, and delete dashboards and metric alerts via conditional PUT/DELETE. It is not read-only. Treat it like a password, and if you hand one to an automation or AI agent, constrain the integration to GET unless you explicitly want it managing dashboards or alerts.

​
Creating a server key

Create a server key in the Mirador dashboard under your project’s API keys.

​
Sending the key

Pass the key on every request using either header (Authorization: Bearer is preferred):
Verify a key resolves correctly before doing real work:

​
Rate limits

Rate limits are enforced per client IP, not per key — roughly 60 requests per second with a burst near 120. Parallel workers behind one egress address share that budget, so serialize page walks instead of fanning out. A 429 response carries a Retry-After header; sleep that many seconds, then retry.

​
Public endpoints

The documentation endpoints do not require a key:
  • GET /docs — Swagger UI
  • GET /openapi.yaml, GET /openapi.json — the OpenAPI contract
  • GET /llms.txt — the agent-facing brief
  • GET /health — liveness check

​
Keeping keys safe

  • Store keys in environment variables or a secrets manager — never in source control, URLs, or logs.
  • Use a separate key per integration so you can rotate or revoke one without affecting others.
  • Scope keys to the project they need; a key cannot read across projects.
  • Rotate keys periodically and on staff changes.

​
Next Steps

Endpoints & Conventions

Parameter map, time windows, pagination, filters, errors

Traces

Filter traces and read event timelines