REST API

obserae exposes an HTTP API you can drive from scripts, supervision systems and CI. It is the same server that renders the Web GUI: the browser pages return HTML, while every path under /api/… returns JSON and every path under /ws/… is a WebSocket. This page is the reference for the JSON API — how to authenticate, what each endpoint does, and copy-paste curl examples.

• Base URL — the web server binds 127.0.0.1:8080 by default (web.bind in configuration). All examples below use http://127.0.0.1:8080; substitute your host and port.
• Content type — send Content-Type: application/json on requests with a body; responses are always application/json.
• Read vs. write — read endpoints (GET) run on a dedicated reader pool and never block ingestion; mutations (POST/PATCH/DELETE) serialise on the writer.
• Machine-readable spec — a full OpenAPI 3.1 description of every endpoint ships alongside this page as openapi.yaml. Import it into Postman/Insomnia, generate a client, or render it with Swagger UI / Redoc.

Authentication

Every /api/… endpoint requires an API token, sent as a Bearer credential:

Authorization: Bearer obs_…

The only exceptions are the two public probes documented below (GET /healthz and GET /api/protocols).

Minting a token

A token is minted for a user and inherits that user’s permissions. The secret is shown once at creation — copy it then; obserae only stores a hash.

• In the GUI — Identity & Access → Users → + New token. See Web GUI › API tokens.

• From the CLI — over the admin socket (the secret is printed once):

  obserae-cli user token-add --name ci --user alice
  obserae-cli user token-ls
  obserae-cli user token-rm <TOKEN_ID>   # revoke
  

Give the token’s owner the least privilege it needs. A supervision system that only polls /api/status, for example, should own a token whose user is in the built-in monitoring group (just monitoring:read) and nothing else.

No CSRF, no MFA for tokens

Bearer-token clients are exempt from CSRF and from the MFA enrollment gate — a script never needs a CSRF header or a second factor. (CSRF only applies to the browser, which authenticates with a session cookie.) See authentication for how humans sign in.

Permissions

Authorization is enforced per route. If the token’s user lacks the required permission, the call fails 403 (see Errors). The catalogue:

Built-in groups bundle these: admin (everything), analyst (read + query + rule authoring), auditor (read-only, incl. auditlog:read), and monitoring (only monitoring:read). Create a custom group to grant an exact subset.

Errors

Machine paths (/api/…, /ws/…) always answer failures with a JSON body:

NFQL compile errors are not HTTP errors. POST /api/query returns 200 OK with an error field populated (see below) so a positioned compile error and a result share one response shape.

Health & status

GET /api/status returns byte-for-byte the same payload as obserae-cli status — one shared snapshot for both surfaces. It is the authenticated counterpart to the public /healthz probe.

curl -H "Authorization: Bearer obs_…" http://127.0.0.1:8080/api/status

{
  "version": "0.27.0",
  "commit": "7a8e5e4",
  "started_at": "2026-07-07T08:00:00Z",
  "uptime_seconds": 3600,
  "timestamp": "2026-07-07T09:00:00Z",
  "data_version": 10,
  "data_version_target": 10,
  "flows":       { "total": 1284003, "per_sec": 412.5 },
  "cartography": { "networks": 12, "hosts": 340, "services": 28, "groups": 9 },
  "sessions":    { "active": 1204, "half_open": 33, "closed": 98120,
                   "open_live": 1237, "open_max": 200000, "fill_pct": 0.6,
                   "pressure": "ok", "evicted": 0,
                   "dropped_closes": 0, "dropped_emits": 0 },
  "rules":       { "total": 42, "expansions": 1180, "alert_rules_active": 7 },
  "coverage":    { "rate_1h": 0.98, "violations_closed_1h": 3 },
  "alerts":      { "total": 15, "by_status": { "open": 4, "acknowledged": 11 },
                   "by_severity": { "high": 2, "medium": 9, "low": 4 },
                   "last_1h": 1, "last_24h": 6 },
  "ingestion":   { "files_written": 8123, "records_ingested": 1284003,
                   "last_flush_at": "2026-07-07T08:59:57Z",
                   "avg_flush_ms": 41.2, "max_flush_ms": 190 },
  "storage":     { "db_path": "data/obserae.duckdb", "db_size_bytes": 12288,
                   "disk_free_bytes": 51230000000, "disk_total_bytes": 100000000000 },
  "runtime":     { "heap_inuse_bytes": 84934656, "goroutines": 61,
                   "udp_drops": 0, "matcher_cursor_lag_seconds": 1 },
  "audit":       { "integrity": "verified", "breaks": 0 },
  "live_metrics_available": true
}

