SiteBeacon API

Send cookieless analytics events from your servers and read your sites' statistics as JSON.

Pointing an AI agent at this API?

Hand it the LLM-ready Markdown version — self-contained instructions an agent can follow with just a URL and an API key.

Open /docs/llm/api.md

Getting started

Base URL

All endpoints live under `https://www.sitebeacon.eu/api/v1`. `https://www.sitebeacon.eu` is the origin you were given (scheme + host, e.g. `https://example.com`). Do not add a trailing slash.

Authentication

Endpoints marked "Bearer token" require a personal API key sent as a Bearer token: `Authorization: Bearer sk_your_key_here`. Keys always start with `sk_`. A missing or invalid key returns `401 { "error": "Invalid or missing API key" }`. Create keys in the app under Settings → API Keys. `POST /api/v1/collect` takes a site secret (`ssk_…`) instead, and the browser ingest `POST /api/event` is open.

Two kinds of keys

Reading statistics (`/api/v1/sites…`) uses your personal API key (`sk_…`, Settings → API Keys). Sending events from a server (`POST /api/v1/collect`) uses the SITE secret (`ssk_…`) shown when the site is created (Site → Settings → Install → Server; it can be rotated there). A site secret can only write events for its one site — it can read nothing — so it is safe to deploy on a web server.

Privacy model

No cookies, no client storage. A visitor is identified by a hash of (daily-rotating salt, site, IP, User-Agent); the salt is deleted after its UTC day and the IP is never stored. Visits (sessions) end after 30 minutes of inactivity. Send the end-user's real IP and User-Agent with server events so visitors and sessions are counted correctly.

Periods and filters

Stats endpoints take `period` = `today` | `24h` | `7d` | `30d` (default) | `90d` | `12mo`, evaluated in the site's time zone, and optional filters `page`, `host` (hostname — for sites with aliases or wildcard subdomains), `source`, `country` (ISO-3166 alpha-2), `browser`, `os`, `device` (`desktop`|`mobile`|`tablet`), `campaign` (utm_campaign) and `event` (keeps whole visits that fired that event — a goal filter). Use the value `(none)` to select rows where a dimension is unknown. Instead of `period` you may pass a custom range `from` + `to` (inclusive calendar days `YYYY-MM-DD` in the site's time zone, at most 731 days; `period` is then reported as `custom`) on /stats, /breakdown, /vitals and /dashboard.

Integrator keys & permissions

Platforms that manage sites for their own customers (e.g. a CDN) use an INTEGRATOR key: minted by the server operator through `POST /api/v1/admin/keys` (scope `created_by_key`). An integrator key sees ONLY the sites it created itself — every other site, and every non-site endpoint, answers `404` as if it did not exist. A key may be limited to a subset of the permissions `sites` (create/list/update/delete/share/members), `stats` (stats, breakdown, realtime, vitals, dashboard), `ingest` (snippet, secret rotation) and `embed` (embed tokens); a call outside them answers `403`. Personal keys have every permission.

Content type

Responses are JSON unless noted (file download returns raw bytes). Request bodies are JSON (`Content-Type: application/json`) except file upload, which is `multipart/form-data`.

Rate limiting

Requests are rate limited per API key. When you exceed a limit you get `429` (or `403` if the limit is configured to block) with an `error` message and, when applicable, a `Retry-After` header (seconds). Back off and retry.

Errors

Errors are JSON with an `error` string and a matching HTTP status (`400` bad input, `401` unauthenticated, `403` forbidden, `404` not found, `413` payload too large, `429` rate limited, `500` server error). Every endpoint that takes a body caps its size and answers `413` before parsing an oversized one (JSON bodies: 64 KB unless stated otherwise).

Your base URL is https://www.sitebeacon.eu. Create API keys under Profile → API Keys.

