Overview

The REST API serves the numbers the MIRA FIVE dashboard shows: projects, the overview, people, raw events, goals, funnels and acquisition. Use it from scripts and servers, for example a nightly export or an internal report. It only reads. To let an AI agent read and set things up, use the MCP server instead.

Base URLCopy Anchor Link

https://app.mirafive.io/api/v1

Every endpoint answers GET and HEAD. Any other method gets 405 Method Not Allowed with Allow: GET, HEAD. Unknown query parameters are ignored.

AuthenticateCopy Anchor Link

Send a credential as a bearer token:

Authorization: Bearer mf_pat_…

Two kinds work:

Create an API key as described in Keys. The examples on these pages read it from MIRAFIVE_API_KEY.

A credential acts as its owner. It sees every project in every organization you belong to, and loses a project the moment you leave its organization. The REST API is read-only whatever the key's switches allow.

Make a first requestCopy Anchor Link

curl https://app.mirafive.io/api/v1/projects \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY"

{
  "data": [
    {
      "id": "01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f",
      "type": "projects",
      "attributes": {
        "name": "Nordlicht Shop",
        "slug": "nordlicht-shop",
        "timezone": "Europe/Berlin",
        "reportingCurrency": "EUR",
        "archived": false,
        "createdAt": "2025-11-04T09:12:44.318+01:00",
        "organization": {
          "id": "01932c4d-1f2e-7a3b-8c4d-5e6f7a8b9c0d",
          "slug": "nordlicht",
          "name": "Nordlicht GmbH"
        },
        "plan": "pro",
        "retentionDays": 366
      },
      "links": {
        "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f"
      }
    }
  ],
  "links": {
    "self": "https://app.mirafive.io/api/v1/projects",
    "next": null
  },
  "meta": {
    "perPage": 50,
    "nextCursor": null
  }
}

Every other endpoint sits under a project: /api/v1/projects/{project_id}/…. The project_id is the id from this list, a UUID. A slug gets 404.

Response formatCopy Anchor Link

Successful answers are JSON:API documents with Content-Type: application/vnd.api+json, whatever Accept header you send. URLs and names are written unescaped (no \/).

• data holds one resource object, or a list of them. Each has id, type, attributes and, where it has an address, links.self.
• meta holds what the answer is about: the period it read, the page size, totals.
• Lists that page have top-level links (self, next). See Pagination.
• There are no relationships and no include.

Sparse fieldsetsCopy Anchor Link

Ask for only some attributes with fields[<type>], a comma-separated list:

curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'fields[projects]=name,timezone'

{
  "data": {
    "id": "01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f",
    "type": "projects",
    "attributes": { "name": "Nordlicht Shop", "timezone": "Europe/Berlin" },
    "links": { "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f" }
  }
}

TimestampsCopy Anchor Link

Moments (createdAt, firstSeen, occurredAt, …) are ISO 8601 with milliseconds, in the project's timezone with its offset: 2026-09-23T13:55:00.000+02:00. The bounds in meta.period and the start of each trend bucket (t) are ISO 8601 without milliseconds: 2026-09-28T00:00:00+02:00.

Money and ratiosCopy Anchor Link

Amounts stay per currency and are never added across currencies: [{ "currency": "EUR", "amount": 49 }, { "currency": "CHF", "amount": 25 }]. Ratios such as rate, conversion, coverage and ctr are between 0 and 1.

PeriodsCopy Anchor Link

Reports read a period. Pass a preset, or period=custom with two days.

A preset ends with the current minute, hour, day or month and includes it: 7d on 27 September is 21 to 27 September, today included. Days and months are cut in the project's timezone.

Rules for a custom range:

