Skip to content

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.

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)
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

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>:

Terminal window
curl "http://localhost:8080/v1/events?project=1&q=level:error&limit=500&cursor=84021" \
-H "Authorization: Bearer kl_…"
{ "accepted": 1998, "rejected": 2, "errors": ["missing message"] }

Bad lines are counted and (up to three) reported — the rest of the batch still lands.