# API Reference

This page lists every QemuRun-pve REST endpoint at a glance; each group has its own detail page.

## Conventions

| Item | Description |
|---|---|
| Base URL | `http://<main node IP>:<PORT>/api` |
| Request format | `Content-Type: application/json` |
| Authentication | No token; mutating endpoints match the client IP against `ALLOW_IPS`, see [Access Control](/access-control) |
| Sync responses | Plain text `ok` on success; plain-text error with 4xx / 5xx on failure |
| SSE responses | `text/event-stream`, ending with `event: close`, see [SSE Events](/sse-events) |
| `:id` | Integer VMID; unparsable values make sync endpoints return `500` (`/status` returns `400`) |

## Endpoints

| Method | Path | Response | `ALLOW_IPS` | Required VM state | Details |
|---|---|---|---|---|---|
| `GET` | `/health` | text `ok` | — | — | [Query Endpoints](/api-query) |
| `GET` | `/vm/list` | JSON | — | — | [Query Endpoints](/api-query) |
| `GET` | `/vm/:id/status` | text | — | — | [Query Endpoints](/api-query) |
| `POST` | `/vm/install` | SSE | ✓ | — | [Install Endpoint](/api-install) |
| `POST` | `/vm/:id/start` | SSE | ✓ | stopped | [Lifecycle Endpoints](/api-lifecycle) |
| `POST` | `/vm/:id/reboot` | SSE | ✓ | running | [Lifecycle Endpoints](/api-lifecycle) |
| `POST` | `/vm/:id/shutdown` | text `ok` | ✓ | running | [Lifecycle Endpoints](/api-lifecycle) |
| `POST` | `/vm/:id/stop` | text `ok` | ✓ | running | [Lifecycle Endpoints](/api-lifecycle) |
| `POST` | `/vm/:id/destroy` | text `ok` | ✓ | stopped | [Lifecycle Endpoints](/api-lifecycle) |
| `POST` | `/vm/:id/set/cpu` | text `ok` | ✓ | stopped | [Resource Endpoints](/api-resources) |
| `POST` | `/vm/:id/set/memory` | text `ok` | ✓ | stopped | [Resource Endpoints](/api-resources) |
| `POST` | `/vm/:id/set/disk` | text `ok` | ✓ | stopped | [Resource Endpoints](/api-resources) |
| `POST` | `/vm/:id/set/node` | SSE | ✓ | stopped | [Resource Endpoints](/api-resources) |

## Static Files

`GET /sh/<file>` serves the `sh/` directory so new VMs can download their [OS Init Scripts](/os-init-scripts); this path is outside `/api` and does not check `ALLOW_IPS`.