"description":"HTTP endpoints exposed by ProxMenux Monitor for Home Assistant, Homepage, Grafana, Prometheus, n8n and custom dashboards. Read state and invoke documented write operations such as VM control, backup submission, notification dispatch and alert acknowledgement.",
"description":"HTTP endpoints for reading state and invoking documented actions on ProxMenux Monitor: Home Assistant sensors, Homepage cards, Grafana dashboards, Prometheus collection, n8n flows and custom scripts. Includes endpoint categories, exported metrics and curl examples.",
"body":"This page lists the endpoints we expect external integrations to use — read-only data export across every part of the Monitor, plus the small set of write operations that automations legitimately need (trigger a backup, send a custom notification, acknowledge an alert). The whole API runs from the same Flask process that serves the dashboard UI on TCP <strong>8008</strong>; bind address and TLS are configured in <link>Access & Authentication</link>."
"<strong>API tokens (recommended for integrations).</strong> Tokens valid for 365 days, created under <strong>Security → API Tokens</strong>. Each has a name and can be revoked individually. Use read_only for data collection and select full_admin only for integrations that need administrative actions.",
"<strong>Login flow (24-hour JWT).</strong> <code>POST /api/auth/login</code> with a username, password and TOTP token when required by 2FA. The returned session JWT expires after 24 hours; scripts must authenticate again when it expires."
"use":"Create a 365-day API token using an authenticated session. Body fields: <code>password, token_name?, totp_token?, scope?</code>. Password and any required TOTP are checked again. Scope defaults to read_only; full_admin must be selected explicitly. The secret is returned only once."
"Most endpoints use JSON. Downloads can return plain text, and <code>/api/prometheus</code> returns Prometheus text exposition format version 0.0.4 rather than OpenMetrics. Check the response type of the specific route.",
"Many write endpoints return <code>'{'\"success\": true, ...'}'</code>. Error formats vary; a common form is <code>'{'\"success\": false, \"error\": \"'<'reason'>'\"'}'</code>. Check both HTTP status and response fields: some authentication challenges return HTTP 200 with success false.",
"Query parameters vary by endpoint. Use <code>limit</code>, <code>offset</code>, <code>since</code> and category-specific filters only where the route supports them.",
"Time formats vary by endpoint: Unix timestamps, ISO-8601 strings and systemd-formatted dates all occur. Do not assume every time field has the same unit or an explicit timezone."
"intro":"The asynchronous system actions below start operations in transient systemd units. With authentication enabled, their write routes require <code>full_admin</code>; <code>read_only</code> tokens can poll <code>.../status</code>. Accepted starts return HTTP 202 with a state snapshot; poll the matching <code>.../status</code> for progress. Guest control and backup use different response contracts, described below.",
"concurrencyBody":"Starting a second run of the same system action returns HTTP 409 while it is active. Cancellation is available only for actions with a documented DELETE route, such as PVE update. Their state becomes <code>cancelled</code> and preserves timestamps. Terminal snapshots are kept in process memory and can be lost when the Monitor restarts.",
"use":"Reboot the Proxmox host. Fire-and-forget — the HTTP connection drops when systemd starts the shutdown sequence."
},
{
"endpoint":"/api/system/power/reboot/status",
"method":"GET",
"use":"State of the last / current reboot action."
},
{
"endpoint":"/api/system/power/shutdown",
"method":"POST",
"use":"Power off the Proxmox host. Useful as an effect wired to a UPS shutdown signal."
},
{
"endpoint":"/api/system/power/shutdown/status",
"method":"GET",
"use":"State of the last / current shutdown action."
},
{
"endpoint":"/api/system/pve-update/run",
"method":"POST",
"use":"Trigger the safe PVE update flow (the same one the Health Monitor's Update Now button and the shell menu run — delegates to update-pve-safe.sh)."
},
{
"endpoint":"/api/system/pve-update/status",
"method":"GET",
"use":"State of the last / current PVE update run."
},
{
"endpoint":"/api/system/pve-update",
"method":"DELETE",
"use":"Cancel a PVE update in progress (SIGTERM to the running script)."
"use":"Update ProxMenux using the installer for the configured stable or beta channel. It runs in its own systemd unit so the job can survive the proxmenux-monitor service restart performed by the installer."
"use":"Submit VM or LXC power control. Body field <code>action</code> accepts <code>start</code>, <code>stop</code>, <code>shutdown</code> or <code>reboot</code>. A successful response returns a confirmed PVE task; it does not mean the operation has completed. Poll the guest control-task endpoint for its outcome."
"use":"Create a vzdump backup of a VM or LXC. Body fields, all optional unless the defaults do not match the storage layout: <code>storage</code> (a PVE storage), <code>mode</code> (<code>snapshot</code>, <code>suspend</code> or <code>stop</code>), <code>compress</code> (<code>zstd</code>, <code>lzo</code>, <code>gzip</code> or <code>none</code>), <code>protected</code> (<code>true</code> or <code>false</code>), <code>notes</code> and <code>pbs_change_detection</code> (<code>default</code>, <code>legacy</code> or <code>data</code>). Returns the PVE task UPID."
"syncVsAsyncBody":"Host power, PVE update and ProxMenux self-update run in transient systemd units with a <code>.../status</code> endpoint. Only PVE update has the <code>DELETE</code> cancellation route listed here. VM/LXC control returns a PVE task that must be polled; backup returns a UPID for a background job. An accepted request is not completion. Authentication and scope requirements depend on the route.",
"haBody":"A <code>rest</code> sensor polls the state and a <code>rest_command</code> triggers the update. Wire both to a dashboard button and to any automation you like:",
"use":"Small health probe returning JSON with <code>status</code>, <code>timestamp</code> and <code>version</code>. Suitable for Uptime Kuma keyword checks; when authentication is enabled, the client must send the bearer header."
"use":"Full snapshot: categories, active errors, dismissed alerts and custom suppression settings. It uses background check results when less than six minutes old; otherwise, or on a forced refresh, it runs a fresh check."
"use":"Internal event stream — the same one that feeds notifications."
},
{
"endpoint":"/api/task-log/<upid>",
"method":"GET",
"use":"Plain-text complete log for one Proxmox task by UPID."
}
]
},
"notifications":{
"heading":"Notifications & AI",
"intro":"The dispatch pipeline, channel walk-throughs and AI rewriter setup live in <notifLink>Notifications</notifLink> and <aiLink>AI Assistant</aiLink>.",
"rows":[
{
"endpoint":"/api/notifications",
"method":"GET",
"use":"Recent notifications surfaced in the dashboard."
},
{
"endpoint":"/api/notifications/download",
"method":"GET",
"use":"Export notifications as text."
},
{
"endpoint":"/api/notifications/status",
"method":"GET",
"use":"Dispatcher status — whether the background thread is running, queue depth, last send."
},
{
"endpoint":"/api/notifications/settings",
"method":"GET",
"use":"Read the full notification config (channels, per-event toggles, AI rewriter, Display Name)."
},
{
"endpoint":"/api/notifications/history",
"method":"GET",
"use":"Dispatch history. Query: <code>?limit=&offset=&severity=&channel=</code>."
},
{
"endpoint":"/api/notifications/history",
"method":"DELETE",
"use":"Wipe the dispatch history table."
},
{
"endpoint":"/api/notifications/test",
"method":"POST",
"use":"Send a test notification to one channel. Body: <code>'{'\"channel\":\"telegram\"'}'</code>."
},
{
"endpoint":"/api/notifications/send",
"method":"POST",
"use":"Emit a custom event. Body: <code>'{'\"event_type\":\"custom\",\"severity\":\"WARNING\",\"title\":\"...\",\"body\":\"...\",\"data\":'{''}''}'</code>."
"use":"Detect which optional security tools (Fail2Ban, Lynis) are installed."
}
]
},
"proxmenuxIntegration":{
"heading":"ProxMenux integration",
"rows":[
{
"endpoint":"/api/proxmenux/update-status",
"method":"GET",
"use":"Whether ProxMenux Monitor has an update available, current and latest version."
},
{
"endpoint":"/api/proxmenux/installed-tools",
"method":"GET",
"use":"List of every ProxMenux post-install optimization currently registered on the host (from <code>/usr/local/share/proxmenux/installed_tools.json</code>)."
"use":"Source of the mapped post-install function, extracted from current host scripts or preserved legacy code. This is not a guaranteed snapshot of the exact code originally executed."
"intro":"The authenticated <code>GET /api/prometheus</code> endpoint returns Prometheus text exposition format version 0.0.4. Every metric includes <code>node=\"<hostname>\"</code> and an explicit timestamp. Collect it with Prometheus or another compatible time-series database.",
"perHostBody":"Each ProxMenux Monitor instance exports metrics for the host it runs on. In a cluster, point Prometheus at every node — the <code>node</code> label on every series lets you distinguish them in Grafana queries (<code>proxmox_vms_running'{'node=\"pve01\"'}'</code>)."
},
"puttingItTogether":{
"heading":"Putting it together",
"body":"For end-to-end recipes wiring these endpoints into Home Assistant sensors, Homepage cards, Grafana dashboards, n8n flows and other tools, see the dedicated <link>Integrations</link> page — it walks through the typical setup for each platform with copy-paste configuration. This page stays focused on the catalogue itself."
},
"whereNext":{
"heading":"Where to next",
"items":[
{
"label":"Access & Authentication",
"href":"/docs/monitor/access-auth",
"tail":" — minting tokens, the audit log, the optional Fail2Ban jail, TLS configuration."
},
{
"label":"Notifications",
"href":"/docs/monitor/notifications",
"tailRich":" — what each event type carries in <code>data</code> when you call <code>/api/notifications/send</code>."
},
{
"label":"AI Assistant",
"href":"/docs/monitor/ai-assistant",
"tailRich":" — how <code>/api/notifications/test-ai</code> and <code>/api/notifications/provider-models</code> are wired."
},
{
"label":"Health Monitor",
"href":"/docs/monitor/health-monitor",
"tailRich":" — the response shape of <code>/api/health/*</code> and the semantics of the ten categories."
