# 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`

```bash
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`

```bash
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`

```bash
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 |

```json
{
  "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.