When the web GUI is disabled (web.enabled: false) the producer-derived blocks (per_sec, coverage, runtime, ingestion timing, audit verdict) stay at zero and live_metrics_available is false; the always-available counts are still filled.

NFQL query execution

Run NFQL queries — the same engine the Investigation page uses. Compiled once, executed on the read-only pool with a row cap and timeout.

Executing a query

POST /api/query with a JSON body:

curl -X POST http://127.0.0.1:8080/api/query \
  -H "Authorization: Bearer obs_…" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "FROM sessions | LAST 3600 | STATS COUNT(*) AS n BY server_port | SORT n DESC | HEAD 5",
    "args": []
  }'

Response (a result or a compile error, always 200 OK):

{
  "columns": [
    { "name": "server_port", "type": "INTEGER" },
    { "name": "n",           "type": "BIGINT"  }
  ],
  "rows": [
    [443, 8123],
    [53, 4102],
    [22, 512]
  ],
  "compile_ms": 3,
  "exec_ms": 41,
  "row_count": 3,
  "truncated": false
}

On a bad query the same shape carries the message instead:

{ "columns": null, "rows": null, "error": "sem: 1:18: unknown column \"prtocol\"" }

truncated: true means the row cap was hit — narrow the query with HEAD or a tighter window. Saved queries are managed under /api/queries (list/search with sessions:read; create/update/delete with nfql:execute).

Endpoint reference by domain

All paths below are under the base URL and require the listed permission. GET returns JSON; mutations take a JSON body and return the updated resource or a status envelope. {…} marks a path parameter.

Cartography — the network map

cartography:read for GET, cartography:write for mutations. Mutations also require the edit lock; a non-holder gets 423 Locked.

Flow-matrix rules

rules:read / rules:write. See rules.

Detection (alerting) rules & rule sets

alerting:read / alerting:write. See alerting and rulesets.

Anomaly detection

alerting:read / alerting:write. See anomaly detection.

Detection alerts

alerts:read for GET, alerts:ack for mutations.

# List, then acknowledge one alert
curl -H "Authorization: Bearer obs_…" http://127.0.0.1:8080/api/alerts
curl -X POST http://127.0.0.1:8080/api/alerts/42/status \
  -H "Authorization: Bearer obs_…" -H "Content-Type: application/json" \
  -d '{"status":"acknowledged"}'

Sessions

Enrichment & exporters

sources:manage. See enrichment and exporters.

Devices (OPNsense)

devices:manage. See sources.

Outputs

outputs:manage. See outputs.

Lifecycle — storage, retention, backup

system:manage. See lifecycle.

Configuration I/O

See CLI › config for the equivalent bundle operations.

Audit log

auditlog:read. See verify for the tamper-evidence scheme.

Identity & access administration

users:manage unless noted; LDAP/OIDC and login security need auth:manage. The account self-service endpoints require only an authenticated token (any user managing their own MFA/password).

WebSockets

Real-time streams for the GUI, also usable by a client that keeps a socket open. Connect with the same Bearer token; an unauthenticated handshake gets a 401.

See also

• Web GUI — where to mint tokens and manage permissions.
• Authentication — how humans sign in (local, LDAP, OIDC).
• NFQL — the query language used by POST /api/query.
• CLI — the admin socket, which mirrors many of these operations.

Browse the interactive API reference. Every endpoint, schema and example rendered from the OpenAPI spec: /docs/api-reference/.