• to must be on or after from.
• from after today (in the project's timezone) is refused. A to after today reads up to today.
• The plan keeps a limited history (retentionDays on the project). A range that starts before it starts at the first day the plan keeps instead, and meta.period.clampedToRetention is true. A range that ends before it is refused, for example with to is before 2025-09-26, the first day the plan keeps.

Trends are bucketed by the period:

Every report says which window it read in meta.period:

"period": {
  "preset": "30d",
  "from": "2026-08-29T00:00:00+02:00",
  "to": "2026-09-28T00:00:00+02:00",
  "timezone": "Europe/Berlin",
  "interval": "day",
  "comparison": null,
  "clampedToRetention": false
}

to is exclusive. comparison holds the from and to of the previous window when the answer compares, else null.

Compare with the previous periodCopy Anchor Link

compare=previous adds the window before it, of the same length. Only three endpoints take it: the overview, a goal report and search. Everywhere else it is refused with This endpoint does not compare periods. Leave out compare.

The overview's key numbers and the search summary carry the previous values even without compare. A previous window that starts before the history the plan keeps, or before the project's first event, is left out: comparison is then null.

FiltersCopy Anchor Link

The overview, events and channels endpoints narrow their events with filters. Each filter is three query parameters with the same index. All filters must hold (AND). At most 20.

filters[0][field]=page_path&filters[0][op]=starts_with&filters[0][value]=/products

With curl, let -G and --data-urlencode encode the brackets:

curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/overview \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=7d' \
  --data-urlencode 'filters[0][field]=channel' \
  --data-urlencode 'filters[0][op]=is' \
  --data-urlencode 'filters[0][value]=organic_search' \
  --data-urlencode 'filters[1][field]=country' \
  --data-urlencode 'filters[1][op]=is' \
  --data-urlencode 'filters[1][value]=DE'

field is at most 150 characters, op 20, value 1,000. The People list has its own filters on people.

FieldsCopy Anchor Link

"text" means every operator except gt and lt. "closed set" means is, is_not, set and not_set.

channel is the channel of the visit the event belongs to. A visit collected without consent keeps only its first page, so under a channel filter it counts by that page. A project that collects only without consent refuses a channel filter: This project collects without consent, so it is not filtered by channel.

OperatorsCopy Anchor Link

PaginationCopy Anchor Link

Lists of projects, people and events come 50 at a time and page by cursor. There is no page number and no page size parameter.

"links": {
  "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events",
  "next": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events?cursor=eyJhdCI6IjIwMjYtMDktMjcgMDg6MTQ6MDIuNTEyIn0"
},
"meta": {
  "perPage": 50,
  "nextCursor": "eyJhdCI6IjIwMjYtMDktMjcgMDg6MTQ6MDIuNTEyIn0"
}

Follow links.next until it is null, or pass meta.nextCursor as cursor with the same other parameters. A cursor the list did not hand out gets 422 with The cursor is not one this list handed out; follow links.next.

Rate limitsCopy Anchor Link

Each person has 120 requests per minute, shared by all their API keys and tokens. The MCP server has a budget of its own. Every answer carries the budget:

RateLimit-Policy: "api";q=120;w=60
RateLimit: "api";r=117;t=42

r is the requests left, t the seconds until the window resets. Past the limit the answer is 429 with Retry-After and The limit is 120 requests per minute. Try again in 42 seconds.

Refused tokens are limited too: 60 per minute from one network. Past that, a bad token gets 429 with Too many refused tokens came from this network. Try again in N seconds. A valid token from the same network still gets through.

Browsers and CORSCopy Anchor Link

The API sends no CORS headers, so a page in a browser cannot read it from another origin. Call it from a server or a script.

Every answer carries X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin and Content-Security-Policy: default-src 'none'; frame-ancestors 'none'.

Audit trailCopy Anchor Link

Every call is recorded under API & MCP in MIRA FIVE as recent access: the key or app, the endpoint, the project and how the call ended. Query parameters are never stored, since they can name people. A call with a revoked or expired key is recorded against its owner, so a leaked key shows up there.

EndpointsCopy Anchor Link

There is no OpenAPI document. Errors are listed in Errors.