"description":"HTTP-Endpunkte von ProxMenux Monitor für Home Assistant, Homepage, Grafana, Prometheus, n8n und eigene Dashboards. Zustand abfragen und dokumentierte Änderungen anstoßen: VM-Steuerung, Sicherungen, Benachrichtigungen und Warnungsbestätigung.",
"ogDescription":"ProxMenux-Monitor-Endpunkte für Home Assistant, Homepage, Grafana, Prometheus, n8n und eigene Dashboards.",
"twitterTitle":"Proxmox-Monitor-API | ProxMenux",
"twitterDescription":"Endpunkte für Home Assistant, Homepage, Grafana, Prometheus, n8n und eigene Dashboards."
},
"header":{
"title":"API-Referenz",
"description":"HTTP-Endpunkte zum Lesen des Zustands und Aufrufen dokumentierter Aktionen: Home-Assistant-Sensoren, Homepage-Karten, Grafana-Dashboards, Prometheus-Erfassung, n8n-Abläufe und eigene Skripte. Mit Kategorien, exportierten Metriken und curl-Beispielen.",
"section":"ProxMenux Monitor"
},
"intro":{
"title":"Wofür diese Seite ist",
"body":"Diese Seite enthält Endpunkte für externe Integrationen: Datenabruf und Aktionen wie Sicherungen, eigene Meldungen und Warnungsbestätigung. Die API läuft im Flask-Prozess des Dashboards auf TCP <strong>8008</strong>. Bindeadresse und TLS beschreibt <link>Zugriff und Authentifizierung</link>."
},
"headerEndpoint":"Endpunkt",
"headerMethod":"Methode",
"headerUse":"Verwendung",
"auth":{
"heading":"Authentifizierung",
"intro":"Bei aktiver Authentifizierung erwarten geschützte Endpunkte ein JWT-Bearer-Token im Anfrageheader:",
"tokensIntro":"Zwei Möglichkeiten, das Token zu erhalten:",
"items":[
"<strong>API-Token, für Integrationen empfohlen.</strong> Sie gelten 365 Tage und entstehen unter <strong>Sicherheit → API-Token</strong>. Sie haben Namen und sind einzeln widerrufbar. read_only dient dem Datenabruf; full_admin wählen Sie nur für benötigte Verwaltungsaktionen.",
"<strong>Anmeldung, JWT für 24 Stunden.</strong> <code>POST /api/auth/login</code> mit Benutzername, Passwort und TOTP, falls 2FA dies verlangt. Das JWT läuft nach 24 Stunden ab; Skripte müssen sich danach erneut anmelden."
],
"flowLink":"Anmeldung, Passwörter, 2FA, Auditprotokoll und TLS erklärt <link>Zugriff und Authentifizierung</link>.",
"rows":[
{
"endpoint":"/api/auth/login",
"method":"POST",
"use":"Anfragefelder (Schema): <code>'{'\"username\",\"password\",\"totp_token?\"'}'</code>. Liefert ein JWT für 24 Stunden."
},
{
"endpoint":"/api/auth/api-tokens",
"method":"GET",
"use":"Listen Sie API-Token auf (nur Metadaten - Namen, Präfixe, Daten; niemals das eigentliche Geheimnis)."
},
{
"endpoint":"/api/auth/generate-api-token",
"method":"POST",
"use":"Erstellt mit einer angemeldeten Sitzung ein API-Token für 365 Tage. Felder: <code>password, token_name?, totp_token?, scope?</code>. Passwort und erforderliches TOTP werden erneut geprüft. scope ist standardmäßig read_only; full_admin muss ausdrücklich gewählt werden. Der geheime Wert erscheint nur einmal."
},
{
"endpoint":"/api/auth/api-tokens/<id>",
"method":"DELETE",
"use":"Widerruf eines bestimmten API-Tokens durch seine ID."
}
]
},
"conventions":{
"heading":"Konventionen",
"items":[
"Die meisten Endpunkte verwenden JSON. Downloads können Klartext liefern; <code>/api/prometheus</code> liefert das Prometheus-Textformat 0.0.4 statt OpenMetrics. Prüfen Sie den Antworttyp der jeweiligen Route.",
"Viele Schreiboperationen liefern <code>'{'\"success\": true, ...'}'</code>. Fehlerformate variieren; häufig ist <code>'{'\"success\": false, \"error\": \"'<'reason'>'\"'}'</code>. Prüfen Sie HTTP-Status und Felder: manche Authentifizierungsanforderungen liefern HTTP 200 mit success false.",
"Abfrageparameter hängen vom Endpunkt ab. Verwenden Sie <code>limit</code>, <code>offset</code>, <code>since</code> und Kategoriefilter nur, wenn die Route sie unterstützt.",
"Zeitformate variieren: Unix-Zeitstempel, ISO-8601-Zeichenfolgen und systemd-Datumsformate kommen vor. Nicht jedes Feld hat dieselbe Einheit oder eine ausdrückliche Zeitzone."
]
},
"system":{
"heading":"System und Hardware",
"rows":[
{
"endpoint":"/api/system",
"method":"GET",
"use":"Aktuelle Werte für CPU, RAM, Swap, Betriebszeit und Last."
"use":"Zeitreihen der CPU- und Package-Temperaturen."
},
{
"endpoint":"/api/gpu/<slot>/realtime",
"method":"GET",
"use":"Aktuelle GPU-Metriken von NVIDIA, Intel und AMD je PCI-Slot."
}
]
},
"actions":{
"heading":"Systemaktionen",
"intro":"Diese asynchronen Systemaktionen laufen in temporären systemd-Units. Bei aktiver Authentifizierung verlangen ihre Schreibzugriffe <code>full_admin</code>; <code>read_only</code> darf <code>.../status</code> abfragen. Angenommene Starts liefern HTTP 202 mit Zustand; <code>.../status</code> zeigt den Fortschritt. Gaststeuerung und Sicherungen haben andere Antworten, siehe unten.",
"shapeTitle":"Gemeinsames Antwortformat",
"shapeIntro":"Asynchrone Systemaktionen teilen das folgende JSON-Zustandsobjekt. Gaststeuerung und Sicherungen antworten in anderen Formaten:",
"concurrencyTitle":"Parallele Ausführung und Abbruch",
"concurrencyBody":"Ein zweiter Start derselben laufenden Aktion liefert HTTP 409. Abbruch gibt es nur mit dokumentierter DELETE-Route, etwa beim PVE-Update. Der Zustand wird <code>cancelled</code>, Zeitstempel bleiben erhalten. Endzustände liegen im Prozessspeicher und können beim Monitor-Neustart verloren gehen.",
"rows":[
{
"endpoint":"/api/system/power/reboot",
"method":"POST",
"use":"Startet den Neustart des Proxmox-Hosts. Die HTTP-Verbindung kann beim Beginn der Abschaltung durch systemd abbrechen."
},
{
"endpoint":"/api/system/power/reboot/status",
"method":"GET",
"use":"Zustand des aktuellen oder letzten Neustarts."
},
{
"endpoint":"/api/system/power/shutdown",
"method":"POST",
"use":"Schaltet den Proxmox-Host aus, etwa als Reaktion auf ein USV-Abschaltsignal."
},
{
"endpoint":"/api/system/power/shutdown/status",
"method":"GET",
"use":"Zustand der aktuellen oder letzten Abschaltung."
},
{
"endpoint":"/api/system/pve-update/run",
"method":"POST",
"use":"Startet denselben PVE-Updateablauf wie Jetzt aktualisieren im Health Monitor und das Shell-Menü; delegiert an update-pve-safe.sh."
},
{
"endpoint":"/api/system/pve-update/status",
"method":"GET",
"use":"Zustand des aktuellen oder letzten PVE-Updates."
},
{
"endpoint":"/api/system/pve-update",
"method":"DELETE",
"use":"Bricht ein laufendes PVE-Update mit SIGTERM ab."
},
{
"endpoint":"/api/proxmenux/self-update/run",
"method":"POST",
"use":"Aktualisiert ProxMenux mit dem Installer des eingestellten Stable- oder Beta-Kanals. Eine eigene systemd-Unit lässt den Auftrag den vom Installer ausgelösten proxmenux-monitor-Neustart überstehen."
},
{
"endpoint":"/api/proxmenux/self-update/status",
"method":"GET",
"use":"Zustand der aktuellen oder letzten ProxMenux-Selbstaktualisierung."
},
{
"endpoint":"/api/vms/<vmid>/control",
"method":"POST",
"use":"Übermittelt die Steuerung einer VM oder eines LXC. <code>action</code> erlaubt <code>start</code>, <code>stop</code>, <code>shutdown</code> oder <code>reboot</code>. Eine erfolgreiche Antwort enthält einen bestätigten PVE-Task und bedeutet nicht dessen Abschluss. Fragen Sie den control-task-Endpunkt des Gastes für das Ergebnis ab."
"use":"Erstellt eine vzdump-Sicherung einer VM oder eines LXC. Felder im Body, alle optional, sofern die Vorgaben zum Speicheraufbau passen: <code>storage</code> (ein PVE-Speicher), <code>mode</code> (<code>snapshot</code>, <code>suspend</code> oder <code>stop</code>), <code>compress</code> (<code>zstd</code>, <code>lzo</code>, <code>gzip</code> oder <code>none</code>), <code>protected</code> (<code>true</code> oder <code>false</code>), <code>notes</code> und <code>pbs_change_detection</code> (<code>default</code>, <code>legacy</code> oder <code>data</code>). Liefert die UPID des PVE-Tasks."
"use":"Listet bisherige Sicherungen einer VM oder eines LXC auf allen erreichbaren Speichern auf."
}
],
"syncVsAsyncTitle":"Zwei Arten von Aktionen",
"syncVsAsyncBody":"Host-Stromsteuerung und Updates laufen in temporären systemd-Units mit <code>.../status</code>. Nur das PVE-Update hat hier eine <code>DELETE</code>-Abbruchroute. VM/LXC-Steuerung liefert einen abzufragenden Task, Sicherung eine UPID für einen Hintergrundauftrag. Annahme bedeutet nicht Abschluss. Authentifizierung und Rechte hängen von der Route ab.",
"curlTitle":"curl-Beispiel",
"curlBody":"Startet ein PVE-Update und fragt bis zum Abschluss ab, wie eine Home-Assistant-Automation oder ein Ansible-Playbook.",
"haBody":"Ein <code>rest</code>-Sensor fragt den Zustand ab; <code>rest_command</code> startet das Update. Binden Sie beide in Dashboard-Schaltflächen und Automationen ein:",
"use":"Kleine Zustandsprüfung mit JSON-Feldern <code>status</code>, <code>timestamp</code> und <code>version</code>. Für Uptime-Kuma-Schlüsselwortprüfungen geeignet; bei aktiver Authentifizierung muss der Client den Bearer-Header senden."
},
{
"endpoint":"/api/health/status",
"method":"GET",
"use":"Gesamtzustand: ein Schweregrad und eine Zusammenfassung."
},
{
"endpoint":"/api/health/details",
"method":"GET",
"use":"Alle zehn Kategorien mit Zustand und strukturierten Daten der jeweiligen Prüfung."
},
{
"endpoint":"/api/health/full",
"method":"GET",
"use":"Vollständige Daten: Kategorien, aktive Fehler, unterdrückte Warnungen und Einstellungen. Hintergrunddaten werden genutzt, wenn sie jünger als sechs Minuten sind; sonst oder bei erzwungener Aktualisierung läuft eine neue Prüfung."
},
{
"endpoint":"/api/health/active-errors",
"method":"GET",
"use":"Aktive Liste, filterbar durch <code>?category=<name></code>."
},
{
"endpoint":"/api/health/dismissed",
"method":"GET",
"use":"Unterdrückte Warnungen mit verbleibenden Stunden."
},
{
"endpoint":"/api/health/settings",
"method":"GET",
"use":"Eingestellte Unterdrückungsdauer je Kategorie."
},
{
"endpoint":"/api/health/remote-storages",
"method":"GET",
"use":"Inventar von Proxmox-definierten Fernspeichern mit Online-Status."
},
{
"endpoint":"/api/health/interfaces",
"method":"GET",
"use":"Netzwerkschnittstellen mit Typ (Bridge / Bond / physisch), IP und Verbindungsgeschwindigkeit."
},
{
"endpoint":"/api/health/acknowledge",
"method":"POST",
"use":"Anfrageinhalt: <code>'{'\"error_key\":\"smart_sdh\"'}'</code>. Unterdrückt eine Warnung für die eingestellte Dauer ihrer Kategorie."
},
{
"endpoint":"/api/health/cleanup-orphans",
"method":"POST",
"use":"Manuelle Bereinigung von Fehlern, deren zugrunde liegendes Gerät oder VM verschwunden ist. Idempotent."
}
],
"outro":"Antwortformate und Kategorien erklärt <link>Health Monitor</link>."
},
"storage":{
"heading":"Speicher",
"rows":[
{
"endpoint":"/api/storage",
"method":"GET",
"use":"Für den Host sichtbare Datenträger: Blockgeräte, ZFS-Pools und LVM."
},
{
"endpoint":"/api/storage/summary",
"method":"GET",
"use":"Kompakte Zusammenfassung, die von Dashboardkarten verwendet wird."
},
{
"endpoint":"/api/proxmox-storage",
"method":"GET",
"use":"Proxmox-definierte Speicher von <code>/etc/pve/storage.cfg</code> mit Online-Zustand und freiem Speicherplatz."
},
{
"endpoint":"/api/storage/observations",
"method":"GET",
"use":"Dauerhaft gespeicherte Beobachtungen: SMART-Warnungen, E/A-Fehler und ZFS-Ereignisse. Bleiben nach automatischer Fehlerauflösung erhalten."
},
{
"endpoint":"/api/storage/smart/<disk>",
"method":"GET",
"use":"Aktuelle SMART Attribute für eine Festplatte."
},
{
"endpoint":"/api/storage/smart/<disk>/latest",
"method":"GET",
"use":"Aktueller SMART Selbsttest für die Festplatte."
},
{
"endpoint":"/api/storage/smart/<disk>/history",
"method":"GET",
"use":"Liste der gespeicherten SMART-Berichte für die Festplatte."
"use":"Listen Sie die derzeit geplanten SMART-Tests auf."
},
{
"endpoint":"/api/storage/smart/tools",
"method":"GET",
"use":"Prüft, ob <code>smartctl</code> und zugehörige Werkzeuge installiert sind."
}
]
},
"network":{
"heading":"Netzwerk",
"rows":[
{
"endpoint":"/api/network",
"method":"GET",
"use":"Alle Schnittstellen mit Linkzustand und Adressen."
},
{
"endpoint":"/api/network/summary",
"method":"GET",
"use":"Kompakte Ansicht, die vom Dashboard verwendet wird."
},
{
"endpoint":"/api/network/<iface>/metrics",
"method":"GET",
"use":"RX/TX je Schnittstelle, Fehlerzähler und RRD-Zeitreihen."
},
{
"endpoint":"/api/network/latency/current",
"method":"GET",
"use":"Letzte Latenzmessung zum Gateway."
},
{
"endpoint":"/api/network/latency/history",
"method":"GET",
"use":"Zeitreihe der Gateway-Latenz."
}
]
},
"vms":{
"heading":"VMs und Container",
"rows":[
{
"endpoint":"/api/vms",
"method":"GET",
"use":"VMs und CTs des lokalen Knotens mit Zustand, vmid und Name."
},
{
"endpoint":"/api/vms/<vmid>",
"method":"GET",
"use":"Vollständige Details für einen Gast (Konfiguration, Netzwerk, Festplatten)."
},
{
"endpoint":"/api/vms/<vmid>/metrics",
"method":"GET",
"use":"CPU / Speicher / Festplatte I/O Zeitreihe für einen Gast (RRD)."
},
{
"endpoint":"/api/vms/<vmid>/logs",
"method":"GET",
"use":"Aktuelle Task-Protokolle dieses Gastes."
},
{
"endpoint":"/api/vms/<vmid>/backups",
"method":"GET",
"use":"Für diesen Gast gespeicherte Sicherungen."
},
{
"endpoint":"/api/vms/<vmid>/control",
"method":"POST",
"use":"Wählen Sie eine Aktion aus dem Schema: <code>'{'\"action\":\"start|stop|reboot|shutdown\"'}'</code>. Steuert den Betriebszustand des Gastes."
},
{
"endpoint":"/api/vms/<vmid>/backup",
"method":"POST",
"use":"Startet <code>vzdump</code> für den Gast. Die Anfrage legt Speicher und Modus fest (<code>snapshot</code> / <code>suspend</code> / <code>stop</code>)."
},
{
"endpoint":"/api/vms/<vmid>/config",
"method":"PUT",
"use":"Aktualisieren Sie das Beschreibungsfeld (Notizen) eines VM / CT. Andere Konfigurationsschlüssel sind von diesem Endpunkt aus nicht veränderbar."
},
{
"endpoint":"/api/node/metrics",
"method":"GET",
"use":"Zusammengefasste Knotenmetriken als RRD-Zeitreihen."
}
]
},
"backups":{
"heading":"Sicherungen",
"rows":[
{
"endpoint":"/api/backups",
"method":"GET",
"use":"Sicherungen auf dir-, NFS-, CIFS- und PBS-Speichern, die über den lokalen Knoten abgefragt werden. Keine vollständige Prüfung aller Clusterknoten."
},
{
"endpoint":"/api/backup-storages",
"method":"GET",
"use":"Als Sicherungsziele gekennzeichnete Speicher mit freiem Platz."
"use":"Entfernen Sie das Monitor-Ziel aus der Benachrichtigungskonfiguration von PVE."
},
{
"endpoint":"/api/notifications/proxmox/read-cfg",
"method":"GET",
"use":"Lesen Sie den aktuellen <code>notifications.cfg</code> von PVE, wie PVE ihn sieht."
}
]
},
"security":{
"heading":"Sicherheit (lesen)",
"rows":[
{
"endpoint":"/api/security/firewall/status",
"method":"GET",
"use":"PVE Firewall Status und aktive Regeln."
},
{
"endpoint":"/api/security/fail2ban/details",
"method":"GET",
"use":"Zustand des Fail2Ban-Jails; setzt diese optionale Installation voraus."
},
{
"endpoint":"/api/security/fail2ban/activity",
"method":"GET",
"use":"Aktuelle Fail2Ban-Ereignisse: Sperren, Entsperren und Jail-Starts."
},
{
"endpoint":"/api/security/lynis/status",
"method":"GET",
"use":"Lynis-Zustand: Installation und Zeitpunkt der letzten Prüfung."
},
{
"endpoint":"/api/security/lynis/report",
"method":"GET",
"use":"Letzter Lynis-Auditbericht: Warnungen, Vorschläge und Hardening-Index."
},
{
"endpoint":"/api/security/tools",
"method":"GET",
"use":"Erkennen Sie, welche optionalen Sicherheitstools (Fail2Ban, Lynis) installiert sind."
}
]
},
"proxmenuxIntegration":{
"heading":"ProxMenux Integration",
"rows":[
{
"endpoint":"/api/proxmenux/update-status",
"method":"GET",
"use":"Verfügbarkeit eines ProxMenux-Monitor-Updates sowie installierte und neueste Version."
},
{
"endpoint":"/api/proxmenux/installed-tools",
"method":"GET",
"use":"Liste jeder ProxMenux-Postinstallationsoptimierung, die derzeit auf dem Host registriert ist (ab <code>/usr/local/share/proxmenux/installed_tools.json</code>)."
},
{
"endpoint":"/api/proxmenux/tool-source/<key>",
"method":"GET",
"use":"Quellcode der zugeordneten Nachinstallationsfunktion aus aktuellen Host-Skripten oder erhaltenem älterem Code. Kein garantiertes Abbild des ursprünglich ausgeführten Codes."
}
]
},
"prometheus":{
"heading":"Prometheus-Metriken",
"intro":"Der authentifizierte Endpunkt <code>GET /api/prometheus</code> liefert das Prometheus-Textformat 0.0.4. Jede Metrik enthält <code>node=\"<hostname>\"</code> und einen Zeitstempel. Erfassen Sie sie mit Prometheus oder einer kompatiblen Zeitreihendatenbank.",
"desc":"Belegter RAM und konfiguriertes Maximum je VM/CT."
}
]
},
{
"group":"GPU",
"metrics":[
{
"metric":"proxmox_gpu_temperature_celsius",
"desc":"GPU-Temperatur. Labels <code>slot</code> und <code>vendor</code>; gpu enthält zusätzlich den GPU-Namen."
},
{
"metric":"proxmox_gpu_utilization_percent",
"desc":"GPU-Auslastung in Prozent."
},
{
"metric":"proxmox_gpu_memory_total_bytes",
"desc":"Gesamter GPU-Speicher."
},
{
"metric":"proxmox_gpu_power_draw_watts",
"desc":"GPU-Leistungsaufnahme in Watt."
},
{
"metric":"proxmox_gpu_clock_speed_mhz",
"desc":"GPU-Kerntakt."
},
{
"metric":"proxmox_gpu_memory_clock_mhz",
"desc":"GPU-Speichertakt."
}
]
},
{
"group":"UPS",
"metrics":[
{
"metric":"proxmox_ups_battery_charge_percent",
"desc":"Batterieladung in Prozent."
},
{
"metric":"proxmox_ups_load_percent",
"desc":"Aktuelle Belastung der USV."
},
{
"metric":"proxmox_ups_runtime_seconds",
"desc":"Geschätzte Laufzeit im Batteriebetrieb."
},
{
"metric":"proxmox_ups_input_voltage_volts",
"desc":"Eingangsspannung."
}
]
}
],
"scrapeTitle":"Prometheus-Scrape-Konfiguration",
"scrapeIntro":"Bei aktiver Authentifizierung tragen Sie ein API-Token als Bearer-Header in die Prometheus-Erfassungskonfiguration ein:",
"perHostTitle":"Erfassung je Host",
"perHostBody":"Jede Instanz exportiert Metriken ihres eigenen Hosts. Lassen Sie Prometheus im Cluster jeden Knoten abfragen. Das Label <code>node</code> unterscheidet die Reihen in Grafana (<code>proxmox_vms_running'{'node=\"pve01\"'}'</code>)."
},
"puttingItTogether":{
"heading":"Integrationen zusammenführen",
"body":"<link>Integrationen</link> erklärt die Anbindung an Home-Assistant-Sensoren, Homepage-Karten, Grafana-Dashboards, n8n-Abläufe und weitere Werkzeuge. Dort finden Sie typische Konfigurationen zum Kopieren. Diese Seite enthält den Endpunktkatalog."
},
"whereNext":{
"heading":"Weitere Schritte",
"items":[
{
"label":"Zugriff und Authentifizierung",
"href":"/docs/monitor/access-auth",
"tail":" — Token-Erstellung, Auditprotokoll, optionales Fail2Ban-Jail und TLS."
},
{
"label":"Benachrichtigungen",
"href":"/docs/monitor/notifications",
"tailRich":" — Inhalt von <code>data</code> je Ereignistyp beim Aufruf von <code>/api/notifications/send</code>."
},
{
"label":"KI-Assistent",
"href":"/docs/monitor/ai-assistant",
"tailRich":" — Funktionsweise von <code>/api/notifications/test-ai</code> und <code>/api/notifications/provider-models</code>."
},
{
"label":"Gesundheitsmonitor",
"href":"/docs/monitor/health-monitor",
"tailRich":" — Antwortformat von <code>/api/health/*</code> und Bedeutung der zehn Kategorien."
