API Reference

Authentication

Every endpoint marked "authenticated" expects a JWT bearer token in the request header:

curl -H "Authorization: Bearer <token>" http://<host>:8008/api/system | jq

Two ways to obtain the token:

• API tokens (recommended for integrations). Long-lived tokens minted from Settings → Security → API Tokens in the dashboard. Each token is named, can be revoked individually, and is what you should hand to Home Assistant / Homepage / Grafana / n8n.
• Login flow (short-lived JWT). POST /api/auth/login with a username, password and TOTP token if 2FA is enabled. The returned JWT is short-lived and refreshed by the dashboard automatically; useful for ad-hoc scripts that authenticate as a human user.

The auth flow, password policy, 2FA setup, audit log and TLS configuration all live in Access & Authentication.

Conventions

• All requests and responses are JSON unless explicitly noted (log download is plain text, /api/prometheus is text/plain in the OpenMetrics format, task log is plain text).
• Successful mutating endpoints return {"success": true, ...}. Error responses use a non-2xx HTTP status with {"success": false, "error": "<reason>"}.
• List endpoints accept optional limit, offset, since and category-specific filters via query string.
• Time fields are returned as Unix epoch seconds or ISO-8601 with explicit timezone, never as locale strings.

System & hardware

Health Monitor

Response shapes and the semantics of the categories live in Health Monitor.

Storage

Network

VMs & containers

Backups

Logs, tasks, events

Notifications & AI

The dispatch pipeline, channel walk-throughs and AI rewriter setup live in Notifications and AI Assistant.

Security (read)

ProxMenux integration

Prometheus metrics

ProxMenux Monitor exposes a Prometheus-format scrape endpoint at GET /api/prometheus (authenticated) returning OpenMetrics-format text. Every metric is labelled with node="<hostname>" and carries an explicit timestamp so it ingests cleanly into Prometheus, VictoriaMetrics, Mimir or any compatible TSDB.

Exported metrics

Prometheus scrape config

The endpoint requires authentication. Pass the API token as a bearer header in your Prometheus scrape config:

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: 'proxmenux'
    metrics_path: /api/prometheus
    scheme: https              # or http if TLS isn't enabled in ProxMenux
    scrape_interval: 30s
    authorization:
      type: Bearer
      credentials: '<your-api-token>'
    static_configs:
      - targets:
          - 'pve01.lan:8008'
          - 'pve02.lan:8008'
          - 'pve03.lan:8008'

Putting it together

For end-to-end recipes wiring these endpoints into Home Assistant sensors, Homepage cards, Grafana dashboards, n8n flows and other tools, see the dedicated Integrations page — it walks through the typical setup for each platform with copy-paste configuration. This page stays focused on the catalogue itself.

Where to next

• Access & Authentication — minting tokens, the audit log, the optional Fail2Ban jail, TLS configuration.
• Notifications — what each event type carries in data when you call /api/notifications/send.
• AI Assistant — how /api/notifications/test-ai and /api/notifications/provider-models are wired.
• Health Monitor — the response shape of /api/health/* and the semantics of the ten categories.