Integrating as a platform (FluxWall)

  1. Operator, once: set `ADMIN_API_KEY_HASH` to the bcrypt hash of an `sk_…` token you generate (unset = the admin API does not exist, 404). Also set `TRUSTED_PROXY_SECRETS` (comma-separated, each ≥ 16 chars, one per proxy) and `EMBED_TOKEN_SECRET` (≥ 16 chars).
  2. Mint an integrator key: `POST https://www.sitebeacon.eu/api/v1/admin/keys` with the admin token and `{ "name": "FluxWall", "scope": "created_by_key", "permissions": ["sites","stats","ingest","embed"] }`. The response `key` is shown once. Everything below uses this key.
  3. Per customer zone: `POST https://www.sitebeacon.eu/api/v1/sites` with `{ "domain": "customer.example", "externalOwner": "fw:<userId>", "externalRef": "fw:<zoneId>", "base": "https://customer.example/_sb" }`. It is idempotent by `externalRef` (per integrator key), so retry freely; two customers with the same domain never collide. Keep the returned `secret` if you will use server ingest.
  4. Serve the tracker first-party: proxy `{base}/a.js` → `https://www.sitebeacon.eu/a.js` and `{base}/api/event` → `https://www.sitebeacon.eu/api/event` (POST + OPTIONS, body passed through as-is). Install the snippet from `GET /api/v1/sites/:id/snippet?base=https://customer.example/_sb`: `<script defer data-site="st_…" data-api="https://customer.example/_sb/api/event" src="https://customer.example/_sb/a.js"></script>`.
  5. On every proxied `/api/event` request add `x-sitebeacon-proxy: <one of TRUSTED_PROXY_SECRETS>`, `X-Forwarded-For: <visitor IP>` (first entry = visitor) and, if known, `x-country-code: <ISO-3166 alpha-2>`. Without a valid `x-sitebeacon-proxy` those headers are ignored and the address of the connecting hop is used — every visitor would look like your proxy. Pass the visitor's User-Agent unchanged.
  6. No-JS sites: report page views from the edge with `POST /api/v1/collect` (site secret) including `ip`, `userAgent` and a random `pageviewKey`, then `{ "name": "engage", "pageviewKey": "…", "engagedMs": 12000 }` for time on page.
  7. Read stats with `/api/v1/sites/:id/dashboard` (one call), `/stats`, `/breakdown`, `/realtime` and `/vitals`; list your sites with `GET /api/v1/sites?externalOwner=fw:<userId>`.
  8. Embed the dashboard: `POST /api/v1/sites/:id/embed-tokens` `{ "allowedOrigins": ["https://app.fluxwall.example"], "ttlSeconds": 3600 }` and frame the returned `url` (add `?snwflk=1&instanceId=<id>` to speak the snwflk 1.0 widget protocol: `ready` → `init` { context.theme.mode, config.period } → `resize` / `emit` { type: "sitebeacon.period", data.period }).
  9. Offboarding: `DELETE /api/v1/sites/:id` per zone; `DELETE /api/v1/admin/keys/:id` revokes the integrator key (its embed links stop working at once).

Endpoints

GET
/api/v1/health

Health check

Confirms the API is up and your key is valid. Handy as a first call to verify credentials and connectivity.

Auth: Bearer tokenAccess: Any valid API key.

Request

curl https://www.sitebeacon.eu/api/v1/health \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "status": "healthy",
  "timestamp": "2026-07-19T12:00:00.000Z",
  "uptime": 1234.56,
  "version": "1.0.0",
  "apiKey": "My key",
  "userId": "usr_...",
  "message": "API is running successfully"
}
GET
/api/v1/stats

Account & API usage stats

Returns the calling user together with API-usage counters (requests today / this week / this month, error rate, API-key count).

Auth: Bearer tokenAccess: Any valid API key (scoped to the key owner).

Request

curl https://www.sitebeacon.eu/api/v1/stats \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "user": { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "createdAt": "..." },
  "apiStats": {
    "totalApiKeys": 2,
    "requestsToday": 14,
    "requestsThisWeek": 98,
    "requestsThisMonth": 412,
    "errorRate": "1.20%",
    "errorCount": 5
  },
  "meta": { "timestamp": "...", "apiKey": "My key" }
}
GET
/api/v1/users

List users

Lists users. A regular key returns only its own user record; an admin key returns all users with pagination.

Auth: Bearer tokenAccess: Any valid API key (admin keys see all users; others see themselves).
NameInTypeReq.Description
limitqueryintegernoPage size, 1–100 (default 10). Admin only; ignored for non-admins.
offsetqueryintegernoRows to skip (default 0). Admin only.

Request

curl "https://www.sitebeacon.eu/api/v1/users?limit=20&offset=0" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "users": [
    { "id": "usr_...", "email": "you@example.com", "name": "You", "role": "user", "emailVerified": null, "createdAt": "..." }
  ],
  "meta": { "limit": 20, "offset": 0, "total": 1, "apiKey": "My key" }
}
POST
/api/v1/users

Create user (scaffold)

Admin-only endpoint scaffold for creating a user. Ships as a stub in this starter — it validates input and echoes it back rather than persisting. Fill in real creation logic before relying on it.

Auth: Bearer tokenAccess: Admin API keys only (others get 403).
NameInTypeReq.Description
emailbodystringyesNew user email.
namebodystringyesNew user display name.
rolebodystringno'user' (default) or 'admin'.

Request

curl -X POST https://www.sitebeacon.eu/api/v1/users \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com","name":"New User","role":"user"}'

Response

{
  "message": "User creation endpoint - implementation needed",
  "requestedData": { "email": "new@example.com", "name": "New User", "role": "user" },
  "apiKey": "My key"
}
  • This is a template stub — no user is actually created yet.
POST
/api/v1/files

