REST API v1

Read-only, programmatic access to your own analytics aggregates: dashboards of dashboards, internal reporting, spreadsheets. Everything the API returns is aggregate data your dashboard already shows; the privacy architecture (no cookies, no visitor identifiers, hour precision) holds by construction.

Authentication

Create an API key in Settings, then send it as a Bearer token. Keys are account-wide and stored hashed on our side; the full key is shown once, at creation.

curl -H "Authorization: Bearer $ILLUMINO_API_KEY" https://illumino.app/api/v1/sites

Session cookies are ignored on /api/v1 routes, and API keys are not accepted anywhere else. The API is served without CORS headers: call it from your servers, not from browsers, so your key never ships to a client.

Limits and errors

Behaviour	Detail
Methods	`GET` only. Anything else returns `405`.
Rate limit	60 requests per minute per key. Over the limit returns `429` with a `Retry-After` header.
Errors	JSON envelope: `{"error": "...", "status": 401}`. Codes: 400, 401, 403, 404, 405, 429.
Date range	`from` and `to` are UTC dates (`YYYY-MM-DD`), both inclusive. Default: the last 7 days. Max range: 365 days.
Row limits	List endpoints accept `limit` (default 20, max 100).

Endpoints

Endpoint	Returns
`GET /api/v1/sites`	The sites on your account: id, domain, created_at.
`GET /api/v1/sites/{id}/stats`	Pageviews, unique visitors, sessions, views per session for the range.
`GET /api/v1/sites/{id}/timeseries`	Pageviews over time. `interval=day` (default) or `hour`; hourly data exists for the last 7 days only (raw hits are deleted after 7 days by design).
`GET /api/v1/sites/{id}/pages`	Top pages by views.
`GET /api/v1/sites/{id}/referrers`	Top referrer domains (hostname only, never full URLs).
`GET /api/v1/sites/{id}/countries`	Top countries by views.
`GET /api/v1/sites/{id}/devices`	Views by device type (desktop, mobile, tablet).
`GET /api/v1/sites/{id}/events`	Custom event counts by event name.
`GET /api/v1/sites/{id}/entry-pages`	Top entry pages with entry counts.
`GET /api/v1/sites/{id}/exit-pages`	Top exit pages with exit counts.

Example: stats for a date range

curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
  "https://illumino.app/api/v1/sites/YOUR_SITE_ID/stats?from=2026-06-01&to=2026-06-30"

{
  "site_id": "YOUR_SITE_ID",
  "domain": "example.com",
  "from": "2026-06-01",
  "to": "2026-06-30",
  "pageviews": 48210,
  "visitors": 17904,
  "sessions": 21455,
  "views_per_session": 2.25
}

Example: daily timeseries

curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
  "https://illumino.app/api/v1/sites/YOUR_SITE_ID/timeseries?interval=day&from=2026-06-24&to=2026-06-30"

{
  "metric": "pageviews",
  "interval": "day",
  "from": "2026-06-24",
  "to": "2026-06-30",
  "points": [
    { "t": "2026-06-24", "value": 1650 },
    { "t": "2026-06-25", "value": 1721 }
  ]
}

Example: top pages

curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
  "https://illumino.app/api/v1/sites/YOUR_SITE_ID/pages?limit=5"

{
  "from": "2026-07-01",
  "to": "2026-07-07",
  "pages": [
    { "path": "/", "views": 4210 },
    { "path": "/pricing", "views": 1288 }
  ]
}

Stability

The API is versioned in the path. Within v1, changes are additive only: new endpoints and new response fields may appear; nothing is removed or renamed. A breaking change means a new /api/v2 namespace. When a version is ever deprecated, we will announce it on this page well ahead of any change; we do not promise specific support timelines.

Availability. The API ships with the Beacon plan and is available to all trial accounts while the trial is active.