Reference

API and metrics

Use Heimnull's REST API with API tokens, read its OpenAPI description, scrape Prometheus metrics, and check health from outside.

Everything the web interface does goes through Heimnull’s REST API, under /api/ on the web port. Scripts can use it with an API token.

Authentication

API tokens (Configure → Users → API tokens) are sent as a bearer token: Authorization: Bearer <token>. Each has a role (viewer, operator or admin) and an optional expiry. See Users and API tokens.
Sessions: the web interface’s cookie. Requests that change something also need the session’s CSRF token in an X-CSRF-Token header; API tokens don’t.

Nothing is public except the login page’s three operations. Every other operation, the live WebSocket, the OpenAPI description and the metrics need a login or a token, and each operation requires a minimum role.

curl -H "Authorization: Bearer $HN_TOKEN" "http://heimnull.example.net/api/attacks?state=active"

Request and response bodies are JSON. Responses carry Cache-Control: no-store.

The OpenAPI description

The API is described in OpenAPI 3.1, generated from the code, so it always matches the server you’re running:

/api/openapi.json: the description;
/api/docs: browsable documentation of every operation, its parameters, responses and minimum role.

Both need a login: open /api/docs in a browser where you’re signed in.

Useful operations

Operation	Role
`GET /api/attacks?state=active`	Viewer	Active attacks
`GET /api/mitigations`	Viewer	Mitigations
`POST /api/mitigations/preview`	Operator	What a mitigation would announce
`POST /api/mitigations`	Operator	Mitigate an address (with a reason)
`POST /api/mitigations/{id}/withdraw`	Operator	Withdraw a mitigation
`POST /api/mitigations/halt`	Operator	Emergency withdraw-all
`GET /api/healthz`	Viewer	Health of PostgreSQL, ClickHouse and the collector
`GET /api/metrics`	Viewer	Prometheus metrics
`GET /api/config/export`	Admin	The configuration bundle
`GET /api/support/bundle`	Admin	A support file
`GET /api/license`	Viewer	The license state

See /api/docs for the full list and their parameters.

Health and metrics

GET /api/healthz reports PostgreSQL, ClickHouse and the flow collector. Use it, with a viewer token, from your monitoring.
Docker health checks: every container has one; sudo docker compose ps shows them.

Prometheus: GET /api/metrics serves the collector’s metrics (ingest per exporter, the Go runtime, the process). Create a viewer API token and scrape with it:

scrape_configs:
  - job_name: heimnull
    metrics_path: /api/metrics
    authorization:
      credentials: <token>
    static_configs:
      - targets: ['heimnull.example.net:80']

Command line

Run these on the server, in /opt/heimnull:

Command	What it does
`sudo docker compose exec heimnull heimnull version`	The running version
`sudo docker compose exec heimnull api reset-password <user>`	A new random password for a user, printed once. Re-enables the account, ends its sessions, and is recorded in the audit log
`sudo docker run --rm registry.heimnull.com/heimnull:latest env-template`	Prints a new `.env` with fresh secrets, sized for this machine, and checks the machine