Upload a file

Uploads a file and stores its raw bytes. Use this instead of a form/Server Action for any real upload (Server Actions cap the body at ~1MB; this endpoint does not). Send `multipart/form-data` with a single `file` field.

Auth: Bearer tokenAccess: Any valid API key (the file is owned by the key owner).
NameInTypeReq.Description
fileformfileyesThe file to upload (multipart field name must be "file").

Request

curl -X POST https://www.sitebeacon.eu/api/v1/files \
  -H "Authorization: Bearer sk_your_key_here" \
  -F "file=@./photo.png"

Response

{
  "id": "fil_...",
  "filename": "photo.png",
  "url": "/api/v1/files/fil_..."
}
  • Default max size is 100MB (configurable via MAX_FILE_SIZE). Oversized uploads return 413 — the whole multipart body is capped at that size + 64 KB while it is read.
  • The returned `url` is the Bearer-gated download endpoint below.
GET
/api/v1/files/:id

Download / preview a file

Streams the raw file bytes with the stored Content-Type. Because it is Bearer-gated you cannot put it directly in an `<img src>`; fetch it with the token and build an object URL client-side.

Auth: Bearer tokenAccess: Any valid API key.
NameInTypeReq.Description
idpathstringyesFile id returned by the upload endpoint.

Request

curl https://www.sitebeacon.eu/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here" \
  --output downloaded-file

Response

Raw binary body with the stored `Content-Type` and `Content-Disposition: inline; filename="..."`. Returns `404 { "error": "File not found" }` if unknown.
DELETE
/api/v1/files/:id

Delete a file

Deletes a file owned by the calling key.

Auth: Bearer tokenAccess: Any valid API key (only the owner may delete).
NameInTypeReq.Description
idpathstringyesFile id to delete.

Request

curl -X DELETE https://www.sitebeacon.eu/api/v1/files/fil_your_file_id \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true }   // { "deleted": false } with status 404 if not found / not owned
POST
/api/v1/collect

Send events from a server

Records pageviews and custom events server-side — for server-rendered sites, backends, apps or anywhere JavaScript does not run. Send ONE event object or an ARRAY of up to 100. An event named `pageview` (the default when `name` is omitted) counts as a pageview; any other name is a custom event/goal. Pass the end-user's IP and User-Agent so visitors and visits are counted (they are hashed with a daily salt, never stored).

Auth: Site secret (Bearer ssk_…)Access: The site whose secret (`ssk_…`) is used. Write-only.
NameInTypeReq.Description
namebodystringno'pageview' (default) or a custom event name, ≤120 chars.
urlbodystringyesAbsolute http(s) URL of the page, or a path starting with `/` (the site domain is assumed). UTM params in it are recorded.
ipbodystringnoThe visitor's IP (hashed, never stored). Strongly recommended.
userAgentbodystringnoThe visitor's User-Agent (browser/OS/device + visitor hash).
referrerbodystringnoReferer header of the original request (query string is dropped).
countrybodystringnoISO-3166 alpha-2 country code if you know it (e.g. from CF-IPCountry).
visitorbodystringnoYour own stable, already-anonymised visitor key — used INSTEAD of ip+userAgent for identity.
propsbodyobjectnoFlat map of custom properties (string/number/boolean, ≤30 keys, values ≤256 chars).
timestampbodystring|numbernoISO-8601 or epoch-ms; defaults to now. May be up to 7 days in the past, never in the future.
pageviewKeybodystringnoPageview items: your random id for this page view (≤ 64 chars), so a later `engage` item can add time on page.
engagedMsbodyintegernoWith `name: "engage"` + `pageviewKey`: visible time on that page in ms (the largest value reported wins).

Request

curl -X POST https://www.sitebeacon.eu/api/v1/collect \
  -H "Authorization: Bearer ssk_your_site_secret" \
  -H "Content-Type: application/json" \
  -d '[{"name":"pageview","url":"https://example.com/pricing","ip":"203.0.113.7","userAgent":"Mozilla/5.0 ...","referrer":"https://www.google.com/"},
       {"name":"Purchase","url":"/checkout","ip":"203.0.113.7","userAgent":"Mozilla/5.0 ...","props":{"plan":"pro"}}]'

Response

{
  "accepted": 2,
  "results": [
    { "index": 0, "stored": true },
    { "index": 1, "stored": true }
  ]
}
  • Returns 202 when at least one event was accepted, 400 when all failed (each result carries its own `error`), 401 for a bad/missing site secret, 413 for >100 events or a body over 1 MB, 429 when rate limited.
  • Bot User-Agents are silently skipped (`stored: false, reason: "bot"`) unless you pass `visitor`.
  • Engagement without JavaScript: send `{ "name": "engage", "pageviewKey": "<same key as the pageview>", "engagedMs": 15000 }` — `stored: false, reason: "unknown page view"` if no pageview with that key exists.
  • `ip` / `country` are always taken from the body here (server ingest is authenticated by the site secret); the trusted-proxy header rule applies to `/api/event` only.
  • Ready-made clients: GET /scripts/sitebeacon.mjs (Node), /scripts/sitebeacon.py (Python), /scripts/sitebeacon.php (PHP).
