LABYRINTHDNS

REST API

Most /api/* endpoints require JWT authentication. Browsers authenticate via the labyrinth_token HttpOnly cookie set at login; programmatic clients send Authorization: Bearer <token>. Public endpoints in web mode include auth/setup, system health and version — plus /dns-query when DoH is enabled.

Endpoints

MethodPathDescription
POST/api/auth/loginLog in with your username and password; returns a JWT
GET/api/auth/meCurrent user info
GET/api/statsReal-time statistics
GET/api/stats/timeseries?window=5mTime-bucketed stats for charts
WS/api/queries/streamLive DNS query WebSocket stream
GET/api/queries/recent?limit=50Recent queries
GET/api/cache/statsCache statistics
GET/api/cache/lookup?name=X&type=ACache entry lookup
POST/api/cache/flushFlush the entire cache
DELETE/api/cache/entry?name=X&type=ADelete a cache entry
GET/api/configRunning config (passwords redacted)
POST/api/auth/change-passwordChange admin password
GET/api/blocklist/statsBlocklist statistics
GET/api/blocklist/listsConfigured blocklist sources
POST/api/blocklist/refreshRefresh all blocklists
POST/api/blocklist/blockQuick-block a domain
POST/api/blocklist/unblockUnblock a domain
GET/api/blocklist/check?domain=XCheck whether a domain is blocked
GET/api/system/healthHealth check
GET/api/system/versionVersion info
GET/api/system/update/checkCheck for updates
POST/api/system/update/applyApply an available update
GET/api/setup/statusCheck whether the setup wizard is needed
POST/api/setup/completeComplete the setup wizard
GET/api/zabbix/itemsZabbix metric key discovery
GET/api/zabbix/item?key=XSingle Zabbix metric value
GET/metricsPrometheus metrics
GET / POST/dns-queryDNS-over-HTTPS endpoint (RFC 8484)

Calling it from a script

# 1) Log in — POST /api/auth/login with your admin credentials as JSON —
#    the response contains the token field.
# 2) Use it:
curl -s http://127.0.0.1:9153/api/stats \
  -H "Authorization: Bearer $TOKEN"

Prometheus /metrics is served on server.metrics_addr only when web.enabled is false — otherwise it lives behind the authenticated web server.

Source: the project README.