Documentation v0.1.7
Home GitHub

Query Endpoints

This page covers the three read-only endpoints: health check, single VM status, and the cluster VM list. Query endpoints do not check ALLOW_IPS.

GET /api/health

curl http://192.168.0.11:8080/api/health
# ok

Confirms only that the process is alive; it does not check Proxmox or the state files.

GET /api/vm/:id/status

curl http://192.168.0.11:8080/api/vm/120/status
# running
Case Response
Success Text: the value after the colon in qm status (running / stopped); unknown when the output cannot be parsed
Non-numeric :id 400 JSON {"error": "invalid VM ID"}
qm status fails 500 failed to get VM status: ...

Runs locally on the main node only; querying a VM on another node fails, so use /vm/list instead.

GET /api/vm/list

curl "http://192.168.0.11:8080/api/vm/list?disable=0"
disable Returns
omitted Every VM, disabled entries included
0 Running and not disabled
1 Stopped and not disabled 
{
  "count": 1,
  "list": [
    { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
      "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
  ],
  "cluster": [
    { "node": "pve1", "max_cpu": 16, "max_memory": 62.7, "cpu": 12.5, "memory": 6.38,
      "memory_used": 1.59, "disk": 93.93, "running": true }
  ],
  "data": []
}

list[]

Field Description
vmid / name / node From pvesh get /cluster/resources --type vm
os The VM's Proxmox tag (this service writes debian / ubuntu / rockylinux); - for disabled entries
running status == "running"; always true for disabled entries
cpu vCPU count
disk / memory / memory_used GiB, integer-truncated

Sorted by ascending vmid.

cluster[]

Field Description
node / running Node name and whether it is online
max_cpu Node logical CPU count
max_memory / disk GiB, rounded to two decimals
cpu Sum of listed VMs' vCPUs ÷ max_cpu (%)
memory Sum of listed VMs' allocated memory ÷ max_memory (%)
memory_used Sum of listed VMs' used memory ÷ max_memory (%)

Percentages count only VMs that pass the disable filter. Sorted by node name.

data

Deprecated; mirrors list for older clients.

中文