POST
/api/event

Browser ingest (used by /a.js)

The endpoint the `/a.js` snippet beacons to. Public and CORS-open; bodies are `text/plain` JSON so no preflight is needed. You normally never call it directly — embed `<script defer data-site="st_…" src="{BASE_URL}/a.js"></script>` and call `sitebeacon('EventName', { props: {…} })` for custom events. Hits whose page hostname is not the site's domain (or a subdomain) are ignored.

Auth: NoneAccess: Anyone who knows the public site id (`st_…`).
NameInTypeReq.Description
sbodystringyesPublic site id (`st_…`).
kbodystringyes'pageview' | 'event' | 'engage' | 'vitals'.
ubodystringyesPage URL (pageview/event).
nbodystringnoEvent name (k=event).
rbodystringnodocument.referrer.
tzbodystringnoIANA time zone — used to derive the country when no CDN country header exists.
pvbodystringnoRandom per-pageview id; lets later `engage` pings add visible time to it.
ebodyintegernoEngaged (visible) milliseconds on the page (k=engage).
pbodyobjectnoCustom event properties (k=event).
lcp, cls, inp, ttfbbodynumbernok=vitals: Core Web Vitals of page view `pv` (ms; CLS unitless). Stored once per page view.
x-sitebeacon-proxyheaderstringnoFirst-party proxies only: a TRUSTED_PROXY_SECRETS value. Only then are `X-Forwarded-For` (first entry = visitor) and `x-country-code` trusted.

Request

curl -X POST https://www.sitebeacon.eu/api/event \
  -H "Content-Type: text/plain" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/128 Safari/537.36" \
  -d '{"s":"st_your_site_id","k":"pageview","u":"https://example.com/","r":"https://duckduckgo.com/","tz":"Europe/Amsterdam"}'

Response

`202 Accepted` with an empty body (also for ignored hits). `400`/`404`/`413` (body over 8 KB)/`429` carry `{ "error": "..." }`.
GET
/api/v1/sites

List your sites

Every site the key owner owns (in the key's tenant when multi-tenant mode is on) or was invited to — or, for an integrator key, exactly the sites that key created. `role` is `owner`, `admin`, `editor` or `viewer`; every role can read stats through this API.

Auth: Bearer tokenAccess: Any valid API key (own and shared sites); integrator keys: own sites only. Permission: `sites`.
NameInTypeReq.Description
externalOwnerquerystringnoOnly sites with this externalOwner tag (exact match).
externalRefquerystringnoOnly sites with this externalRef tag (exact match).

Request

curl "https://www.sitebeacon.eu/api/v1/sites?externalOwner=fw:usr_123" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "sites": [
    {
      "id": "st_2O8iQhfAz3yg",
      "name": "Demo store",
      "domain": "example.com",
      "aliases": ["www.example.com", "abc123.vibecode.cloud"],
      "timezone": "Europe/Amsterdam",
      "respectDnt": false,
      "allowLocalhost": true,
      "externalOwner": null,
      "externalRef": null,
      "role": "owner",
      "public": false,
      "firstEventAt": "2026-07-02T22:07:22.000Z",
      "createdAt": "2026-07-02T09:39:44.000Z"
    }
  ]
}
POST
/api/v1/sites

Create a site (idempotent)

Creates a site and returns its tracking snippet and server secret. Idempotent, so provisioning can call it repeatedly — an existing match is returned with 200, `created: false` and no secret. Personal keys match by domain among the key owner's own sites. Integrator keys match by (key, `externalRef`) when `externalRef` is given, else by (key, domain): two integrator customers with the same domain but different `externalRef`s get separate sites. Optional `members` are added silently (no e-mail) unless `notify: true`.

Auth: Bearer tokenAccess: Any valid API key (owned by the key owner; for integrator keys the site is visible to that key only). Permission: `sites`.
NameInTypeReq.Description
domainbodystringyesPrimary hostname, e.g. `example.com` (its subdomains count too).
namebodystringnoDisplay name (defaults to the domain).
aliasesbodystring[]noExtra hostnames whose hits count for this site: exact hosts or `*.zone` wildcards.
timezonebodystringnoIANA zone for day boundaries (default UTC).
membersbodyobject[]no`[{ "email": "...", "role": "viewer|editor|admin" }]` to share the site with.
notifybodybooleannoE-mail the members about their access (default false here).
externalOwnerbodystringnoYour own tag for who the site belongs to, e.g. `fw:<userId>` (≤ 200 chars). Filterable on GET.
externalRefbodystringnoYour own id for the site, e.g. `fw:<zoneId>` (≤ 200 chars). Integrator keys: the idempotency key.
basebodystringnoProxy base (https origin + optional path prefix) for a first-party `snippet` — see GET /api/v1/sites/:id/snippet.

