hearthgate docs

Admin API and metrics

The dashboard uses the same REST API as scripts, on the same port. Its OpenAPI document is at /api/v1/openapi.json. Scripts authenticate with an API token created under Settings, Account, or with the admin token for scripts on the server itself:

TOKEN=$(sudo -u hearthgate hearthgate admin-token)
curl --cacert /var/lib/hearthgate/admin-tls/cert.pem \
  -H "Authorization: Bearer $TOKEN" https://localhost:7380/api/v1/status
Endpoint
GET /api/v1/statusRunning revision, listeners, upstream health and traffic rates, problems
GET /api/v1/state, PUT /api/v1/stateRead or replace the desired state (JSON)
POST /api/v1/state/validate, POST /api/v1/state/previewCheck a state, and see its diff against the running one
GET /api/v1/state/exportThe running state as TOML
GET /api/v1/revisions, GET /api/v1/revisions/{id}, GET /api/v1/revisions/{id}/diffHistory
POST /api/v1/revisions/{id}/rollbackRoll back
GET /api/v1/certificatesStored certificates and expiry
GET /api/v1/eventsLive updates as Server-Sent Events: status every 2 seconds and new log lines
GET /api/v1/logs, GET /api/v1/trafficThe last log lines, and requests per hour for 24 hours
GET, PUT /api/v1/settings/admin-accessWho can reach the dashboard
GET /api/v1/firewall, GET /api/v1/firewall/recentFirewall state, dropped packets, feeds and bans, and sources dropped in the last hour
POST /api/v1/firewall/confirmKeep a waiting firewall change (only over a connection opened after the change)
POST /api/v1/firewall/bans, DELETE /api/v1/firewall/bans/{address}Ban or unban an address
GET /api/v1/routerRouter port forwarding status
GET /api/v1/docker, GET /api/v1/docker/updatesManaged containers and stacks, and image update checks
POST /api/v1/docker/containers/{name}/restart, …/update, POST /api/v1/docker/stacks/{name}/updateRestart, or pull and recreate
GET /api/v1/docker/containers/{name}/logs, …/statsOutput (with tail and search) and resource use
POST /api/v1/notifications/testSend a test message with the given notification settings
GET /api/v1/vpnVPN state, devices with their last handshake and traffic, and the internal DNS names
POST /api/v1/vpn/peer-configKeys and configuration for a new device. Nothing is stored: add the returned public key to the state
/api/v1/auth/…, /api/v1/tokensLogin, password, two-factor login and API tokens
GET /metricsPrometheus metrics

Browser sessions also need the X-CSRF-Token header (from GET /api/v1/auth/session) on every request that changes something; token-authenticated requests don't.

Metrics

/metrics exposes, among others: hearthgate_upstream_healthy, hearthgate_upstream_active, hearthgate_upstream_connections_total, hearthgate_upstream_failures_total, sent and received bytes, hearthgate_http_responses_total by status class, hearthgate_http_local_responses_total, hearthgate_listener_open_connections, hearthgate_certificate_expiry_timestamp_seconds and hearthgate_revision. Set admin.metrics_without_token = true to let a Prometheus server on your LAN scrape it without the token.

Edit this page on GitHub Hearthgate 1.0