API reference
Auth is either the Better Auth session cookie (web UI) or
Authorization: Bearer kl_… (project API keys). Session requests to
project-scoped routes pass ?project=<id>; API keys are bound to their project
and enforce their ingest / query scopes.
Browser sign-in, sign-out, and password changes are served by Better Auth under
/api/auth/*. Public self-signup is disabled — administrators create accounts.
Auth & workspace
Section titled “Auth & workspace”| Route | Method | What it does |
|---|---|---|
/api/auth/sign-in/email |
POST |
Sign in — sets the session cookie |
/api/auth/sign-out |
POST |
Sign out |
/api/auth/get-session |
GET |
Current Better Auth session |
/api/auth/change-password |
POST |
Change your password |
/v1/me |
GET |
Current user + permissions |
/v1/projects |
GET/POST |
List / create projects |
/v1/projects/:id |
DELETE |
Delete a project and all its data |
/v1/users |
GET/POST |
List / create users (admin) |
/v1/users/:id |
PATCH/DELETE |
Change role / delete user (admin) |
/v1/projects/:id/keys |
GET/POST |
List / create API keys for a project |
/v1/keys/:id |
DELETE |
Revoke a key (requires ?project=) |
/v1/projects/:id/members |
GET/POST |
List / assign project members (admin) |
/v1/projects/:id/members/:userId |
DELETE |
Remove a project member (admin) |
/v1/system/status |
GET |
Operational diagnostics — retention, monitors, counts (admin) |
| Route | Method | What it does |
|---|---|---|
/v1/events |
POST |
Ingest a batch — NDJSON or JSON, ≤ 8 MB, ≤ 10,000 events |
/v1/events |
GET |
Query events. Params: q, from, to (epoch ms), limit (≤ 1000), cursor |
/v1/histogram |
GET |
Counts per level per bucket. Params: from, to, buckets (≤ 240) |
/v1/services |
GET |
Known services with event counts |
/v1/stream |
GET |
SSE live tail. Params: q — cookie auth, plus key/token for headerless clients |
/healthz |
GET |
Health check (no auth) |
Monitors & alerts
Section titled “Monitors & alerts”| Route | Method | What it does |
|---|---|---|
/v1/monitors |
GET/POST |
List / create monitors (session only — keys can’t manage them) |
/v1/monitors/:id |
PATCH/DELETE |
Update / delete a monitor |
/v1/monitors/:id/test |
POST |
Send a test notification through every channel |
/v1/alerts |
GET |
Alert history, latest first |
Pagination
Section titled “Pagination”GET /v1/events returns events newest-first plus a nextCursor (the id of
the last row returned) when more may exist. Request the next page with
cursor=<nextCursor>:
curl "http://localhost:8080/v1/events?project=1&q=level:error&limit=500&cursor=84021" \ -H "Authorization: Bearer kl_…"Ingest responses
Section titled “Ingest responses”{ "accepted": 1998, "rejected": 2, "errors": ["missing message"] }Bad lines are counted and (up to three) reported — the rest of the batch still lands.