Request

curl -X POST https://www.sitebeacon.eu/api/v1/sites \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Shop","domain":"shop.example.com","aliases":["abc123.vibecode.cloud"],"members":[{"email":"colleague@example.com","role":"admin"}]}'

Response

{
  "site": { "id": "st_…", "name": "Shop", "domain": "shop.example.com", "aliases": ["abc123.vibecode.cloud"], "timezone": "UTC",
            "respectDnt": false, "allowLocalhost": true, "externalOwner": null, "externalRef": null },
  "created": true,
  "secret": "ssk_…",
  "snippet": "<script defer data-site=\"st_…\" src=\"{BASE_URL}/a.js\"></script>"
}
  • `secret` is only returned when the site is created; it cannot be read back (rotate it with POST /api/v1/sites/:id/secret/rotate).
PATCH
/api/v1/sites/:id

Update a site

Change any of the listed settings; omitted fields stay as they are. `aliases` replaces the whole list.

Auth: Bearer tokenAccess: Owner, admin or editor of the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
namebodystringnoDisplay name.
domainbodystringnoPrimary hostname.
aliasesbodystring[]noExact hosts and/or `*.zone` wildcards.
timezonebodystringnoIANA zone for day boundaries, e.g. `Europe/Amsterdam`.
respectDntbodybooleannoDrop browser hits that send `DNT: 1` / `Sec-GPC: 1`.
allowLocalhostbodybooleannoCount hits from localhost / *.local pages.
externalOwnerbodystring|nullnoReplace (or clear with null) the externalOwner tag.
externalRefbodystring|nullnoReplace (or clear with null) the externalRef tag; 409 if another live site of the same integrator key has it.

Request

curl -X PATCH https://www.sitebeacon.eu/api/v1/sites/st_your_site_id \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"aliases":["www.example.com","abc123.vibecode.cloud"]}'

Response

{ "site": { "id": "st_…", "name": "Shop", "domain": "example.com", "aliases": ["www.example.com", "abc123.vibecode.cloud"], "timezone": "UTC", "respectDnt": false, "allowLocalhost": true, "externalOwner": null, "externalRef": null } }
GET
/api/v1/sites/:id

Get one site

The site with your role on it.

Auth: Bearer tokenAccess: Any role on the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).

Request

curl https://www.sitebeacon.eu/api/v1/sites/st_your_site_id \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "site": { "id": "st_…", "name": "Shop", "domain": "example.com", "aliases": [], "timezone": "UTC", "respectDnt": false, "allowLocalhost": true,
           "externalOwner": "fw:usr_1", "externalRef": "fw:zone_9", "role": "owner", "public": false, "firstEventAt": null, "createdAt": "…" } }
DELETE
/api/v1/sites/:id

Delete a site

Deletes the site and its statistics — the same as deleting it in the dashboard (a soft delete when tombstones are on). The tracking snippet and server secret stop working at once.

Auth: Bearer tokenAccess: Owner or admin of the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).

Request

curl -X DELETE https://www.sitebeacon.eu/api/v1/sites/st_your_site_id \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "deleted": true, "id": "st_…" }
POST
/api/v1/sites/:id/secret/rotate

Rotate the server secret

Issues a new site secret (`ssk_…`) for POST /api/v1/collect, shown once. The old secret stops working immediately.

Auth: Bearer tokenAccess: Owner or admin of the site, or the integrator key that created it. Permission: `ingest`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).

Request

curl -X POST https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/secret/rotate \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "secret": "ssk_…" }
PUT
/api/v1/sites/:id/share

Public dashboard link on/off

Enables (or disables) the public, read-only dashboard link. Re-enabling keeps the existing link.

Auth: Bearer tokenAccess: Owner, admin or editor of the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
enabledbodybooleanyestrue = public link on, false = off.

Request

curl -X PUT https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/share \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Response

{ "shareUrl": "{BASE_URL}/share/abc…" }   // { "shareUrl": null } when disabled
GET
/api/v1/sites/:id/snippet

Install snippet (optionally first-party)

The `<script>` tag to install. With `base`, the snippet is first-party: a proxy on the customer's domain mounts SiteBeacon's `/a.js` and `/api/event` under that prefix and forwards them unchanged (`{base}/a.js` → `{BASE_URL}/a.js`, `{base}/api/event` → `{BASE_URL}/api/event`). The proxy must send `x-sitebeacon-proxy: <TRUSTED_PROXY_SECRETS entry>` plus `X-Forwarded-For` (first entry = visitor) and optionally `x-country-code`; without the trusted header those are ignored.

