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.
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.
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.
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.
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.
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.
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.
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`.
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 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.
/api/v1/healthConfirms the API is up and your key is valid. Handy as a first call to verify credentials and connectivity.
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"
}/api/v1/statsReturns the calling user together with API-usage counters (requests today / this week / this month, error rate, API-key count).
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" }
}/api/v1/usersLists users. A regular key returns only its own user record; an admin key returns all users with pagination.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| limit | query | integer | no | Page size, 1–100 (default 10). Admin only; ignored for non-admins. |
| offset | query | integer | no | Rows 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" }
}/api/v1/usersAdmin-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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| body | string | yes | New user email. | |
| name | body | string | yes | New user display name. |
| role | body | string | no | '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"
}/api/v1/filesUploads 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| file | form | file | yes | The 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_..."
}/api/v1/files/:idStreams 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | File 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-fileResponse
Raw binary body with the stored `Content-Type` and `Content-Disposition: inline; filename="..."`. Returns `404 { "error": "File not found" }` if unknown./api/v1/files/:idDeletes a file owned by the calling key.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | File 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/api/v1/collectRecords 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).
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| name | body | string | no | 'pageview' (default) or a custom event name, ≤120 chars. |
| url | body | string | yes | Absolute http(s) URL of the page, or a path starting with `/` (the site domain is assumed). UTM params in it are recorded. |
| ip | body | string | no | The visitor's IP (hashed, never stored). Strongly recommended. |
| userAgent | body | string | no | The visitor's User-Agent (browser/OS/device + visitor hash). |
| referrer | body | string | no | Referer header of the original request (query string is dropped). |
| country | body | string | no | ISO-3166 alpha-2 country code if you know it (e.g. from CF-IPCountry). |
| visitor | body | string | no | Your own stable, already-anonymised visitor key — used INSTEAD of ip+userAgent for identity. |
| props | body | object | no | Flat map of custom properties (string/number/boolean, ≤30 keys, values ≤256 chars). |
| timestamp | body | string|number | no | ISO-8601 or epoch-ms; defaults to now. May be up to 7 days in the past, never in the future. |
| pageviewKey | body | string | no | Pageview items: your random id for this page view (≤ 64 chars), so a later `engage` item can add time on page. |
| engagedMs | body | integer | no | With `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 }
]
}/api/eventThe 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| s | body | string | yes | Public site id (`st_…`). |
| k | body | string | yes | 'pageview' | 'event' | 'engage' | 'vitals'. |
| u | body | string | yes | Page URL (pageview/event). |
| n | body | string | no | Event name (k=event). |
| r | body | string | no | document.referrer. |
| tz | body | string | no | IANA time zone — used to derive the country when no CDN country header exists. |
| pv | body | string | no | Random per-pageview id; lets later `engage` pings add visible time to it. |
| e | body | integer | no | Engaged (visible) milliseconds on the page (k=engage). |
| p | body | object | no | Custom event properties (k=event). |
| lcp, cls, inp, ttfb | body | number | no | k=vitals: Core Web Vitals of page view `pv` (ms; CLS unitless). Stored once per page view. |
| x-sitebeacon-proxy | header | string | no | First-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": "..." }`./api/v1/sitesEvery 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| externalOwner | query | string | no | Only sites with this externalOwner tag (exact match). |
| externalRef | query | string | no | Only 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"
}
]
}/api/v1/sitesCreates 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`.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| domain | body | string | yes | Primary hostname, e.g. `example.com` (its subdomains count too). |
| name | body | string | no | Display name (defaults to the domain). |
| aliases | body | string[] | no | Extra hostnames whose hits count for this site: exact hosts or `*.zone` wildcards. |
| timezone | body | string | no | IANA zone for day boundaries (default UTC). |
| members | body | object[] | no | `[{ "email": "...", "role": "viewer|editor|admin" }]` to share the site with. |
| notify | body | boolean | no | E-mail the members about their access (default false here). |
| externalOwner | body | string | no | Your own tag for who the site belongs to, e.g. `fw:<userId>` (≤ 200 chars). Filterable on GET. |
| externalRef | body | string | no | Your own id for the site, e.g. `fw:<zoneId>` (≤ 200 chars). Integrator keys: the idempotency key. |
| base | body | string | no | Proxy 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>"
}/api/v1/sites/:idChange any of the listed settings; omitted fields stay as they are. `aliases` replaces the whole list.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| name | body | string | no | Display name. |
| domain | body | string | no | Primary hostname. |
| aliases | body | string[] | no | Exact hosts and/or `*.zone` wildcards. |
| timezone | body | string | no | IANA zone for day boundaries, e.g. `Europe/Amsterdam`. |
| respectDnt | body | boolean | no | Drop browser hits that send `DNT: 1` / `Sec-GPC: 1`. |
| allowLocalhost | body | boolean | no | Count hits from localhost / *.local pages. |
| externalOwner | body | string|null | no | Replace (or clear with null) the externalOwner tag. |
| externalRef | body | string|null | no | Replace (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 } }/api/v1/sites/:idThe site with your role on it.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site 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": "…" } }/api/v1/sites/:idDeletes 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site 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_…" }/api/v1/sites/:id/secret/rotateIssues a new site secret (`ssk_…`) for POST /api/v1/collect, shown once. The old secret stops working immediately.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site 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_…" }/api/v1/sites/:id/snippetThe `<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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| base | query | string | no | https 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>"
}/api/v1/sites/:id/membersEveryone the site is shared with (not the owner), with role and whether they have signed in yet.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site 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": "…" } ] }/api/v1/sites/:id/membersGives 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`.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| body | string | yes | Address to share with. | |
| role | body | string | yes | viewer | editor | admin. |
| notify | body | boolean | no | Send 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 }/api/v1/sites/:id/statsHeadline 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| period | query | string | no | today | 24h | 7d | 30d (default) | 90d | 12mo. |
| from, to | query | string | no | Custom range instead of period: inclusive days `YYYY-MM-DD` in the site time zone (both required). |
| page, host, source, country, browser, os, device, campaign, event | query | string | no | Optional 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 } ]
}/api/v1/sites/:id/breakdownRanks the values of one dimension by unique visitors for the period, honouring the same filters as /stats.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| dimension | query | string | yes | page | hostname | entry | exit | source | referrer | campaign | medium | country | browser | os | device | event. |
| period | query | string | no | As for /stats (default 30d). |
| from, to | query | string | no | Custom range instead of period (YYYY-MM-DD, inclusive). |
| limit | query | integer | no | Rows to return, 1–500 (default 10). |
| page, host, source, country, browser, os, device, campaign, event | query | string | no | Optional 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 }
]
}/api/v1/sites/:id/realtimeUnique 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).
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site 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 } ]
}/api/v1/sites/:id/vitalsp75 (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`).
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| period | query | string | no | As for /stats (default 30d). |
| from, to | query | string | no | Custom range instead of period (YYYY-MM-DD, inclusive). |
| page | query | string | no | Only this path. |
| device | query | string | no | desktop | mobile | tablet. |
| limit | query | integer | no | Pages 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 } ]
}/api/v1/sites/:id/dashboardSummary, previous period, time series and the top 10 pages, sources, countries and devices — everything a dashboard view needs.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| period | query | string | no | As for /stats (default 30d). |
| from, to | query | string | no | Custom range instead of period (YYYY-MM-DD, inclusive). |
| page, host, source, country, browser, os, device, campaign, event | query | string | no | Optional 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 } ]
}/api/v1/sites/:id/embed-tokensMints 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Site id (`st_…`). |
| allowedOrigins | body | string[] | yes | 1–10 https origins allowed to frame it, e.g. `["https://app.fluxwall.example"]`. |
| ttlSeconds | body | integer | no | Lifetime, 60–86400 (default 3600). |
| view | body | string | no | `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"
}/api/v1/admin/keysCreates 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.
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| name | body | string | yes | Label, e.g. `FluxWall production`. |
| scope | body | string | yes | Must be `created_by_key`. |
| permissions | body | string[] | no | Subset 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": "…" }/api/v1/admin/keysIntegrator keys minted through the admin API that are not revoked, with how many live sites each created.
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 } ] }/api/v1/admin/keys/:idThe key stops authenticating immediately and its embed links die. Sites it created are kept (delete them first if needed).
| Name | In | Type | Req. | Description |
|---|---|---|---|---|
| id | path | string | yes | Key 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