DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

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

CredentialPrefixIssued by
API keydgk_…POST /v1/apikeys (admin) or the settings UI — secret shown once
Session tokendgs_…POST /v1/auth/login
POST/v1/auth/login
> {"username":"admin","password":"…"}
< 200 {"token":"dgs_…","name":"admin","role":"admin"}

Roles & permissions

RoleCan ingestCan readAdmin
writerYES——
reader—YES + metrics—
adminYESYESYES + /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

POST /v1/logsWRITER+
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 fieldTypeNotes
servicestringRequired — primary grouping key
messagestringRequired
levelstringdebug|info|warn|error|fatal — synonyms normalized, default info
tsRFC3339 | epoch s/msDefault: server receive time
hoststringOptional grouping key
attrsobjectArbitrary JSON — queryable via attr.*

Query

GET /v1/logsREADER+
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}
ParamFilter
from, toRFC3339 time window
levelComma list — error,fatal
min_levelSeverity floor — debug|info|warn|error|fatal
service, hostComma lists — match any
qCase-insensitive substring on message
attr.<key>Exact match on JSON attrs — dots navigate nesting (attr.http.status=500)
orderasc — default newest-first
limit, offsetPagination

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

GET /v1/logs/tailREADER+
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

EndpointRoleReturns
GET /v1/stats?window=1h&bucket=1mreader+{total, per_level, per_service, series} — buckets: 10s|30s|1m|5m|15m|1h, window is a Go duration (15m, 1h)
GET /v1/servicesreader+{services:[…]} distinct names
GET /v1/metricsreader+{queued, written, dropped, flushes, last_error}
GET /v1/systemreader+{uptime_s, go:{version,goroutines,mem_alloc,mem_sys}, storage, ingest}
GET /v1/auth/meany credential{name, role, via}
POST /v1/auth/logoutany credentialRevokes the session token
GET /healthznone200 ok — liveness probe

Admin ADMIN ROLE

EndpointBehaviour
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

StatusMeaning
400Malformed body / rejected SQL — {"error":"…"}
401Missing or bad credential — browser flows redirect to /sign-in
403Role lacks the permission (e.g. reader → /v1/sql)
409Conflict (e.g. removing the last enabled admin)
429 / 5xxTransient — SDKs retry with backoff

Error bodies are {"error":"…"}. UI pages (/, /settings) live outside this reference — see the docs overview.