Auth: Bearer tokenAccess: Any role on the site, or the integrator key that created it. Permission: `ingest`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
basequerystringnohttps origin + optional path prefix, e.g. `https://customer.example/_sb` (no query/fragment).

Request

curl "https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/snippet?base=https://customer.example/_sb" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "siteId": "st_…",
  "base": "https://customer.example/_sb",
  "scriptUrl": "https://customer.example/_sb/a.js",
  "eventUrl": "https://customer.example/_sb/api/event",
  "snippet": "<script defer data-site=\"st_…\" data-api=\"https://customer.example/_sb/api/event\" src=\"https://customer.example/_sb/a.js\"></script>"
}
GET
/api/v1/sites/:id/members

List people with access

Everyone the site is shared with (not the owner), with role and whether they have signed in yet.

Auth: Bearer tokenAccess: Owner or admin of the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).

Request

curl https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/members \
  -H "Authorization: Bearer sk_your_key_here"

Response

{ "members": [ { "id": "…", "email": "colleague@example.com", "name": null, "role": "viewer", "status": "pending", "invitedAt": "…" } ] }
POST
/api/v1/sites/:id/members

Share a site with someone

Gives an e-mail address a role (`viewer`, `editor` or `admin`). Existing accounts get access at once; new addresses get an invitation and can sign up (e-mail code / Google). Idempotent — repeating it just changes the role. E-mails the person unless `notify: false`.

Auth: Bearer tokenAccess: Owner or admin of the site, or the integrator key that created it. Permission: `sites`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
emailbodystringyesAddress to share with.
rolebodystringyesviewer | editor | admin.
notifybodybooleannoSend the access e-mail (default true).

Request

curl -X POST https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/members \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email":"colleague@example.com","role":"editor"}'

Response

{ "email": "colleague@example.com", "changed": true, "invitedNewUser": false, "emailed": true }
GET
/api/v1/sites/:id/stats

Summary + time series

Headline metrics for the period (and the previous period of equal length, for comparison) plus a visitors/visits/pageviews series bucketed by hour (today, 24h), day (7d–90d) or month (12mo) in the site's time zone.

Auth: Bearer tokenAccess: Any valid API key whose owner owns the site or was invited to it (any role), or the integrator key that created it. Permission: `stats`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
periodquerystringnotoday | 24h | 7d | 30d (default) | 90d | 12mo.
from, toquerystringnoCustom range instead of period: inclusive days `YYYY-MM-DD` in the site time zone (both required).
page, host, source, country, browser, os, device, campaign, eventquerystringnoOptional filters (see Essentials → Periods and filters).

Request

curl "https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/stats?period=7d&country=NL" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "site": { "id": "st_…", "name": "Demo store", "domain": "example.com", "timezone": "Europe/Amsterdam" },
  "period": "7d",
  "from": "2026-09-23T22:00:00.000Z",
  "to": "2026-09-30T10:00:00.000Z",
  "granularity": "day",
  "filters": { "country": "NL" },
  "summary":  { "visitors": 1301, "visits": 1452, "pageviews": 3081, "events": 320, "viewsPerVisit": 2.12, "bounceRate": 40.4, "avgDurationSec": 141 },
  "previous": { "visitors": 1176, "visits": 1290, "pageviews": 2732, "events": 299, "viewsPerVisit": 2.12, "bounceRate": 38.1, "avgDurationSec": 138 },
  "timeseries": [ { "bucket": "2026-09-24", "visitors": 218, "visits": 240, "pageviews": 515 } ]
}
  • `bounceRate` is a percentage (0–100) of visits with a single pageview and no events; `avgDurationSec` is the average visible (engaged) time per visit.
  • Visitors are unique per UTC day by design (the hash salt rotates daily), so multi-day totals count a returning person once per day.
GET
/api/v1/sites/:id/breakdown

Top values of a dimension

Ranks the values of one dimension by unique visitors for the period, honouring the same filters as /stats.

Auth: Bearer tokenAccess: Any valid API key whose owner owns the site or was invited to it (any role), or the integrator key that created it. Permission: `stats`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
dimensionquerystringyespage | hostname | entry | exit | source | referrer | campaign | medium | country | browser | os | device | event.
periodquerystringnoAs for /stats (default 30d).
from, toquerystringnoCustom range instead of period (YYYY-MM-DD, inclusive).
limitqueryintegernoRows to return, 1–500 (default 10).
page, host, source, country, browser, os, device, campaign, eventquerystringnoOptional filters.

Request

