API reference
Every piece of data Clientlog holds is reachable over HTTP. The CLI, the dashboard and the digest all read the same endpoints.
Base URL and authentication
https://api.dev.clientlog.bayis.co.uk/v1
Requests carry a Cognito ID token in the Authorization header. The CLI
obtains and stores one:
clientlog login you@example.com
cat ~/.clientlog/auth.json
curl -H "Authorization: $TOKEN" \
"https://api.dev.clientlog.bayis.co.uk/v1/sessions?origin=https://example.com&project=myapp/home"
Most endpoints require origin and project as query parameters. They scope
every request, and a token grants access only to projects registered against
its account.
The event ingestion endpoint is the exception: POST /event is
unauthenticated, because it is called from browsers.
Endpoints
Ingestion
| Method | Path | Description |
|---|---|---|
| POST | /event |
Record one event. Unauthenticated. |
Sessions
| Method | Path | Description |
|---|---|---|
| GET | /sessions |
Session identifiers for a project, newest first. |
| GET | /sessions/{id} |
Full session summary. |
| GET | /sessions/{id}/events |
Enriched events for one session, in order. |
| GET | /sessions/{id}/attributes |
Attributes extracted by attribution rules. |
Events
| Method | Path | Description |
|---|---|---|
| GET | /events |
Raw events as received. |
| GET | /events/enriched |
Events with browser, location and query fields. |
| GET | /events/actions |
Distinct action names and when each was last seen. |
/events/actions is the instrumentation coverage check: an action missing
from it is not being emitted.
Projects
| Method | Path | Description |
|---|---|---|
| GET | /users/projects |
Projects registered to the account. |
| GET | /projects/overview |
Stored overviews, the digest data queryable on demand. |
Rules
| Method | Path | Description |
|---|---|---|
| GET | /rules/ |
Rules for a project. |
| GET | /rules/{rule_id} |
One rule. |
| POST | /rules |
Create or update a rule. |
| DELETE | /rules/{rule_id} |
Disable a rule. |
| POST | /rules/test |
Evaluate rules against supplied sessions. |
POST /rules/test takes sessions and a rules document and returns match
results without writing anything. It backs clog test.
Tags
| Method | Path | Description |
|---|---|---|
| GET | /tags |
Distinct tags for a project with last-seen times. |
| GET | /tags/{tag} |
Tagged sessions within a time range. |
Triggers
| Method | Path | Description |
|---|---|---|
| POST | /trigger/aggregation |
Aggregate sessions for a window. |
| POST | /trigger/notification |
Build and send a digest for a window. |
| POST | /trigger/transitions |
Compute a transition matrix. |
| POST | /trigger/classification |
Reclassify named sessions. |
Triggers are asynchronous. The response confirms the job was dispatched.
Status
| Method | Path | Description |
|---|---|---|
| GET | /status/health |
Current pipeline health. |
| GET | /status/health/history |
Recorded health checks. |
Time and windows
Timestamps are milliseconds since the Unix epoch, UTC, throughout. Endpoints
accepting a window take window_start and window_end in the same form.
Full specification
The machine-readable specification is generated from the API source at build time and published at /openapi.json. Use it to generate a client in any language.