"description":"Koncové body HTTP ProxMenux Monitor pre Home Assistant, Homepage, Grafana, Prometheus, n8n a vlastné panely. Čítanie stavu a zdokumentované operácie: ovládanie VM, spustenie záloh, oznámenia a potvrdenie výstrah.",
"twitterDescription":"Koncové body pre Home Assistant, Homepage, Grafana, Prometheus, n8n a vlastné panely."
},
"header":{
"title":"Referenčná príručka API",
"description":"Koncové body HTTP na čítanie stavu a zdokumentované akcie: senzory Home Assistant, karty Homepage, panely Grafana, zber Prometheus, toky n8n a vlastné skripty. Obsahuje kategórie, exportované metriky a príklady curl.",
"section":"ProxMenux Monitor"
},
"intro":{
"title":"Na čo je táto stránka",
"body":"Táto stránka uvádza koncové body integrácií: čítanie údajov, spustenie záloh, vlastné oznámenia a potvrdenie výstrah. API beží v procese Flask panela na TCP <strong>8008</strong>. Adresu počúvania a TLS opisuje <link>Prístup a overenie</link>."
},
"headerEndpoint":"Koncový bod",
"headerMethod":"Metóda",
"headerUse":"Použitie",
"auth":{
"heading":"Prihlásenie",
"intro":"Pri zapnutom overovaní chránené koncové body očakávajú JWT Bearer token v hlavičke požiadavky:",
"tokensIntro":"Dva spôsoby získania tokenu:",
"items":[
"<strong>Tokeny API, odporúčané pre integrácie.</strong> Platia 365 dní a vytvárajú sa v <strong>Zabezpečenie → Tokeny API</strong>. Majú názov a možno ich jednotlivo odvolať. Na údaje použite read_only, full_admin iba na potrebné správcovské akcie.",
"<strong>Prihlásenie, JWT na 24 hodín.</strong> <code>POST /api/auth/login</code> s menom, heslom a TOTP, ak ho vyžaduje 2FA. JWT vyprší po 24 hodinách; skripty sa potom musia prihlásiť znova."
],
"flowLink":"Prihlásenie, heslá, 2FA, audit a TLS opisuje <link>Prístup a overenie</link>.",
"rows":[
{
"endpoint":"/api/auth/login",
"method":"POST",
"use":"Polia tela (schéma): <code>'{'\"username\",\"password\",\"totp_token?\"'}'</code>. Vráti JWT na 24 hodín."
},
{
"endpoint":"/api/auth/api-tokens",
"method":"GET",
"use":"Uveďte API tokeny (iba metadáta — mená, predpony, dátumy; nikdy nie skutočný tajný kód)."
},
{
"endpoint":"/api/auth/generate-api-token",
"method":"POST",
"use":"Vytvorí token API na 365 dní v overenej relácii. Polia: <code>password, token_name?, totp_token?, scope?</code>. Heslo a požadované TOTP sa overia znova. scope je predvolene read_only; full_admin treba zvoliť výslovne. Tajný token sa vráti iba raz."
},
{
"endpoint":"/api/auth/api-tokens/<id>",
"method":"DELETE",
"use":"Zrušte špecifický API token jeho ID."
}
]
},
"conventions":{
"heading":"Konvencie",
"items":[
"Väčšina používa JSON. Niektoré sťahovania vracajú obyčajný text; <code>/api/prometheus</code> používa textový formát Prometheus 0.0.4 namiesto OpenMetrics. Overte typ odpovede konkrétnej cesty.",
"Mnohé zápisy vracajú <code>'{'\"success\": true, ...'}'</code>. Chyby sa líšia; bežný formát je <code>'{'\"success\": false, \"error\": \"'<'reason'>'\"'}'</code>. Kontrolujte stav HTTP aj polia: niektoré výzvy overenia používajú HTTP 200 so success false.",
"Parametre závisia od koncového bodu. <code>limit</code>, <code>offset</code>, <code>since</code> a filtre kategórií použite iba tam, kde sú podporované.",
"Časové formáty sa líšia: Unix čas, reťazce ISO-8601 aj dátumy systemd. Nepredpokladajte rovnakú jednotku ani výslovné časové pásmo vo všetkých poliach."
]
},
"system":{
"heading":"Systém a hardvér",
"rows":[
{
"endpoint":"/api/system",
"method":"GET",
"use":"Aktuálne hodnoty CPU, pamäte, swapu, času prevádzky a záťaže."
},
{
"endpoint":"/api/info",
"method":"GET",
"use":"Statické informácie o hostiteľovi: meno hostiteľa, jadro, verzia PVE, model CPU, distro."
},
{
"endpoint":"/api/system-info",
"method":"GET",
"use":"Rozšírené systémové údaje pre hlavičku panela: celkové metriky a čas spustenia."
},
{
"endpoint":"/api/hardware",
"method":"GET",
"use":"Podrobný hardvérový inventár: zariadenia PCI, GPU a senzory."
},
{
"endpoint":"/api/hardware/live",
"method":"GET",
"use":"Aktuálne hodnoty rýchlo sa meniacich senzorov."
},
{
"endpoint":"/api/temperature/history",
"method":"GET",
"use":"Časové rady teplôt CPU a jeho puzdra."
},
{
"endpoint":"/api/gpu/<slot>/realtime",
"method":"GET",
"use":"Aktuálne metriky GPU NVIDIA, Intel a AMD podľa pozície PCI."
}
]
},
"actions":{
"heading":"Systémové akcie",
"intro":"Tieto asynchrónne systémové akcie používajú dočasné jednotky systemd. Pri zapnutom overovaní ich zápisy vyžadujú <code>full_admin</code>; <code>read_only</code> môže čítať <code>.../status</code>. Prijatý štart vráti HTTP 202 a stav; priebeh sledujte cez <code>.../status</code>. Ovládanie hostí a zálohy majú iné odpovede, opísané nižšie.",
"shapeTitle":"Tvar bežnej odozvy",
"shapeIntro":"Asynchrónne systémové akcie používajú tento objekt stavu JSON. Ovládanie hostí a zálohy majú iné formáty:",
"concurrencyBody":"Ďalší štart tej istej aktívnej akcie vráti HTTP 409. Zrušenie je možné iba s dokumentovanou cestou DELETE, napríklad pri aktualizácii PVE. Stav prejde na <code>cancelled</code> a časy zostanú. Konečné stavy sú v pamäti procesu a po reštarte Monitora sa môžu stratiť.",
"rows":[
{
"endpoint":"/api/system/power/reboot",
"method":"POST",
"use":"Spustí reštart hostiteľa Proxmox. Spojenie HTTP sa môže prerušiť, keď systemd začne vypínanie."
},
{
"endpoint":"/api/system/power/reboot/status",
"method":"GET",
"use":"Stav aktuálneho alebo posledného reštartu."
},
{
"endpoint":"/api/system/power/shutdown",
"method":"POST",
"use":"Vypne hostiteľa Proxmox, napríklad po signáli na vypnutie z UPS."
},
{
"endpoint":"/api/system/power/shutdown/status",
"method":"GET",
"use":"Stav aktuálneho alebo posledného vypínania."
},
{
"endpoint":"/api/system/pve-update/run",
"method":"POST",
"use":"Spustí aktualizáciu PVE používanú voľbou Aktualizovať teraz v Health Monitor aj ponukou shellu; odovzdá ju update-pve-safe.sh."
},
{
"endpoint":"/api/system/pve-update/status",
"method":"GET",
"use":"Stav aktuálnej alebo poslednej aktualizácie PVE."
"use":"Aktualizuje ProxMenux inštalátorom nastaveného stabilného alebo beta kanála. Vlastná jednotka systemd umožní pokračovať počas reštartu proxmenux-monitor vykonaného inštalátorom."
},
{
"endpoint":"/api/proxmenux/self-update/status",
"method":"GET",
"use":"Stav aktuálnej alebo poslednej aktualizácie ProxMenux."
},
{
"endpoint":"/api/vms/<vmid>/control",
"method":"POST",
"use":"Odošle ovládací príkaz VM alebo LXC. Pole <code>action</code> prijíma <code>start</code>, <code>stop</code>, <code>shutdown</code> alebo <code>reboot</code>. Úspešná odpoveď vracia potvrdenú úlohu PVE, nie potvrdenie dokončenia. Výsledok sledujte cez koncový bod control-task hosťa."
"use":"Vytvorí zálohu vzdump VM alebo LXC. Polia tela, všetky voliteľné, ak predvolené hodnoty zodpovedajú rozloženiu úložiska: <code>storage</code> (úložisko PVE), <code>mode</code> (<code>snapshot</code>, <code>suspend</code> alebo <code>stop</code>), <code>compress</code> (<code>zstd</code>, <code>lzo</code>, <code>gzip</code> alebo <code>none</code>), <code>protected</code> (<code>true</code> alebo <code>false</code>), <code>notes</code> a <code>pbs_change_detection</code> (<code>default</code>, <code>legacy</code> alebo <code>data</code>). Vráti UPID úlohy PVE."
"use":"Zoznam predchádzajúcich záloh pre VM alebo LXC vo všetkých dosiahnuteľných úložiskách."
}
],
"syncVsAsyncTitle":"Dva typy akcií",
"syncVsAsyncBody":"Napájanie a aktualizácie hostiteľa používajú dočasné jednotky systemd s <code>.../status</code>. Iba aktualizácia PVE tu má cestu <code>DELETE</code> na zrušenie. Ovládanie VM/LXC vráti úlohu na sledovanie; záloha UPID úlohy na pozadí. Prijatie neznamená dokončenie. Overovanie a oprávnenia závisia od cesty.",
"curlTitle":"Príklad curl",
"curlBody":"Spustí aktualizáciu PVE a sleduje ju do dokončenia, ako automatizácia Home Assistant či playbook Ansible.",
"haBody":"Senzor <code>rest</code> zisťuje stav a <code>rest_command</code> spustí aktualizáciu. Priraďte ich k tlačidlu panela a potrebným automatizáciám:",
"use":"Ľahká kontrola vracajúca JSON s <code>status</code>, <code>timestamp</code> a <code>version</code>. Vhodná na kontrolu kľúčových slov Uptime Kuma; pri zapnutom overovaní klient posiela hlavičku Bearer."
},
{
"endpoint":"/api/health/status",
"method":"GET",
"use":"Celkový stav: úroveň závažnosti a zhrnutie."
},
{
"endpoint":"/api/health/details",
"method":"GET",
"use":"Všetkých desať kategórií so stavom a štruktúrovanými údajmi jednotlivých kontrol."
},
{
"endpoint":"/api/health/full",
"method":"GET",
"use":"Úplné údaje: kategórie, aktívne chyby, potlačené výstrahy a nastavenia potlačenia. Používa výsledky na pozadí mladšie než šesť minút; inak alebo pri vynútenej obnove spustí novú kontrolu."
"use":"Odošle skúšobné oznámenie do kanála. Telo: <code>'{'\"channel\":\"telegram\"'}'</code>."
},
{
"endpoint":"/api/notifications/send",
"method":"POST",
"use":"Vytvorí vlastnú udalosť. Telo: <code>'{'\"event_type\":\"custom\",\"severity\":\"WARNING\",\"title\":\"...\",\"body\":\"...\",\"data\":'{''}''}'</code>."
},
{
"endpoint":"/api/notifications/test-ai",
"method":"POST",
"use":"Overí spojenie s poskytovateľom AI. Polia tela (schéma): <code>'{'\"provider\",\"api_key\",\"model\",\"ollama_url?\"'}'</code>."
},
{
"endpoint":"/api/notifications/provider-models",
"method":"POST",
"use":"Zoznam dostupných modelov pre vybraného poskytovateľa AI."
"use":"Odstráni cieľ Monitora z konfigurácie oznámení PVE."
},
{
"endpoint":"/api/notifications/proxmox/read-cfg",
"method":"GET",
"use":"Prečítajte si aktuálne PVE <code>notifications.cfg</code> ako to vidí PVE."
}
]
},
"security":{
"heading":"Bezpečnosť (čítanie)",
"rows":[
{
"endpoint":"/api/security/firewall/status",
"method":"GET",
"use":"Stav firewallu PVE a aktívne pravidlá."
},
{
"endpoint":"/api/security/fail2ban/details",
"method":"GET",
"use":"Stav jailu Fail2Ban; vyžaduje nainštalovaný voliteľný komponent."
},
{
"endpoint":"/api/security/fail2ban/activity",
"method":"GET",
"use":"Nedávne udalosti Fail2Ban: blokovania, odblokovania a spustenia jailu."
},
{
"endpoint":"/api/security/lynis/status",
"method":"GET",
"use":"Stav Lynis: inštalácia a čas poslednej kontroly."
},
{
"endpoint":"/api/security/lynis/report",
"method":"GET",
"use":"Posledná správa Lynis: výstrahy, návrhy a index zabezpečenia."
},
{
"endpoint":"/api/security/tools",
"method":"GET",
"use":"Detekovať, ktoré voliteľné bezpečnostné nástroje (Fail2Ban, Lynis) sú nainštalované."
}
]
},
"proxmenuxIntegration":{
"heading":"Integrácia ProxMenux",
"rows":[
{
"endpoint":"/api/proxmenux/update-status",
"method":"GET",
"use":"Dostupnosť aktualizácie ProxMenux Monitor, nainštalovaná a najnovšia verzia."
},
{
"endpoint":"/api/proxmenux/installed-tools",
"method":"GET",
"use":"Zoznam optimalizácií ProxMenux po inštalácii zaznamenaných na hostiteľovi (z <code>/usr/local/share/proxmenux/installed_tools.json</code>)."
},
{
"endpoint":"/api/proxmenux/tool-source/<key>",
"method":"GET",
"use":"Kód priradenej funkcie po inštalácii z aktuálnych skriptov hostiteľa alebo zachovaného staršieho kódu. Nezaručuje presnú snímku pôvodne spusteného kódu."
}
]
},
"prometheus":{
"heading":"Metriky Prometheus",
"intro":"Overený koncový bod <code>GET /api/prometheus</code> vracia textový formát Prometheus 0.0.4. Každá metrika obsahuje <code>node=\"<hostname>\"</code> a časovú pečiatku. Zber zabezpečí Prometheus alebo kompatibilná databáza časových radov.",
"exportedTitle":"Exportované metriky",
"headerGroup":"Skupina",
"headerMetric":"Metrika",
"headerDesc":"Popis",
"groups":[
{
"group":"Systém",
"metrics":[
{
"metric":"proxmox_cpu_usage",
"desc":"Percento využitia CPU, metrika typu gauge."
"desc":"Použitá pamäť a nastavené maximum každej VM/CT."
}
]
},
{
"group":"GPU",
"metrics":[
{
"metric":"proxmox_gpu_temperature_celsius",
"desc":"Teplota GPU. Štítky <code>slot</code> a <code>vendor</code>; gpu obsahuje aj názov GPU."
},
{
"metric":"proxmox_gpu_utilization_percent",
"desc":"Percento využitia GPU."
},
{
"metric":"proxmox_gpu_memory_total_bytes",
"desc":"Celková pamäť GPU."
},
{
"metric":"proxmox_gpu_power_draw_watts",
"desc":"Príkon GPU vo wattoch."
},
{
"metric":"proxmox_gpu_clock_speed_mhz",
"desc":"Takt jadra GPU."
},
{
"metric":"proxmox_gpu_memory_clock_mhz",
"desc":"Takt pamäte GPU."
}
]
},
{
"group":"UPS",
"metrics":[
{
"metric":"proxmox_ups_battery_charge_percent",
"desc":"Percento nabitia batérie."
},
{
"metric":"proxmox_ups_load_percent",
"desc":"Aktuálne zaťaženie UPS."
},
{
"metric":"proxmox_ups_runtime_seconds",
"desc":"Odhadovaná výdrž na batériu."
},
{
"metric":"proxmox_ups_input_voltage_volts",
"desc":"Vstupné napätie."
}
]
}
],
"scrapeTitle":"Konfigurácia zberu Prometheus",
"scrapeIntro":"Pri zapnutom overovaní zadajte token API do hlavičky Bearer v konfigurácii zberu Prometheus:",
"perHostTitle":"Zber pre každého hostiteľa",
"perHostBody":"Každá inštancia exportuje metriky svojho hostiteľa. V klastri nastavte Prometheus na zber z každého uzla. Štítok <code>node</code> rozlišuje rady v Grafane (<code>proxmox_vms_running'{'node=\"pve01\"'}'</code>)."
},
"puttingItTogether":{
"heading":"Prepojenie integrácií",
"body":"Pozrite <link>Integrácie</link> na prepojenie koncových bodov so senzormi Home Assistant, kartami Homepage, panelmi Grafana, tokmi n8n a ďalšími nástrojmi. Obsahuje bežné konfigurácie na kopírovanie. Táto stránka uvádza katalóg koncových bodov."