curl "https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/breakdown?dimension=source&period=30d&limit=5" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "dimension": "source",
  "period": "30d",
  "filters": {},
  "rows": [
    { "value": "Google", "visitors": 1972, "pageviews": 4679, "count": 5161 },
    { "value": "Direct / None", "visitors": 1715, "pageviews": 4135, "count": 4556 }
  ]
}
  • `count` = matching rows (for `event`: times the event fired; for `entry`/`exit`: visits that started/ended there). `value` is null when unknown.
GET
/api/v1/sites/:id/realtime

Realtime visitors

Unique visitors and pageviews in the last 5 minutes, the top 5 active pages, and pageviews per minute for the last 30 minutes (index 0 = 29 minutes ago).

Auth: Bearer tokenAccess: Any valid API key whose owner owns the site or was invited to it (any role), or the integrator key that created it. Permission: `stats`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).

Request

curl https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/realtime \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "visitors": 3,
  "pageviews": 4,
  "pages": [ { "path": "/pricing", "visitors": 2 } ],
  "perMinute": [ { "minute": 29, "pageviews": 0 }, "…", { "minute": 0, "pageviews": 2 } ]
}
GET
/api/v1/sites/:id/vitals

Core Web Vitals

p75 (nearest rank) of LCP, CLS, INP and TTFB for real page views, the share of samples rated good / needs improvement / poor (LCP 2.5 s / 4 s, CLS 0.1 / 0.25, INP 200 / 500 ms, TTFB 0.8 / 1.8 s), and the same p75s per page. Reported by `/a.js` (opt out per snippet with `data-no-vitals`).

Auth: Bearer tokenAccess: Any role on the site, or the integrator key that created it. Permission: `stats`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
periodquerystringnoAs for /stats (default 30d).
from, toquerystringnoCustom range instead of period (YYYY-MM-DD, inclusive).
pagequerystringnoOnly this path.
devicequerystringnodesktop | mobile | tablet.
limitqueryintegernoPages in `byPage`, 1–100 (default 20, by sample count).

Request

curl "https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/vitals?period=7d&device=mobile" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "period": "7d", "from": "…", "to": "…", "filters": { "device": "mobile" },
  "p75": { "lcp": 2310, "cls": 0.04, "inp": 180, "ttfb": 420 },
  "rating": {
    "lcp": { "good": 78.2, "needsImprovement": 15.1, "poor": 6.7, "samples": 1290 },
    "cls": { "good": 91.0, "needsImprovement": 6.5, "poor": 2.5, "samples": 1302 },
    "inp": { "good": 84.4, "needsImprovement": 12.0, "poor": 3.6, "samples": 870 },
    "ttfb": { "good": 88.9, "needsImprovement": 9.8, "poor": 1.3, "samples": 1302 }
  },
  "samples": 1302,
  "byPage": [ { "path": "/", "samples": 540, "lcp": 2100, "cls": 0.03, "inp": 160, "ttfb": 390 } ]
}
  • `rating` values are percentages (0–100) of that metric's samples; a metric is `null` when no page view reported it (e.g. INP without interactions).
GET
/api/v1/sites/:id/dashboard

Dashboard in one call

Summary, previous period, time series and the top 10 pages, sources, countries and devices — everything a dashboard view needs.

Auth: Bearer tokenAccess: Any role on the site, or the integrator key that created it. Permission: `stats`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
periodquerystringnoAs for /stats (default 30d).
from, toquerystringnoCustom range instead of period (YYYY-MM-DD, inclusive).
page, host, source, country, browser, os, device, campaign, eventquerystringnoOptional filters.

Request

curl "https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/dashboard?period=30d" \
  -H "Authorization: Bearer sk_your_key_here"

Response

{
  "site": { "id": "st_…", "name": "Shop", "domain": "example.com", "timezone": "UTC" },
  "period": "30d", "from": "…", "to": "…", "granularity": "day", "filters": {},
  "summary": { "visitors": 1301, "visits": 1452, "pageviews": 3081, "events": 320, "viewsPerVisit": 2.12, "bounceRate": 40.4, "avgDurationSec": 141 },
  "previous": { "visitors": 1176, "…": "…" },
  "timeseries": [ { "bucket": "2026-11-01", "visitors": 41, "visits": 45, "pageviews": 98 } ],
  "topPages": [ { "value": "/", "visitors": 800, "pageviews": 1200, "count": 1200 } ],
  "topSources": [ { "value": "Google", "visitors": 500, "pageviews": 900, "count": 950 } ],
  "topCountries": [ { "value": "NL", "name": "Netherlands", "visitors": 400, "pageviews": 700, "count": 760 } ],
  "topDevices": [ { "value": "desktop", "visitors": 700, "pageviews": 1500, "count": 1600 } ]
}
POST
/api/v1/sites/:id/embed-tokens

Embeddable dashboard link

