API reference
Every route of the server, who may call it, what it takes, and what it answered on an invented site.
This page is generated from the server's route table, its schemas and
route-docs.ts in packages/server and packages/ee, and every example
is the answer the real server gave. The same is in openapi.json
for your own tools.
How to call it
Every answer is JSON in one envelope: { "success": true, "data": ..., "meta": ... },
or { "success": false, "error": { "code", "message", "details" } } with
the status that fits. A route that changes something is sent JSON.
A caller is somebody signed in, with the chokh_session cookie that
signing in sets, or a key, sent as Authorization: Bearer <token>. A key
carries scopes on one site: read:stats reads reports, read:identity
also reads who people are, write:events sends events from a server, and
admin changes the site. A route marked Chokh Pro answers only on an
install whose licence key names its feature.
Times are Unix milliseconds. A report's from and to also take a date
and time written as ISO 8601.
About the examples. They come from Quillmoor Coffee, a site invented for
these pages, recorded from the server at noon UTC on 1 October 2026. An id
the server made at random is shown as g_example1 and so on, and every
list is cut to its first three items. Routes of Chokh Pro, a redirect, the
realtime stream, the badge picture and the check a load balancer reads have
no recorded example.
Collecting
POST /api/collect
What the tracker sends: a batch of pageviews and events from one page, read as JSON whatever its content type says.
Who: Anybody.
Body:
siteId, text, requiredsentAt, a whole number, requiredhostname, text, requiredlang, textscreen, textviewport, textvisitorId, textuserId, textsig, textevents, a list of an object, required
POST /api/sites/:siteId/events
Events and identifies from your own server, with a key carrying write:events.
Who: A session or a key with write:events on the site.
Body:
userId, text, requiredvisitorId, textevents, a list of an object, required
GET /health
Whether the process is up, for a load balancer or a container check.
Who: Anybody.
Signing in
POST /api/auth/register
The first account of an install registers itself and owns it; after that, an owner creates accounts.
Who: Anybody, for the first account of an install; after that, a person who owns a team.
Body:
email, text, requiredpassword, text, requiredname, text
POST /api/auth/login
Signs in with an address and a password and sets the session cookie.
Who: Anybody.
Body:
email, text, requiredpassword, text, required
POST /api/auth/logout
Ends the session this request carries.
Who: Anybody signed in, or any key.
POST /api/sso
Exchanges a token another application signed for a session, for that application's server.
Who: Anybody.
Body:
token, text, required
GET /api/sso
The same exchange for a person following a link: sets the cookie and redirects to next.
Who: Anybody.
Query:
token, text, requirednext, text
GET /api/me
Who is asking: the account or the key, and every site it can read with its role and scopes.
Who: Anybody signed in, or any key.
Answered 200:
{
"success": true,
"data": {
"actor": {
"kind": "session",
"id": "u_example1"
},
"user": {
"id": "u_example1",
"email": "mira@quillmoor.example",
"name": "Mira Okafor"
},
"sites": [
{
"id": "s_demo",
"name": "Quillmoor Coffee",
"domains": [
"quillmoor.example"
],
"teamId": "default",
"settings": {
"ipMode": "anonymized",
"visitorIdMode": "cookieless",
"botFilter": true,
"retentionDays": 180,
"timezone": "UTC",
"allowUnsignedIdentify": true,
"excludeIps": [],
"excludePaths": [],
"excludeQueryParams": [],
"routeGroups": [],
"errorCapture": false,
"errorStacks": false
},
"share": {
"token": "share_example1",
"protected": false,
"createdAt": 1790856000000
},
"scopes": [
"admin",
"read:identity",
"read:stats"
],
"role": "owner"
}
],
"teams": [
{
"id": "default",
"name": "Default",
"role": "owner"
}
]
}
}
GET /api/license
What this install may run: the licence's holder, its features and its expiry, or that there is none.
Who: Anybody signed in, or any key.
Answered 200:
{
"success": true,
"data": {
"licensed": false,
"plan": null,
"licensee": null,
"expiresAt": null,
"features": []
}
}
Sites
GET /api/sites
The sites the caller can read.
Who: Anybody signed in, or any key.
Answered 200:
{
"success": true,
"data": {
"sites": [
{
"id": "s_demo",
"name": "Quillmoor Coffee",
"domains": [
"quillmoor.example"
],
"teamId": "default",
"settings": {
"ipMode": "anonymized",
"visitorIdMode": "cookieless",
"botFilter": true,
"retentionDays": 180,
"timezone": "UTC",
"allowUnsignedIdentify": true,
"excludeIps": [],
"excludePaths": [],
"excludeQueryParams": [],
"routeGroups": [],
"errorCapture": false,
"errorStacks": false
},
"share": {
"token": "share_example1",
"protected": false,
"createdAt": 1790856000000
},
"scopes": [
"admin",
"read:identity",
"read:stats"
],
"role": "owner"
}
]
}
}
POST /api/sites
Creates a site, with its id, name, domains and settings. Its identify secret is in the answer, once.
Who: A person signed in who owns the team. Never a key.
Body:
id, textname, text, requireddomains, a list of text, requiredteamId, textsettings, an object
GET /api/sites/:siteId
One site and its settings.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"site": {
"id": "s_demo",
"name": "Quillmoor Coffee",
"domains": [
"quillmoor.example"
],
"teamId": "default",
"settings": {
"ipMode": "anonymized",
"visitorIdMode": "cookieless",
"botFilter": true,
"retentionDays": 180,
"timezone": "UTC",
"allowUnsignedIdentify": true,
"excludeIps": [],
"excludePaths": [],
"excludeQueryParams": [],
"routeGroups": [],
"errorCapture": false,
"errorStacks": false
},
"share": {
"token": "share_example1",
"protected": false,
"createdAt": 1790856000000
}
},
"scopes": [
"admin",
"read:identity",
"read:stats"
],
"role": "owner"
}
}
PATCH /api/sites/:siteId
Changes a site's name, domains or settings.
Who: A session or a key with admin on the site.
Body:
name, textdomains, a list of textsettings, an object
POST /api/sites/:siteId/identify-secret/rotate
Replaces the site's identify secret; the new one is in the answer, once.
Who: A session or a key with admin on the site.
Keys
GET /api/sites/:siteId/keys
The site's keys, without their tokens.
Who: A session or a key with admin on the site.
Answered 200:
{
"success": true,
"data": {
"keys": [
{
"id": "k_example1",
"siteId": "s_demo",
"name": "Checkout server",
"scopes": [
"write:events"
],
"createdAt": 1790856000000,
"createdBy": "u_example1"
}
]
}
}
POST /api/sites/:siteId/keys
Creates a key with the scopes named; its token is in the answer, once.
Who: A session or a key with admin on the site.
Body:
name, text, requiredscopes, a list of one ofread:stats,read:identity,write:events,admin, required
DELETE /api/sites/:siteId/keys/:keyId
Revokes a key.
Who: A session or a key with admin on the site.
Reports
GET /api/sites/:siteId/stats/aggregate
The headline numbers for a range: visitors, visits, pageviews, bounce rate, visit duration, with a comparison when asked.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"range": {
"from": 1790251200000,
"to": 1790856000000
},
"previousRange": null,
"metrics": {
"visitors": 6,
"pageviews": 13,
"visits": 6,
"bounces": 1,
"bounceRate": 0.16666666666666666,
"avgDurationMs": 60000
},
"previous": null
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/sites/:siteId/stats/timeseries
The same numbers by minute, hour, day, week or month.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"interval": "day",
"points": [
{
"start": 1790208000000,
"end": 1790294400000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"start": 1790294400000,
"end": 1790380800000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"start": 1790380800000,
"end": 1790467200000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
}
],
"previous": null
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/sites/:siteId/stats/breakdown
One dimension's rows (pages, sources, countries, devices and the rest), with their numbers.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"dim": "page",
"rows": [
{
"key": "/",
"metrics": {
"visitors": 4,
"pageviews": 4,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"key": "/menu",
"metrics": {
"visitors": 3,
"pageviews": 3,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"key": "/shop/beans",
"metrics": {
"visitors": 3,
"pageviews": 3,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
}
]
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/sites/:siteId/stats/engagement
Time on page and scroll depth by page.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"dim": "page",
"rows": [],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180
}
}
GET /api/sites/:siteId/export.csv
Any report as a CSV file.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
key,visitors,pageviews,visits,bounces,bounce_rate,avg_duration_ms
/,4,4,0,0,,
/menu,3,3,0,0,,
/shop/beans,3,3,0,0,,
/shop/checkout,2,2,0,0,,
/about,1,1,0,0,,
GET /api/sites/:siteId/stats/events
Custom events and how often each happened.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"visitors": 6,
"rows": [
{
"key": "order_paid",
"visitors": 2,
"events": 2,
"rate": 0.3333333333333333
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true
}
}
GET /api/sites/:siteId/stats/properties
One event's properties and their values.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, textevent, text, requiredproperty, text
Answered 200:
{
"success": true,
"data": {
"event": "order_paid",
"properties": [
{
"key": "size",
"events": 2
}
],
"property": "size",
"visitors": 6,
"rows": [
{
"key": "250g",
"visitors": 2,
"events": 2,
"rate": 0.3333333333333333
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true
}
}
GET /api/sites/:siteId/stats/goals
Each goal's conversions and conversion rate.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"visitors": 6,
"rows": [
{
"goal": {
"siteId": "s_demo",
"id": "g_example1",
"name": "Order paid",
"kind": "event",
"match": "order_paid",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
"conversion": {
"visitors": 2,
"completions": 2,
"rate": 0.3333333333333333,
"value": null
}
},
{
"goal": {
"siteId": "s_demo",
"id": "g_example2",
"name": "Saw the menu",
"kind": "page",
"match": "/menu",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
"conversion": {
"visitors": 3,
"completions": 3,
"rate": 0.5,
"value": null
}
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true
}
}
GET /api/sites/:siteId/stats/funnel
A saved funnel: how many reached each step, and where they dropped off.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, textfunnel, text, required
Answered 200:
{
"success": true,
"data": {
"funnel": {
"siteId": "s_demo",
"id": "f_example1",
"name": "Home to checkout",
"steps": [
{
"kind": "page",
"match": "/",
"name": "/"
},
{
"kind": "page",
"match": "/shop/beans",
"name": "/shop/beans"
},
{
"kind": "page",
"match": "/shop/checkout",
"name": "/shop/checkout"
}
],
"window": "visit",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
"visitors": 6,
"steps": [
{
"visitors": 4,
"dropOff": 0,
"rate": 1,
"stepRate": null
},
{
"visitors": 2,
"dropOff": 2,
"rate": 0.5,
"stepRate": 0.5
},
{
"visitors": 1,
"dropOff": 1,
"rate": 0.25,
"stepRate": 0.5
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true,
"funnel": "f_example1"
}
}
GET /api/sites/:siteId/stats/journeys
The paths visits took from the page they came in on.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, textbranches, a whole number
Answered 200:
{
"success": true,
"data": {
"visits": 6,
"columns": [
[
{
"key": "/",
"visits": 4,
"exits": 0,
"onward": 0
},
{
"key": "/menu",
"visits": 1,
"exits": 1,
"onward": 0
},
{
"key": "/shop/beans",
"visits": 1,
"exits": 0,
"onward": 0
}
],
[
{
"key": "/menu",
"visits": 2,
"exits": 1,
"onward": 0
},
{
"key": "/about",
"visits": 1,
"exits": 1,
"onward": 0
},
{
"key": "/shop/beans",
"visits": 1,
"exits": 0,
"onward": 0
}
],
[
{
"key": "/shop/beans",
"visits": 1,
"exits": 1,
"onward": 0
},
{
"key": "/shop/checkout",
"visits": 1,
"exits": 1,
"onward": 0
}
]
],
"links": [
{
"column": 0,
"from": "/",
"to": "/menu",
"visits": 2
},
{
"column": 0,
"from": "/",
"to": "/about",
"visits": 1
},
{
"column": 0,
"from": "/",
"to": "/shop/beans",
"visits": 1
}
],
"branches": 5,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true
}
}
GET /api/sites/:siteId/stats/cohorts
Retention cohorts: of the visitors first seen in a week or month, how many came back in each one after.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredinterval, one ofweek,month
Answered 200:
{
"success": true,
"data": {
"interval": "week",
"cohorts": [
{
"start": 1789948800000,
"end": 1790553600000,
"visitors": 0,
"periods": [
{
"start": 1789948800000,
"end": 1790553600000,
"visitors": 0,
"rate": null,
"complete": true
},
{
"start": 1790553600000,
"end": 1791158400000,
"visitors": 0,
"rate": null,
"complete": false
}
]
},
{
"start": 1790553600000,
"end": 1791158400000,
"visitors": 6,
"periods": [
{
"start": 1790553600000,
"end": 1791158400000,
"visitors": 6,
"rate": 1,
"complete": false
}
]
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true,
"interval": "week"
}
}
GET /api/sites/:siteId/stats/activity
Daily, weekly and monthly active visitors, and stickiness.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, required
Answered 200:
{
"success": true,
"data": {
"days": [
{
"start": 1790208000000,
"end": 1790294400000,
"dau": 0,
"wau": 0,
"mau": 0,
"complete": true
},
{
"start": 1790294400000,
"end": 1790380800000,
"dau": 0,
"wau": 0,
"mau": 0,
"complete": true
},
{
"start": 1790380800000,
"end": 1790467200000,
"dau": 0,
"wau": 0,
"mau": 0,
"complete": true
}
],
"dau": 0,
"wau": 0,
"mau": 0,
"stickiness": null,
"visitors": 6,
"returning": 0,
"returningRate": 0,
"curve": [
6,
0,
0
],
"powerMinDays": 3,
"powerUsers": 0,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true
}
}
GET /api/sites/:siteId/stats/attribution
First touch against last touch for one goal: what first brought each converting visitor, and what brought the visit they converted in.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredgoal, text, requireddim, one ofchannel,referrer,utm_source,utm_medium,utm_campaign,entry
Answered 200:
{
"success": true,
"data": {
"dim": "channel",
"visitors": 2,
"completions": 2,
"value": null,
"rows": [
{
"key": "direct",
"first": {
"visitors": 1,
"completions": 1
},
"last": {
"visitors": 1,
"completions": 1
}
},
{
"key": "organic",
"first": {
"visitors": 1,
"completions": 1
},
"last": {
"visitors": 1,
"completions": 1
}
}
],
"other": {
"first": {
"visitors": 0,
"completions": 0
},
"last": {
"visitors": 0,
"completions": 0
}
},
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true,
"goal": "g_example1",
"dim": "channel"
}
}
GET /api/sites/:siteId/stats/power-users
The most active people of the range, as rows of the people directory; their names only for a caller with read:identity.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredlimit, a whole numberminDays, a whole number
Answered 200:
{
"success": true,
"data": {
"people": [],
"days": 8,
"minDays": 3,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true,
"identity": true,
"limit": 20
}
}
GET /api/sites/:siteId/stats/vitals
Core Web Vitals by page, at the 75th percentile.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requireddevice, one ofdesktop,mobile,tabletsort, one ofLCP,INP,CLS,FCP,TTFB
Answered 200:
{
"success": true,
"data": {
"minSamples": 20,
"sort": "LCP",
"metrics": [
{
"metric": "LCP",
"p75": null,
"samples": 0,
"rating": null,
"shares": null,
"devices": []
},
{
"metric": "INP",
"p75": null,
"samples": 0,
"rating": null,
"shares": null,
"devices": []
},
{
"metric": "CLS",
"p75": null,
"samples": 0,
"rating": null,
"shares": null,
"devices": []
}
],
"pages": [],
"pagesTotal": 0,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true,
"sort": "LCP",
"device": null
}
}
GET /api/sites/:siteId/stats/errors
JavaScript errors, grouped by message and place.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, requiredlimit, a whole number
Answered 200:
{
"success": true,
"data": {
"total": 0,
"visitors": 0,
"groups": [],
"groupsTotal": 0,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true,
"limit": 50,
"errorCapture": false,
"errorStacks": false
}
}
GET /api/sites/:siteId/stats/coverage
Of the people the site's server named, the share no browser row carries: an estimate of how many block or decline the tracker.
Who: A session or a key with read:stats on the site.
Query:
from, text, requiredto, text, required
Answered 200:
{
"success": true,
"data": {
"state": "no_server_events",
"people": 0,
"seenInBrowser": 0,
"serverOnly": 0,
"share": null,
"browserIdentified": 0,
"minPeople": 20,
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"visitorIdMode": "cookieless",
"rawOnly": true
}
}
Realtime
GET /api/sites/:siteId/realtime
Who is on the site now, and on which page.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"online": 0,
"signedIn": 0,
"anonymous": 0,
"byPage": [],
"byCountry": [],
"byCity": [],
"visitors": [],
"recent": [
{
"visitorId": "v_example1",
"since": 1790855880000,
"lastSeenAt": 1790855880000,
"path": "/menu",
"browser": "Mobile Safari",
"os": "iOS",
"device": "mobile",
"ip": "203.0.113.0"
}
]
},
"meta": {
"siteId": "s_demo",
"identity": true
}
}
GET /api/sites/:siteId/realtime/stream
The same, pushed as server-sent events when it changes.
Who: A session or a key with read:stats on the site.
People
GET /api/sites/:siteId/people
Everybody the site has seen, with search and an identified-only switch.
Who: A session or a key with read:stats on the site.
Query:
limit, a whole numbercursor, textidentifiedOnly, one oftrue,falseq, text
Answered 200:
{
"success": true,
"data": {
"people": [
{
"visitorId": "u:cust_1042",
"firstSeenAt": 1790856000000,
"lastSeenAt": 1790856000000,
"sessions": 1,
"pageviews": 0,
"devices": [],
"ips": [],
"userId": "cust_1042",
"traits": {
"plan": "subscriber"
}
},
{
"visitorId": "v_example1",
"firstSeenAt": 1790855880000,
"lastSeenAt": 1790855880000,
"sessions": 1,
"pageviews": 1,
"devices": [
"Mobile Safari on iOS"
],
"ips": [
"203.0.113.0"
],
"homeGeo": {}
},
{
"visitorId": "v_example2",
"firstSeenAt": 1790834400000,
"lastSeenAt": 1790834520000,
"sessions": 1,
"pageviews": 3,
"devices": [
"Chrome on Windows"
],
"ips": [
"203.0.113.0"
],
"homeGeo": {}
}
],
"next": null
},
"meta": {
"identity": true,
"limit": 50
}
}
GET /api/sites/:siteId/visitors/:visitorId
One visitor's visits and events.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"siteId": "s_demo",
"visitorId": "u:cust_1042",
"firstSeenAt": 1790856000000,
"lastSeenAt": 1790856000000,
"pageviews": 0,
"events": 1,
"sessions": 1,
"devices": [],
"ips": [],
"timeline": [
{
"ts": 1790856000000,
"type": "event",
"name": "order_paid",
"sessionId": "dlfwz9ud86gZn5JcGWM6_8"
},
{
"ts": 1790856000000,
"type": "identify",
"sessionId": "dlfwz9ud86gZn5JcGWM6_8"
}
],
"userId": "cust_1042",
"traits": {
"plan": "subscriber"
},
"firstTouch": {
"at": 1790856000000,
"channel": "direct"
},
"lastTouch": {
"at": 1790856000000,
"channel": "direct"
}
},
"meta": {
"identity": true
}
}
GET /api/sites/:siteId/users/:userId
One identified person's visits, events and traits.
Who: A session or a key with read:identity on the site.
Answered 200:
{
"success": true,
"data": {
"siteId": "s_demo",
"visitorIds": [
"u:cust_1042"
],
"firstSeenAt": 1790856000000,
"lastSeenAt": 1790856000000,
"pageviews": 0,
"events": 1,
"sessions": 1,
"devices": [],
"ips": [],
"timeline": [
{
"ts": 1790856000000,
"type": "event",
"name": "order_paid",
"sessionId": "dlfwz9ud86gZn5JcGWM6_8"
},
{
"ts": 1790856000000,
"type": "identify",
"sessionId": "dlfwz9ud86gZn5JcGWM6_8"
}
],
"userId": "cust_1042",
"traits": {
"plan": "subscriber"
},
"firstTouch": {
"at": 1790856000000,
"channel": "direct"
},
"lastTouch": {
"at": 1790856000000,
"channel": "direct"
}
}
}
GET /api/sites/:siteId/users/:userId/presence
Whether that person is on the site now.
Who: A session or a key with read:identity on the site.
Answered 200:
{
"success": true,
"data": {
"online": false,
"lastSeenAt": 1790856000000
}
}
Goals, funnels, segments and annotations
GET /api/sites/:siteId/goals
The site's goals.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"goals": [
{
"siteId": "s_demo",
"id": "g_example1",
"name": "Order paid",
"kind": "event",
"match": "order_paid",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
{
"siteId": "s_demo",
"id": "g_example2",
"name": "Saw the menu",
"kind": "page",
"match": "/menu",
"createdBy": "u_example1",
"createdAt": 1790856000000
}
]
},
"meta": {
"siteId": "s_demo",
"max": 50
}
}
POST /api/sites/:siteId/goals
Creates a goal: a page or an event.
Who: A session or a key with admin on the site.
Body:
One of these shapes:
{
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"page"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"match": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
}
},
"required": [
"kind",
"name",
"match"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"event"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"match": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 1000000000
}
},
"required": [
"kind",
"name",
"match"
],
"additionalProperties": false
}
]
}
DELETE /api/sites/:siteId/goals/:goalId
Deletes a goal.
Who: A session or a key with admin on the site.
GET /api/sites/:siteId/funnels
The site's funnels.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"funnels": [
{
"siteId": "s_demo",
"id": "f_example1",
"name": "Home to checkout",
"steps": [
{
"kind": "page",
"match": "/",
"name": "/"
},
{
"kind": "page",
"match": "/shop/beans",
"name": "/shop/beans"
},
{
"kind": "page",
"match": "/shop/checkout",
"name": "/shop/checkout"
}
],
"window": "visit",
"createdBy": "u_example1",
"createdAt": 1790856000000
}
]
},
"meta": {
"siteId": "s_demo",
"max": 50,
"maxSteps": 8,
"windows": [
"visit",
"1h",
"1d"
],
"defaultWindow": "visit"
}
}
POST /api/sites/:siteId/funnels
Creates a funnel from its steps.
Who: A session or a key with admin on the site.
Body:
name, text, requiredwindow, one ofvisit,1h,1d,7d,30dsteps, a list of an object, required
DELETE /api/sites/:siteId/funnels/:funnelId
Deletes a funnel.
Who: A session or a key with admin on the site.
GET /api/sites/:siteId/segments
The site's saved segments.
Who: A session or a key with read:stats on the site.
Answered 200:
{
"success": true,
"data": {
"segments": [
{
"siteId": "s_demo",
"id": "sg_example1",
"name": "From Google",
"filters": [
{
"dim": "referrer",
"op": "contains",
"value": "google"
}
],
"createdBy": "u_example1",
"createdAt": 1790856000000
}
]
},
"meta": {
"siteId": "s_demo",
"max": 50
}
}
POST /api/sites/:siteId/segments
Saves a list of filters under a name.
Who: A session or a key with admin on the site.
Body:
name, text, requiredfilters, a list of an object, required
DELETE /api/sites/:siteId/segments/:segmentId
Deletes a segment.
Who: A session or a key with admin on the site.
GET /api/sites/:siteId/annotations
The marks drawn on the chart in a range.
Who: A session or a key with read:stats on the site.
Query:
from, a whole number, requiredto, a whole number, required
Answered 200:
{
"success": true,
"data": {
"annotations": [
{
"siteId": "s_demo",
"id": "an_example1",
"at": 1790510400000,
"kind": "campaign",
"text": "Autumn blend launched",
"createdBy": "u_example1",
"createdAt": 1790856000000
}
]
},
"meta": {
"siteId": "s_demo",
"from": 1790251200000,
"to": 1790856000000,
"max": 1000
}
}
POST /api/sites/:siteId/annotations
Adds a mark: a deploy, a campaign, an outage or a note.
Who: A session or a key with write:events on the site.
Body:
at, a whole number, requiredkind, one ofdeploy,campaign,downtime,note, requiredtext, text, requiredurl, text
DELETE /api/sites/:siteId/annotations/:annotationId
Deletes a mark.
Who: A session or a key with write:events on the site.
Sharing
PUT /api/sites/:siteId/share
Turns on the public share link, with an optional password, or changes it.
Who: A session or a key with admin on the site.
Body:
regenerate, true or falsepassword, text
DELETE /api/sites/:siteId/share
Turns the share link off.
Who: A session or a key with admin on the site.
GET /api/share/:token
What a share link shows: the site's name and whether a password is asked for.
Who: Anybody.
Answered 200:
{
"success": true,
"data": {
"site": {
"name": "Quillmoor Coffee",
"timezone": "UTC"
},
"protected": false,
"unlocked": true
}
}
POST /api/share/:token/unlock
Opens a share that has a password.
Who: Anybody.
Body:
password, text, required
GET /api/share/:token/stats/aggregate
The headline numbers, through a share link.
Who: Whoever holds the share link, and its password when it has one.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"range": {
"from": 1790251200000,
"to": 1790856000000
},
"previousRange": null,
"metrics": {
"visitors": 6,
"pageviews": 13,
"visits": 6,
"bounces": 1,
"bounceRate": 0.16666666666666666,
"avgDurationMs": 60000
},
"previous": null
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/share/:token/stats/timeseries
The chart, through a share link.
Who: Whoever holds the share link, and its password when it has one.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"interval": "day",
"points": [
{
"start": 1790208000000,
"end": 1790294400000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"start": 1790294400000,
"end": 1790380800000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"start": 1790380800000,
"end": 1790467200000,
"metrics": {
"visitors": 0,
"pageviews": 0,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
}
],
"previous": null
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/share/:token/stats/breakdown
One dimension's rows, through a share link.
Who: Whoever holds the share link, and its password when it has one.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"dim": "page",
"rows": [
{
"key": "/",
"metrics": {
"visitors": 4,
"pageviews": 4,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"key": "/menu",
"metrics": {
"visitors": 3,
"pageviews": 3,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
},
{
"key": "/shop/beans",
"metrics": {
"visitors": 3,
"pageviews": 3,
"visits": 0,
"bounces": 0,
"bounceRate": null,
"avgDurationMs": null
}
}
]
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000
}
}
GET /api/share/:token/stats/goals
The goals, through a share link.
Who: Whoever holds the share link, and its password when it has one.
Query:
from, text, requiredto, text, requiredfilters, textcompare, one ofprevious_period,previous_yearinterval, one ofminute,hour,day,week,monthdim, one ofpage,route,entry,exit,referrer,channel,utm_source,utm_mediumand moremetrics, textlimit, a whole numbergoal, text
Answered 200:
{
"success": true,
"data": {
"visitors": 6,
"rows": [
{
"goal": {
"siteId": "s_demo",
"id": "g_example1",
"name": "Order paid",
"kind": "event",
"match": "order_paid",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
"conversion": {
"visitors": 2,
"completions": 2,
"rate": 0.3333333333333333,
"value": null
}
},
{
"goal": {
"siteId": "s_demo",
"id": "g_example2",
"name": "Saw the menu",
"kind": "page",
"match": "/menu",
"createdBy": "u_example1",
"createdAt": 1790856000000
},
"conversion": {
"visitors": 3,
"completions": 3,
"rate": 0.5,
"value": null
}
}
],
"rawOnly": true
},
"meta": {
"siteId": "s_demo",
"timezone": "UTC",
"from": 1790251200000,
"to": 1790856000000,
"retentionDays": 180,
"rawOnly": true
}
}
GET /api/share/:token/annotations
The chart's marks, through a share link.
Who: Whoever holds the share link, and its password when it has one.
Query:
from, a whole number, requiredto, a whole number, required
Answered 200:
{
"success": true,
"data": {
"annotations": [
{
"siteId": "s_demo",
"id": "an_example1",
"at": 1790510400000,
"kind": "campaign",
"text": "Autumn blend launched",
"createdBy": "u_example1",
"createdAt": 1790856000000
}
]
},
"meta": {
"siteId": "s_demo",
"from": 1790251200000,
"to": 1790856000000,
"max": 1000
}
}
GET /api/share/:token/widget.svg
A badge of visitors or pageviews for today, 7 or 30 days, to put on a page.
Who: Whoever holds the share link, and its password when it has one.
Teams and members
GET /api/teams/:teamId/members
A team's members and their roles.
Who: A person signed in who owns the team. Never a key.
Answered 200:
{
"success": true,
"data": {
"team": {
"id": "default",
"name": "Default"
},
"members": [
{
"userId": "u_example1",
"email": "mira@quillmoor.example",
"name": "Mira Okafor",
"role": "owner",
"identity": true,
"managed": false
}
]
}
}
PUT /api/teams/:teamId/members/:userId
Gives somebody a role in the team, or changes it.
Who: A person signed in who owns the team. Never a key.
Body:
role, one ofowner,editor,viewer, requiredidentity, true or falserevokeKeys, true or false
DELETE /api/teams/:teamId/members/:userId
Removes somebody from the team.
Who: A person signed in who owns the team. Never a key.
Query:
revokeKeys, one oftrue,false
PATCH /api/teams/:teamId
Renames a team.
Who: A person signed in who owns the team. Never a key.
Body:
name, text, required
GET /api/sites/:siteId/members
Who has a role on this one site.
Who: A person signed in with admin on the site. Never a key.
Answered 200:
{
"success": true,
"data": {
"members": []
},
"meta": {
"siteId": "s_demo"
}
}
PUT /api/sites/:siteId/members/:userId
Gives somebody a role on this one site, or changes it.
Who: A person signed in with admin on the site. Never a key.
Body:
role, one ofowner,editor,viewer, requiredidentity, true or falserevokeKeys, true or false
DELETE /api/sites/:siteId/members/:userId
Removes somebody's role on this site.
Who: A person signed in with admin on the site. Never a key.
Query:
revokeKeys, one oftrue,false
Invitations
GET /api/teams/:teamId/invitations
The team's invitations still waiting.
Who: A person signed in who owns the team. Never a key.
Answered 200:
{
"success": true,
"data": {
"invitations": []
}
}
POST /api/teams/:teamId/invitations
Invites somebody to the team; the link is in the answer, once.
Who: A person signed in who owns the team. Never a key.
Body:
email, text, requiredrole, one ofowner,editor,viewer, requiredidentity, true or false
DELETE /api/teams/:teamId/invitations/:invitationId
Takes an invitation back.
Who: A person signed in who owns the team. Never a key.
GET /api/sites/:siteId/invitations
The site's invitations still waiting.
Who: A person signed in with admin on the site. Never a key.
Answered 200:
{
"success": true,
"data": {
"invitations": []
},
"meta": {
"siteId": "s_demo"
}
}
POST /api/sites/:siteId/invitations
Invites somebody to this one site; the link is in the answer, once.
Who: A person signed in with admin on the site. Never a key.
Body:
email, text, requiredrole, one ofowner,editor,viewer, requiredidentity, true or false
DELETE /api/sites/:siteId/invitations/:invitationId
Takes an invitation back.
Who: A person signed in with admin on the site. Never a key.
POST /api/invitations/lookup
What an invitation is for, for the page its link opens.
Who: Anybody.
Body:
token, text, required
POST /api/invitations/accept
Uses an invitation: by the account signed in, or by a new one with a password.
Who: Anybody.
Body:
token, text, requiredpassword, textname, text
The audit log
GET /api/teams/:teamId/audit
The team's log of who gave whom what, and who read identities, newest first.
Who: A person signed in who owns the team. Never a key.
Query:
limit, a whole numbercursor, textfrom, a whole numberto, a whole numberactor, textkind, one ofidentity,access,logtarget, text
Answered 200:
{
"success": true,
"data": {
"rows": [],
"accounts": {},
"next": null
},
"meta": {
"identity": true,
"limit": 5
}
}
GET /api/sites/:siteId/audit
The same log for one site.
Who: A session or a key with admin on the site.
Query:
limit, a whole numbercursor, textfrom, a whole numberto, a whole numberactor, textkind, one ofidentity,access,logtarget, text
Answered 200:
{
"success": true,
"data": {
"rows": [
{
"siteId": "s_demo",
"ts": 1790856000000,
"actor": {
"kind": "session",
"id": "u_example1",
"email": "mira@quillmoor.example"
},
"action": "read:identity",
"route": "GET /api/sites/:siteId/users/:userId/presence",
"fields": [
"userId"
],
"target": "cust_1042",
"id": "5",
"kind": "identity"
},
{
"siteId": "s_demo",
"ts": 1790856000000,
"actor": {
"kind": "session",
"id": "u_example1",
"email": "mira@quillmoor.example"
},
"action": "read:identity",
"route": "GET /api/sites/:siteId/users/:userId",
"fields": [
"traits",
"userId"
],
"target": "cust_1042",
"id": "4",
"kind": "identity"
},
{
"siteId": "s_demo",
"ts": 1790856000000,
"actor": {
"kind": "session",
"id": "u_example1",
"email": "mira@quillmoor.example"
},
"action": "read:identity",
"route": "GET /api/sites/:siteId/visitors/:visitorId",
"fields": [
"traits",
"userId"
],
"target": "u:cust_1042",
"id": "3",
"kind": "identity"
}
],
"accounts": {
"u_example1": {
"email": "mira@quillmoor.example",
"name": "Mira Okafor"
}
},
"next": "cursor_example1"
},
"meta": {
"identity": true,
"limit": 5
}
}
Alerts (Chokh Pro)
GET /api/sites/:siteId/ee/alerts
The site's alerts and where each one sends.
Who: A session or a key with read:stats on the site.
Chokh Pro: the alerts feature.
POST /api/sites/:siteId/ee/alerts
Creates an alert: a condition on a number, and the email, Telegram chat or webhook it goes to.
Who: A session or a key with admin on the site.
Chokh Pro: the alerts feature.
Body:
name, text, requiredcondition, an object, requiredchannels, a list of an object, required
DELETE /api/sites/:siteId/ee/alerts/:alertId
Deletes an alert.
Who: A session or a key with admin on the site.
Chokh Pro: the alerts feature.
POST /api/sites/:siteId/ee/alerts/:alertId/test
Sends an alert's message now, to check where it goes.
Who: A session or a key with admin on the site.
Chokh Pro: the alerts feature.
Digests (Chokh Pro)
GET /api/sites/:siteId/ee/digests
The site's scheduled email digests.
Who: A session or a key with read:stats on the site.
Chokh Pro: the digests feature.
POST /api/sites/:siteId/ee/digests
Schedules a digest by email, daily or weekly, with the same numbers in an attached PDF.
Who: A session or a key with admin on the site.
Chokh Pro: the digests feature.
Body:
cadence, one ofdaily,weekly, requiredto, a list of text, requiredhour, a whole numberweekday, a whole number
DELETE /api/sites/:siteId/ee/digests/:digestId
Stops a digest.
Who: A session or a key with admin on the site.
Chokh Pro: the digests feature.
POST /api/sites/:siteId/ee/digests/:digestId/send
Sends a digest now.
Who: A session or a key with admin on the site.
Chokh Pro: the digests feature.
More than one team (Chokh Pro)
POST /api/ee/teams
Creates a team, owned by whoever creates it.
Who: A person signed in who owns a team. Never a key.
Chokh Pro: the teams feature.
Body:
name, text, required
DELETE /api/ee/teams/:teamId
Deletes a team that holds no site.
Who: A person signed in who owns the team. Never a key.
Chokh Pro: the teams feature.
PUT /api/ee/sites/:siteId/team
Moves a site to another team the caller owns.
Who: A person signed in who owns the team. Never a key.
Chokh Pro: the teams feature.
Body:
teamId, text, requiredrevokeKeys, true or false
Single sign-on (Chokh Pro)
GET /api/ee/oidc
Whether single sign-on is on, for the sign-in page.
Who: Anybody.
Chokh Pro: the oidc feature.
GET /api/ee/oidc/start
Sends the browser to the identity provider to sign in.
Who: Anybody.
Chokh Pro: the oidc feature.
GET /api/ee/oidc/callback
Where the provider sends the browser back; signs the person in.
Who: Anybody.
Chokh Pro: the oidc feature.
Query:
code, textstate, texterror, text
POST /api/ee/oidc/invite
Uses an invitation by signing in with the provider.
Who: Anybody.
Chokh Pro: the oidc feature.
Body:
token, text, required
POST /api/ee/oidc/link
Connects the account signed in to an identity at the provider.
Who: A person signed in. Never a key.
Chokh Pro: the oidc feature.
GET /api/ee/oidc/identity
Whether the account signed in is connected, and to what.
Who: A person signed in. Never a key.
DELETE /api/ee/oidc/identity
Disconnects it, unless it is the account's only way in.
Who: A person signed in. Never a key.
Checking a licence (Chokh Pro)
GET /api/sites/:siteId/ee/ping
Answers only when the licence key covers paid features: a way to check a key works.
Who: A session or a key with read:stats on the site.
Chokh Pro: the ee.ping feature.