HTTP API

Every route the server exposes, with authentication, parameters, filters and status codes.

All paths are relative to basePath (default /api). Dates are ISO 8601, or Unix milliseconds on the Query objects used in code. Time zones are IANA names and default to the site’s time zone. Intervals are hour, day, week or month.

Public routes

CORS is open and text/plain bodies are accepted, so the browser sends events without a preflight request.

Event body

The body is a TrackerPayload, compact on purpose, to keep the request small:

curl -X POST https://analytics.example.com/api/event \
  -H 'Content-Type: text/plain' \
  -d '{"w":"SITE_ID","t":"goal","u":"https://example.com/pricing","n":"signup","p":{"plan":"pro"}}'

Admin routes

Admin routes need a session cookie from POST /auth/login, or Authorization: Bearer <admin token>. Without one they answer 401.

Most of them also accept an API key as Authorization: Bearer anl_..., within the key’s scope and sites (see API keys). Every route a key may use is served under /v1 as well (/v1/sites/:id/overview), with identical behavior; the /v1 address is the stable one for scripts. GET /v1/openapi.json describes them for tools, see OpenAPI document.

Auth

Email

Preferences

Sites

| Method and path | Description | | –––––––––––––– | —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— | –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– | | GET /sites | List sites. | | GET /summary | Every site’s visitors, revenue and orders in from–to (ISO dates, default the last 24 hours) and who is online now, as SiteSummary[]. One request for the sites overview, however many sites there are. series=hour | dayaddstraffic(visitors) andsales(revenue) arrays with one point per bucket fromfrom; compare=1addsprevious, the totals of the window before. | | GET /my-ip | The address this request comes from as the server sees it: { ip }, or null when no trusted proxy header says. The dashboard’s “Add my current IP” uses it. | | GET /version | The running version and the newest release on npm: { current, latest }; latest is null when the server could not look it up or updateCheck is off. The server asks the registry at most every six hours. The dashboard uses it for its update notice. | | GET /sites/:id/favicon | The site’s stored icon; the first request for a site that has none reads the site (see POST /sites/:id/sync). An icon older than 30 days is returned at once and fetched again behind it. 404 when there is none; a site that could not be read is not asked again for an hour. | | POST /sites/:id/sync | Reads the site’s home page and returns what it found against what is stored: { reachable, tracker, changes }, each change { field, current, found, changed } for name, color and icon (a data: URL), and manual: true on a name that was typed by hand. tracker is found, not-found or unknown. Changes nothing. Generated test sites answer { skipped: "test-site" }. | | POST /sites/:id/sync/apply | Body { "fields": ["name", "color", "icon"] }. Reads the page again and takes over the listed fields it found; answers { site, applied }. 502 when the page cannot be read. | | POST /sites | Create a site. Only domain is required (a real domain such as example.com; localhost is rejected). Other fields: name, timezone, currency, privacyMode, retentionDays, allowLocalhost, ignoredIps (addresses or CIDR ranges), ignoreAdmins, vitalsSample (percent of page views, 0 to 100, that measure Core Web Vitals; 0 is off), targets (up to 20 of { goal, target, period }, period week, month or quarter), shareToken. Answers 201 with { site, apiKey }; the key is shown once. | | GET /sites/:id | One site. Secrets are never returned: webhooks says which providers have a secret, and shareToken is the current share token or null. | | PATCH /sites/:id | Change settings, including webhook secrets (webhookSecrets: { stripe: "..." }, null removes one) and the share link (shareToken: true creates a token, null turns sharing off). paused: true stops tracking until set back to false: tracker events and server goals are dropped (202 with filtered: "paused"), payments are still recorded. | | DELETE /sites/:id | Delete the site and its data. The body proves it is meant: { "confirm": "example.com", "password": "..." }, the site’s domain and the admin password. When admins sign in through verify() there is no password, and the domain alone is enough. A wrong domain answers 400; a wrong password 403, and it counts toward the login limit. | | POST /sites/:id/rotate-key | Issue a new site API key. The old one stops working. |

Statistics

All take from, to, interval, tz and filters. GET /sites/:id/realtime takes none of them.

overview, timeseries and breakdown also take compare=previous (the period of the same length just before) or compare=year (the same dates a year earlier). The comparison comes back in the same response: every TimeseriesPoint and BreakdownRow gets a previous object (the bucket at the same position, matched by index; the row’s numbers, all 0 when the value had no visits), and overview measures its changes against that period. Without compare nothing extra is read, and with it every one of these requests reads the data twice, so leave it off on a dashboard you keep open all day on a database that bills rows read.

Dimensions for breakdown: channel, source, referrer, campaign, medium, term, content, ref, page, entry, exit, country, region, city, browser, os, device, event, outbound, goal.

Every stats route also takes property filters, written prop:<key>=<value> (URL-encode the colon): they keep sessions with a goal event whose property equals the value, and when goal or event is also set, the same event has to match both. Keys use 1 to 64 letters, digits, _, . and -; other keys are ignored.

