# API 參考

本頁一覽 QemuRun-pve 的全部 REST 端點，每組端點的細節在對應子頁。

## 慣例

| 項目 | 說明 |
|---|---|
| 基底網址 | `http://<主節點 IP>:<PORT>/api` |
| 請求格式 | `Content-Type: application/json` |
| 驗證 | 無 token；寫入端點以來源 IP 比對 `ALLOW_IPS`，見 [存取控制](/zh/access-control) |
| 同步端點回應 | 成功為純文字 `ok`；失敗為純文字錯誤訊息與 4xx／5xx |
| SSE 端點回應 | `text/event-stream`，以 `event: close` 結束，見 [SSE 事件](/zh/sse-events) |
| `:id` | VMID 整數；無法解析時同步端點回 `500`（`/status` 回 `400`） |

## 端點一覽

| 方法 | 路徑 | 回應 | `ALLOW_IPS` | VM 狀態要求 | 說明頁 |
|---|---|---|---|---|---|
| `GET` | `/health` | 文字 `ok` | — | — | [查詢端點](/zh/api-query) |
| `GET` | `/vm/list` | JSON | — | — | [查詢端點](/zh/api-query) |
| `GET` | `/vm/:id/status` | 文字 | — | — | [查詢端點](/zh/api-query) |
| `POST` | `/vm/install` | SSE | ✓ | — | [建立 VM 端點](/zh/api-install) |
| `POST` | `/vm/:id/start` | SSE | ✓ | 停止中 | [生命週期端點](/zh/api-lifecycle) |
| `POST` | `/vm/:id/reboot` | SSE | ✓ | 執行中 | [生命週期端點](/zh/api-lifecycle) |
| `POST` | `/vm/:id/shutdown` | 文字 `ok` | ✓ | 執行中 | [生命週期端點](/zh/api-lifecycle) |
| `POST` | `/vm/:id/stop` | 文字 `ok` | ✓ | 執行中 | [生命週期端點](/zh/api-lifecycle) |
| `POST` | `/vm/:id/destroy` | 文字 `ok` | ✓ | 停止中 | [生命週期端點](/zh/api-lifecycle) |
| `POST` | `/vm/:id/set/cpu` | 文字 `ok` | ✓ | 停止中 | [資源調整端點](/zh/api-resources) |
| `POST` | `/vm/:id/set/memory` | 文字 `ok` | ✓ | 停止中 | [資源調整端點](/zh/api-resources) |
| `POST` | `/vm/:id/set/disk` | 文字 `ok` | ✓ | 停止中 | [資源調整端點](/zh/api-resources) |
| `POST` | `/vm/:id/set/node` | SSE | ✓ | 停止中 | [資源調整端點](/zh/api-resources) |

## 靜態檔案

`GET /sh/<file>` 提供 `sh/` 目錄內容，供新 VM 下載 [OS 初始化腳本](/zh/os-init-scripts)；此路徑不在 `/api` 之下，也不檢查 `ALLOW_IPS`。