Mints a signed, expiring URL (`/embed/:token`) that renders the dashboard without SiteBeacon's header/navigation, for an iframe on `allowedOrigins` only (`Content-Security-Policy: frame-ancestors …`). Stateless (HMAC with the server's `EMBED_TOKEN_SECRET`); it stops working at `expiresAt`, or earlier if the minting key is revoked or the site deleted. An invalid/expired link shows a small 401 page. Realtime and charts poll token-authenticated GET routes, so they work cross-origin without cookies.

Auth: Bearer tokenAccess: Any role on the site, or the integrator key that created it. Permission: `embed`.
NameInTypeReq.Description
idpathstringyesSite id (`st_…`).
allowedOriginsbodystring[]yes1–10 https origins allowed to frame it, e.g. `["https://app.fluxwall.example"]`.
ttlSecondsbodyintegernoLifetime, 60–86400 (default 3600).
viewbodystringno`full` (default) or `overview` (KPIs, chart and realtime only).

Request

curl -X POST https://www.sitebeacon.eu/api/v1/sites/st_your_site_id/embed-tokens \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins":["https://app.fluxwall.example"],"ttlSeconds":3600,"view":"full"}'

Response

{
  "token": "eyJ2IjoxLC…",
  "url": "{BASE_URL}/embed/eyJ2IjoxLC…",
  "expiresAt": "2026-11-18T13:00:00.000Z",
  "allowedOrigins": ["https://app.fluxwall.example"],
  "view": "full"
}
  • URL options: `?period=7d`, `?theme=light|dark`, and `?snwflk=1&instanceId=<id>` for the snwflk 1.0 widget protocol. The embed posts `{ snwflk: "1.0", kind, instanceId, messageId, replyTo?, timestamp, payload }` envelopes to `window.parent` — only at the first `allowedOrigins` entry equal to the `document.referrer` origin (never `*`) — and accepts messages only from `window.parent` at that origin. It sends `ready` `{ capabilities: { emits: ["sitebeacon.period"] } }`, `resize` `{ height }` and, when the period changes, `emit` `{ type: "sitebeacon.period", version: "1.0", data: { period } }` (events always use kind `emit`), and applies `init` `payload.context.theme.mode` (light/dark) and `payload.config.period`.
  • 503 when the server has no `EMBED_TOKEN_SECRET` configured.
POST
/api/v1/admin/keys

Mint an integrator key

Creates an integrator API key (`scope: "created_by_key"`) owned by the platform identity (the earliest admin user and its workspace). The key can only see sites it creates itself. Only available when the server sets `ADMIN_API_KEY_HASH` (bcrypt of the admin `sk_…` token) — otherwise every `/api/v1/admin/**` route answers 404.

Auth: Admin bootstrap key (ADMIN_API_KEY_HASH)Access: The server operator (admin bootstrap key).
NameInTypeReq.Description
namebodystringyesLabel, e.g. `FluxWall production`.
scopebodystringyesMust be `created_by_key`.
permissionsbodystring[]noSubset of `sites`, `stats`, `ingest`, `embed` (default: all).

Request

curl -X POST https://www.sitebeacon.eu/api/v1/admin/keys \
  -H "Authorization: Bearer sk_admin_bootstrap_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"FluxWall","scope":"created_by_key","permissions":["sites","stats","ingest","embed"]}'

Response

{ "id": "…", "key": "sk_…", "name": "FluxWall", "scope": "created_by_key", "permissions": ["sites", "stats", "ingest", "embed"], "createdAt": "…" }
  • `key` is shown only in this response. 401 for a wrong admin key, 503 if no admin user exists yet.
GET
/api/v1/admin/keys

List integrator keys

Integrator keys minted through the admin API that are not revoked, with how many live sites each created.

Auth: Admin bootstrap key (ADMIN_API_KEY_HASH)Access: The server operator (admin bootstrap key).

Request

curl https://www.sitebeacon.eu/api/v1/admin/keys \
  -H "Authorization: Bearer sk_admin_bootstrap_key"

Response

{ "keys": [ { "id": "…", "name": "FluxWall", "scope": "created_by_key", "permissions": ["sites", "stats", "ingest", "embed"], "createdAt": "…", "lastUsedAt": "…", "sites": 42 } ] }
DELETE
/api/v1/admin/keys/:id

Revoke an integrator key

The key stops authenticating immediately and its embed links die. Sites it created are kept (delete them first if needed).

Auth: Admin bootstrap key (ADMIN_API_KEY_HASH)Access: The server operator (admin bootstrap key).
NameInTypeReq.Description
idpathstringyesKey id from POST/GET /api/v1/admin/keys.

Request

curl -X DELETE https://www.sitebeacon.eu/api/v1/admin/keys/key_id \
  -H "Authorization: Bearer sk_admin_bootstrap_key"

Response

{ "deleted": true, "id": "…" }   // 404 { "error": "Key not found" } for unknown / already revoked