/// HTTP API REFERENCE
HTTP API.
Everything the SDKs call — plain JSON over HTTP. Ship logs with any
HTTP client; no SDK required. Base URL examples use
localhost:8080.
Authentication
Pass Authorization: Bearer <token> on every request
(except /healthz). Two credential types:
| Credential | Prefix | Issued by |
|---|---|---|
| API key | dgk_… | POST /v1/apikeys (admin) or the settings UI — secret shown once |
| Session token | dgs_… | POST /v1/auth/login |
> {"username":"admin","password":"…"}
< 200 {"token":"dgs_…","name":"admin","role":"admin"}
Roles & permissions
| Role | Can ingest | Can read | Admin |
|---|---|---|---|
writer | YES | — | — |
reader | — | YES + metrics | — |
admin | YES | YES | YES + /v1/sql |
Roles are disjoint by design: a writer key can ship logs but not read them; a reader key reads but cannot ingest. Issue separate keys per function.
Ingest
curl -X POST localhost:8080/v1/logs \
-H "authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
[-H 'content-encoding: gzip'] \
-d '[{"service":"api","level":"info","message":"listening :8080",
"host":"prod-1","attrs":{"region":"us-east"}}]'
< 202 {"accepted":1}
Body is a JSON array — up to 50,000 entries per POST. Gzip
bodies accepted via Content-Encoding: gzip.
| Entry field | Type | Notes |
|---|---|---|
service | string | Required — primary grouping key |
message | string | Required |
level | string | debug|info|warn|error|fatal — synonyms normalized, default info |
ts | RFC3339 | epoch s/ms | Default: server receive time |
host | string | Optional grouping key |
attrs | object | Arbitrary JSON — queryable via attr.* |
Query
curl "localhost:8080/v1/logs?service=api&min_level=warn&limit=100" \
-H "authorization: Bearer $TOKEN"
< 200 {"rows":[{"ts":"…","level":"error","service":"api","host":"prod-1",
"message":"…","attrs":"{\"region\":\"us-east\"}",
"ingested_at":"…"}], "count":100}
| Param | Filter |
|---|---|
from, to | RFC3339 time window |
level | Comma list — error,fatal |
min_level | Severity floor — debug|info|warn|error|fatal |
service, host | Comma lists — match any |
q | Case-insensitive substring on message |
attr.<key> | Exact match on JSON attrs — dots navigate nesting (attr.http.status=500) |
order | asc — default newest-first |
limit, offset | Pagination |
POST /v1/query accepts the same filters as a JSON body
({"levels":[],"services":[],"hosts":[],"q":"","attrs":{},
"min_level":"","from":"","to":"","order":"asc","limit":0,"offset":0})
— better for large attr sets that would bloat a URL.
Live tail — SSE
curl -N "localhost:8080/v1/logs/tail?min_level=warn" \
-H "authorization: Bearer $TOKEN" -H 'accept: text/event-stream'
data: {"ts":"…","level":"error","service":"api","message":"…",…}
data: {"ts":"…","level":"warn","service":"web","message":"…",…}
Same filter params as /v1/logs. Server-Sent-Events stream,
best-effort delivery — new matching rows until the connection closes.
Aggregates & introspection
| Endpoint | Role | Returns |
|---|---|---|
GET /v1/stats?window=1h&bucket=1m | reader+ | {total, per_level, per_service, series} — buckets: 10s|30s|1m|5m|15m|1h, window is a Go duration (15m, 1h) |
GET /v1/services | reader+ | {services:[…]} distinct names |
GET /v1/metrics | reader+ | {queued, written, dropped, flushes, last_error} |
GET /v1/system | reader+ | {uptime_s, go:{version,goroutines,mem_alloc,mem_sys}, storage, ingest} |
GET /v1/auth/me | any credential | {name, role, via} |
POST /v1/auth/logout | any credential | Revokes the session token |
GET /healthz | none | 200 ok — liveness probe |
Admin ADMIN ROLE
| Endpoint | Behaviour |
|---|---|
GET /v1/users | {users:[{username,role,created_at,disabled}]} |
POST /v1/users | {username,password,role} → 201 |
PATCH /v1/users/{name} | {role?,disabled?,password?} — can't edit own role/disabled |
DELETE /v1/users/{name} | 204 — can't delete self or last admin |
GET /v1/apikeys | {keys:[{id,name,prefix,role,created_at,last_used_at,disabled}]} |
POST /v1/apikeys | {name,role} → 201 {key, secret} — secret shown once |
DELETE /v1/apikeys/{id} | 204 |
POST /v1/sql | {"sql":"SELECT …"} → {columns,col_types,rows,truncated,elapsed_ms} |
/v1/sql is read-only: single statement, whitelisted
to SELECT, WITH, EXPLAIN,
DESCRIBE, SHOW, VALUES — capped at
5,000 rows and 30s.
Errors
| Status | Meaning |
|---|---|
400 | Malformed body / rejected SQL — {"error":"…"} |
401 | Missing or bad credential — browser flows redirect to /sign-in |
403 | Role lacks the permission (e.g. reader → /v1/sql) |
409 | Conflict (e.g. removing the last enabled admin) |
429 / 5xx | Transient — SDKs retry with backoff |
Error bodies are {"error":"…"}. UI pages
(/, /settings) live outside this reference —
see the docs overview.