Lists

Sessions, events and payments answer one page at a time, newest first: { items, nextCursor, total }. total counts every match, not just this page.

Sort keys: sessions time duration pageviews source country entry revenue; events time type name page; payments time amount provider customer attribution. Sessions search pages, sources, channels, places, browsers, systems and visitor ids; events search names, paths and types; payments search ids, emails, names, customer, order and subscription ids and the provider.

Events also take name and type (pageview, goal, outbound, revenue, identify). Payments take kind (payment or refund), provider and attributed (true or false). An unknown sort, order or filter value answers 400, and so does a cursor combined with sort or offset.

curl -b cookies.txt \
  "https://analytics.example.com/api/sites/SITE_ID/payments?kind=refund&sort=amount&order=desc&offset=25&limit=25"

Filters

Filters use the dimension names as query keys: country=DE&channel=Organic%20Search&page=/pricing. Repeat a key to match any of several values.

curl -b cookies.txt \
  "https://analytics.example.com/api/sites/SITE_ID/breakdown?dimension=source&from=2026-10-01&to=2026-11-01&country=DE"

Share links

Admin routes, per site:

A request that carries a token, as ?share=TOKEN, an x-analytik-share: TOKEN header or Authorization: Bearer TOKEN, can read these GET routes without logging in: shared (the site’s name, domain, time zone and currency, and the link’s views), overview, timeseries, breakdown, properties, realtime, sessions, events, bots, and the funnel list and funnel results. A link limited to some views reads only the routes behind them; any other route answers 401, as does a token for another site, a revoked or an expired one. That is the aggregate numbers and the session list, including visitor ids, countries, cities, browsers, pages, referrers, and event names and properties. Payments, single-session details, the site settings, export and every write, including the share-link routes, stay admin only.

Only a token in the address is cached publicly (a header or bearer token is never): those answers carry Cache-Control: public, s-maxage=60 (10 seconds for realtime). Tokens are stored as SHA-256 hashes.

The older single token still works: PATCH /sites/:id with { "shareToken": true } returns a plain shareToken that opens every shareable route, uncached, until { "shareToken": null }. Prefer share links.

API keys

Created and managed by the signed-in admin only; a key can never read or change keys. Creating, rolling, enabling and deleting need password (the admin password) in the body unless admins sign in through verify(). A wrong password answers 403 and counts toward the sign-in limit (429 after 10 in 15 minutes). See the guide.

What a key may call:

• read: every GET of its sites that is a statistic or a list: /sites, /sites/:id, overview, timeseries, breakdown, properties, bots, vitals, journeys, retention, targets, realtime, sessions, sessions/:sid, events, event-log, funnels, payments, export, imports, shared, favicon, and /summary.
• write: all of the above plus PATCH /sites/:id, annotations (create, change, delete), funnels (create, delete), POST /sites/:id/rematch, POST /sites/:id/import and DELETE /sites/:id/imports/:source.
• Never: deleting a site, rotate-key, sync, share links, webhooks, deleting data, e-mail, preferences, defaults, debug, sign-in and the key routes above.

A key with an ipAllowlist answers 403 this key cannot be used from this address for any other address, and when the address is unknown; the check comes before scope and site and does not count toward the 30 unknown-key limit. A key limited to some sites answers 403 on others and sees only its sites in /sites and /summary. Errors: 401 (unusable key), 403 (not allowed, the message says why), 429 (limit). Each key may send 120 requests a minute and 12 a minute to journeys, retention, export, import and sessions?search=; answers carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 adds Retry-After. The limits and where they are counted (keyRateLimit.perMinute, heavy, store: 'database' | 'memory') are server options. Unknown keys are counted per address: 30 in 15 minutes, then 429. Answers to a key are never cached (Cache-Control: no-store).

Outgoing webhooks

Admin only; a share link cannot read or change them. See the guide.

Annotations

Notes are read with GET /sites/:id/timeseries: each point carries the notes dated in its bucket as notes: [{ id, ts, text, createdAt }], at most 100 for the range, left out when there are none.

Funnels

Maintenance

The purge deletes events, sessions, return-page claims and visitors left without sessions. Payments are kept so revenue numbers stay correct, but their email, name, customer id, visitor id and session id are cleared. See Retention.

Debug

Test data for trying the dashboard with many sites, long histories and large numbers. GET /debug always answers; the other routes answer 404 unless the server was created with debug: true.

Payments

POST /v1/payments and analytik.recordPayment() take a PaymentInput. Amounts are minor units. A refund has kind: "refund" and the positive amount. For a refund without an id of its own, send refundedTotal, the total refunded for the order so far, and the server records only the difference; a retried request adds nothing.

Revenue events from the tracker are stored as payments with the provider client and the id client:<orderId>. When a verified payment from a provider webhook or your server arrives for the same order, it replaces the client record instead of counting twice.