` header is required; without a valid key every request answers `401 unauthorized`. Requests share the REST API’s read budget of 120 requests per minute per key, so a busy agent can hit `429 rate_limited` with a `Retry-After` header. See [Keys](/docs/keys/) for how live and read-only keys relate.
The server is stateless: no session ids, no server-side conversation state, one self-contained JSON-RPC exchange per request.
## Tools
[Section titled “Tools”](#tools)
Stats tools take `window` (`24h`, `7d`, `30d`, `90d`; default `7d`) and `includeBots` (default `false`, bots excluded).
| Tool | Arguments | Returns |
| --------------------- | ---------------------------------- | ------------------------------------------------ |
| `get_project` | none | Name, trusted domains, retention, caps |
| `get_overview` | window, includeBots | Visitors, pageviews, bounce rate, visit duration |
| `get_timeseries` | window, includeBots | Visitors and pageviews over time |
| `get_top_pages` | window, includeBots | Most-visited paths |
| `get_traffic_sources` | window, includeBots | Search, social, direct, referral breakdown |
| `get_countries` | window, includeBots | Visitors by country |
| `get_devices` | window, includeBots | Browser, OS, device-type breakdowns |
| `get_utm` | window, includeBots | Campaign performance by UTM parameters |
| `get_custom_events` | window, includeBots | Counts per custom event name |
| `get_goals` | window, includeBots | Goal conversions and rates |
| `get_realtime` | none | Visitors active in the last 5 minutes |
| `get_recent_sessions` | window, includeBots, limit, offset | Paginated session list, newest first |
| `get_session` | sessionId | Full event trail of one session |
Results come back as JSON in the tool’s text content, in the same shapes as the [REST API](/docs/api/rest/) responses.
## Raw protocol example
[Section titled “Raw protocol example”](#raw-protocol-example)
The endpoint is plain JSON-RPC 2.0 over HTTP POST, so it is easy to probe without a client:
```bash
curl https://api.analytics.canarycoders.es/mcp \
-H "Authorization: Bearer cly_read_..." \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_overview","arguments":{"window":"30d"}}}'
```
## Related
[Section titled “Related”](#related)
[REST API](/docs/api/rest/)The /v1 endpoints these tools wrap.
[Keys](/docs/keys/)Live vs read-only keys, rotation, and what each may do.
# REST API
> The CanaryLytics /v1 REST API exposes every stat the dashboard shows, over Bearer-authed JSON endpoints for stats, sessions, exports, custom events and setup validation.
The `/v1` REST API at `https://api.analytics.canarycoders.es` exposes every stat the dashboard shows, over Bearer-authed JSON endpoints. Every route is scoped to the project that owns the key. There is no cross-project read path.
## Endpoints at a glance
[Section titled “Endpoints at a glance”](#endpoints-at-a-glance)
| Method & path | Key required | Returns |
| ---------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
| `POST /v1/projects` | invite code (no key) | New project + plaintext key, shown once |
| `GET /v1/project` | live or read | Project info (`ProjectInfo`) |
| `GET /v1/validate` | live or read | Dry-run of the ingest acceptance rules |
| `GET /v1/stats/*` | live or read | Overview, timeseries, pages, sources, countries, regions, events, UTM, devices, goals, realtime |
| `GET /v1/sessions` · `/:sessionId` | live or read | Paginated session list, session detail |
| `GET /v1/export` | live or read | Cursor-paginated raw event dump (CSV/NDJSON) |
| `POST /v1/events` | **live only** | `202`, records a server-side custom event |
## Authentication
[Section titled “Authentication”](#authentication)
```plaintext
Authorization: Bearer cly_live_5f3a9c2e1b7d4a80f6c3e9d2a1b4c7e0
```
A `cly_live_…` key authorizes every endpoint. A `cly_read_…` key authorizes everything **except** `POST /v1/events`, which answers `403 read_only_key`. `POST /v1/projects` is the only unauthenticated route. See [provisioning](#provisioning).
Errors are always `{ "error": { "code": "...", "message": "..." } }`, with the HTTP status carrying the usual meaning (`400`, `401`, `403`, `404`, `429`).
## Rate limit
[Section titled “Rate limit”](#rate-limit)
120 requests/minute per key, fixed 60-second window. Over the limit you get `429 rate_limited` with a `Retry-After` header (seconds until the window resets).
## CORS
[Section titled “CORS”](#cors)
`/v1` responses reflect `Access-Control-Allow-Origin` only when the request’s `Origin` matches the authenticated project’s trusted domains, the dashboard origin, or a localhost-ish origin while the project’s “Allow local origins” toggle is on. Server-to-server calls (no `Origin` header) skip this check entirely. It only matters for browser callers such as the widget or an SDK client running in a browser.
An untrusted browser `Origin` is **not** a `403`: the request succeeds, but the response omits `Access-Control-Allow-Origin`, so the browser refuses to hand your script the body. This is why a call can work in `curl` (and any server-side caller) yet fail in the browser. Add the page’s domain to the project’s trusted domains to fix it.
## Provisioning
[Section titled “Provisioning”](#provisioning)
```plaintext
POST /v1/projects
```
The one unauthenticated route. It is gated by an invite code instead of a key, since no key exists yet.
```bash
curl https://api.analytics.canarycoders.es/v1/projects \
-H "Content-Type: application/json" \
-d '{"inviteCode":"...","name":"My App","domains":["myapp.com"]}'
```
Returns `201` with `{ apiKey, project }`, where `apiKey` is the plaintext key, shown exactly once. `403 invalid_invite_code` on a bad invite; `400 bad_request` on a malformed body or invalid domain list; `409 conflict` if a domain is already claimed by another project.
## Project
[Section titled “Project”](#project)
```plaintext
GET /v1/project
```
Returns `ProjectInfo`: `id`, `name`, `keyPrefix`, `domains`, `retentionDays`, `dailyEventCap`, `createdAt`, `readKeyPrefix` (`null` if none minted), `allowLocalOrigins`.
## Validate
[Section titled “Validate”](#validate)
```plaintext
GET /v1/validate?domain=myapp.com&origin=https://myapp.com
```
Dry-runs the `/ingest` acceptance rules for the authenticated project. See the [troubleshooting guide](/docs/troubleshooting/#walking-through-v1validate) for a field-by-field walkthrough.
## Stats
[Section titled “Stats”](#stats)
All `GET /v1/stats/*` routes take `?window=24h|7d|30d|90d` (default `7d`) and, except `realtime`, `?includeBots=true|1` (default `false`):
```plaintext
GET /v1/stats/overview GET /v1/stats/timeseries
GET /v1/stats/pages GET /v1/stats/sources
GET /v1/stats/countries GET /v1/stats/regions?country=ES (country is required)
GET /v1/stats/events GET /v1/stats/utm
GET /v1/stats/devices GET /v1/stats/goals
GET /v1/stats/realtime
```
```bash
curl "https://api.analytics.canarycoders.es/v1/stats/overview?window=30d" \
-H "Authorization: Bearer cly_read_a1b2c3d4e5f60718293a4b5c6d7e8f90"
```
`/v1/stats/realtime` is the odd one out: it returns `{ activeSessions }`, meaning distinct non-bot sessions with at least one event in the last 5 minutes, and it ignores `window` entirely. Bots are always excluded (a crawler is never a “current visitor”), which is why it has no `includeBots` toggle.
These are thin wrappers over the same query layer the dashboard uses, so numbers can never drift between the widget/SDK and the dashboard UI.
## Sessions
[Section titled “Sessions”](#sessions)
```plaintext
GET /v1/sessions?window=7d&limit=50&offset=0&country=ES®ionCode=ES-MD&includeBots=false
GET /v1/sessions/:sessionId
```
`limit` is 1–200 (default 50); the list response includes `hasMore`. The detail route 404s (`not_found`) if the session has no recorded events.
## Export
[Section titled “Export”](#export)
```plaintext
GET /v1/export?window=7d&format=csv&limit=1000&cursor=...
```
A cursor-paginated raw event dump. `format` is `csv` (default) or `ndjson`; `limit` is 1–10000 (default 1000). The response body **is** the page of data. A next-page cursor arrives in the `X-Next-Cursor` response header, present only when the page filled up completely (an exactly-full last page costs one extra empty request to confirm there is nothing more).
```bash
curl "https://api.analytics.canarycoders.es/v1/export?window=7d&format=ndjson&limit=5000" \
-H "Authorization: Bearer cly_read_a1b2c3d4e5f60718293a4b5c6d7e8f90" \
-D - -o events.ndjson
```
Both formats emit the same columns, in a fixed order: `id, createdAt, sessionId, eventType, eventName, props, path, referrerPath, targetPath, country, region, regionCode, city, asn, asOrganization, browser, os, deviceType, isBot, botName, isVpn, locale, trafficSource, utmSource, utmMedium, utmCampaign, userAgent`.
## Track a custom event
[Section titled “Track a custom event”](#track-a-custom-event)
```plaintext
POST /v1/events
```
Full key only. Read keys get `403 read_only_key`.
```bash
curl https://api.analytics.canarycoders.es/v1/events \
-H "Authorization: Bearer cly_live_5f3a9c2e1b7d4a80f6c3e9d2a1b4c7e0" \
-H "Content-Type: application/json" \
-d '{"name":"signup","props":{"plan":"pro"},"path":"/onboarding"}'
```
`202 { "accepted": true }`, or `429 daily_cap_exceeded` if the project’s daily event cap is reached. See [Custom events, goals & UTM tracking](/docs/tracking/events-and-goals/) for the field constraints.
Tip
Prefer a typed client over raw `curl`? The [SDK](/docs/api/sdk/) wraps every one of these routes with request building, auth headers, and typed responses.
## Related
[Section titled “Related”](#related)
[SDK](/docs/api/sdk/)The typed @canarylytics/sdk client for these endpoints.
[MCP server](/docs/api/mcp/)The same stats as MCP tools for any MCP-capable agent.
[Keys & security](/docs/keys/)Which key to use where: live vs read-only.
# SDK
> @canarylytics/sdk is a typed, isomorphic client for the CanaryLytics REST API. It runs in browsers, Node, Workers and Electron, with optional React hooks for polling.
`@canarylytics/sdk` is a typed, isomorphic client for the [REST API](/docs/api/rest/). It only needs a global `fetch`, so it runs unmodified in browsers, Node ≥ 18, Cloudflare Workers, and an Electron main process. Every wire type ships in the package itself (`ProjectInfo`, `StatsOverview`, `SessionDetail`, …), so responses are fully typed.
```bash
npm install @canarylytics/sdk
```
## Create a client
[Section titled “Create a client”](#create-a-client)
```ts
import { createClient } from "@canarylytics/sdk";
const lytics = createClient({
apiKey: process.env.CANARYLYTICS_KEY!, // cly_live_… or cly_read_…
baseUrl: "https://api.analytics.canarycoders.es", // optional, this is the default
});
```
`createClient` throws immediately if `apiKey` is missing, and again at call time if no global `fetch` is available and you didn’t pass one via `config.fetch`.
## Call the API
[Section titled “Call the API”](#call-the-api)
Every method maps one-to-one onto a REST endpoint:
```ts
await lytics.project.info();
await lytics.stats.overview({ window: "7d" });
await lytics.stats.timeseries({ window: "30d" });
await lytics.stats.pages({ window: "7d" });
await lytics.stats.sources({ window: "7d" });
await lytics.stats.countries({ window: "7d" });
await lytics.stats.regions({ window: "7d", country: "ES" });
await lytics.stats.events({ window: "7d" });
await lytics.stats.utm({ window: "7d" });
await lytics.stats.devices({ window: "7d" });
await lytics.stats.goals({ window: "7d" });
await lytics.stats.realtime();
await lytics.sessions.list({ window: "24h", limit: 50 });
await lytics.sessions.get(sessionId); // null on 404, doesn't throw
await lytics.validate({ domain: "myapp.com", origin: "https://myapp.com" });
await lytics.exportEvents({ window: "7d", format: "ndjson" });
await lytics.events.track("signup", { plan: "pro" }, { path: "/onboarding" });
```
## Handle errors
[Section titled “Handle errors”](#handle-errors)
Every non-2xx response throws a typed `LyticsApiError`:
```ts
import { LyticsApiError } from "@canarylytics/sdk";
try {
await lytics.events.track("signup");
} catch (err) {
if (err instanceof LyticsApiError) {
// err.status (e.g. 403), err.code (e.g. "read_only_key"), err.message
// 401 → code "unauthorized", message
// "A valid API key is required (Authorization: Bearer cly_live_…)"
}
}
```
## Provision a project
[Section titled “Provision a project”](#provision-a-project)
Creating a project happens before any key exists, so it is a standalone function rather than a client method:
```ts
import { provisionProject } from "@canarylytics/sdk";
const { apiKey, project } = await provisionProject("https://api.analytics.canarycoders.es", {
inviteCode: "...",
name: "My App",
domains: ["myapp.com"],
});
```
## React hooks
[Section titled “React hooks”](#react-hooks)
```bash
npm install @canarylytics/sdk react
```
```tsx
import { useLyticsClient, useOverview, useRealtime } from "@canarylytics/sdk/react";
function Dashboard() {
const client = useLyticsClient({ apiKey: readOnlyKey });
const overview = useOverview(client, { window: "7d", refreshInterval: 5000 });
const live = useRealtime(client, { refreshInterval: 2000 });
if (overview.isLoading) return Loading…
;
if (overview.error) return {overview.error.message}
;
return {overview.data?.totals.sessions} sessions · {live.data?.activeSessions} live
;
}
```
Every hook (`useOverview`, `useTimeseries`, `useTopPages`, `useSources`, `useCountries`, `useCustomEvents`, `useUtm`, `useDevices`, `useGoals`, `useRealtime`, `useSessions`) returns `{ data, error, isLoading, refresh }` and accepts the matching stats query plus `refreshInterval` (milliseconds; omit or pass `0` to fetch once). Polling pauses while the tab is hidden and refetches immediately when it becomes visible again, so data doesn’t go stale in a backgrounded tab.
`react >= 18` is an optional peer dependency, needed only if you import from the `/react` subpath.
Note
Import from `"@canarylytics/sdk"` for the core client and `"@canarylytics/sdk/react"` for the hooks. They are separate entry points, so a non-React consumer such as a server script or an Electron main process doesn’t need React installed at all.
## Related
[Section titled “Related”](#related)
[REST API](/docs/api/rest/)The endpoints behind every SDK method.
[Custom events & goals](/docs/tracking/events-and-goals/)Track conversions with events.track().
# Capacitor & Ionic
> Capacitor and Ionic apps load from capacitor://localhost, so CanaryLytics needs the project's "Allow local origins" toggle enabled. data-domain stays your real domain.
Capacitor and Ionic apps load the web view from `capacitor://localhost` (or `ionic://localhost` on older setups). In both cases the page’s **hostname is literally `localhost`**, even though this is a production app on someone’s phone rather than a dev server.
Enable the project’s **“Allow local origins”** toggle (dashboard → Settings) so ingest and the widget/SDK’s CORS layer accept it. The toggle covers `localhost`, `127.0.0.1`, and `*.localhost` origins for the project.
```html
```
`data-domain` should still be your real production domain (or whatever value you want events grouped under). The toggle is about which *Origin* is trusted, not what domain the snippet reports.
This toggle is shared with dev
“Allow local origins” also governs plain `localhost` development traffic on this project (see [Localhost & development](/docs/environments/localhost/)). Turning it off to “clean up” dev noise will also silently stop ingestion from every Capacitor/Ionic install of this app. The two use cases share the same hostname and can’t be told apart at the Origin-check level.
## Related
[Section titled “Related”](#related)
[Localhost & development](/docs/environments/localhost/)The other use case behind the same toggle.
[Electron](/docs/environments/electron/)The desktop equivalent, using custom protocol schemes instead.
# Electron
> Track an Electron app with CanaryLytics. Remote URLs work as-is; bundled apps need a custom protocol scheme, because file:// origins can never be trusted.
Electron apps track like websites as long as the page has a real origin. A `BrowserWindow` loading a remote URL needs nothing special; a bundled app needs a custom protocol scheme, because `file://` pages have no origin to trust.
## Loading a remote URL
[Section titled “Loading a remote URL”](#loading-a-remote-url)
If your `BrowserWindow` loads a real `https://` URL (for example `win.loadURL("https://myapp.com")`), it works exactly like a normal web page. The page’s origin is `https://myapp.com`, which just needs to be a trusted domain like any other site. Nothing Electron-specific to configure.
## Bundled apps
[Section titled “Bundled apps”](#bundled-apps)
Never load via file://
Don’t `win.loadFile("index.html")` and expect tracking to work. A `file://` page’s origin is the opaque string `"null"`, which can never match a trusted domain, so every event is dropped by design. This isn’t a bug to work around; `file://` origins are unsupportable for a domain-locked ingest model.
Instead, register a **standard, secure custom protocol scheme** before the app is ready, and load your bundled app through it:
main.js
```js
const { app, protocol, BrowserWindow } = require("electron");
protocol.registerSchemesAsPrivileged([
{
scheme: "app",
privileges: {
standard: true,
secure: true,
supportFetchAPI: true,
corsEnabled: true,
},
},
]);
app.whenReady().then(() => {
// ... register a protocol.handle("app", ...) that serves your bundled files ...
const win = new BrowserWindow({ /* ... */ });
win.loadURL("app://myapp/index.html");
});
```
A page served over `app://myapp/...` has a real, non-opaque origin: `app://myapp`. Add `myapp` as a trusted domain in the dashboard (single-label domains, like `localhost`, are allowed) and point the snippet at it:
```html
```
With that in place, `/ingest`, the widget, and the browser SDK all work exactly as they would on the web.
## Tracking from the main process
[Section titled “Tracking from the main process”](#tracking-from-the-main-process)
The [`@canarylytics/sdk`](/docs/api/sdk/) client is isomorphic, so in Electron’s main process it behaves like any Node server calling `/v1`. There is no `Origin` header and no CORS check there (that only applies to browser reads), just a Bearer-authed request:
main.js
```ts
import { createClient } from "@canarylytics/sdk";
const lytics = createClient({ apiKey: process.env.CANARYLYTICS_KEY });
await lytics.events.track("app_launched", { version: app.getVersion() });
```
## Related
[Section titled “Related”](#related)
[Capacitor & Ionic](/docs/environments/capacitor/)The mobile-hybrid equivalent of this page.
[Custom events & goals](/docs/tracking/events-and-goals/)Server-side event constraints for main-process tracking.
# Framework integrations
> Where to put the CanaryLytics script tag in plain HTML, Vite, Next.js App Router, Astro and TanStack Start, plus the pre-init fallback for async script injection.
The snippet is a single `
```
* Vite SPA
Add it directly to `index.html`. Vite serves that as static HTML, so the tag reaches the browser unmodified:
index.html
```html
```
* Next.js (App Router)
app/layout.tsx
```tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}