VMs API
GET /api/v1/vms
Section titled “GET /api/v1/vms”List Vms
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host | query | integer | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/vms
Section titled “POST /api/v1/vms”Create Vm Route
Validate the spec here, not in the job: a bad spec should be a 422 the operator sees while the form is still open, not a failed job in the history.
Request body (required), application/json, VmCreateIn
| Field | Type | Required | Description |
|---|---|---|---|
bridge | string | no | |
cores | integer | no | |
disk_gb | integer | no | |
host_id | integer | yes | |
iso | string | null | no | |
memory_mb | integer | no | |
name | string | yes | |
node | string | null | no | |
ostype | string | no | |
start | boolean | no | |
storage | string | no | |
vlan_tag | integer | null | no | |
vmid | integer | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
DELETE /api/v1/vms/{vm_id}
Section titled “DELETE /api/v1/vms/{vm_id}”Delete Vm Route
The most destructive route in this phase: the guest and its disks are gone, and nothing here backs them up first. Doc 05 puts it at owner, one rung above every other VM route; on top of that it takes the same typed-confirmation path as a self-targeted stop, and refuses a running guest outright rather than forcing it down first.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Request body, application/json, VmDeleteIn
| Field | Type | Required | Description |
|---|---|---|---|
confirm | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/vms/{vm_id}
Section titled “GET /api/v1/vms/{vm_id}”Vm Detail
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/vms/{vm_id}/{action}
Section titled “POST /api/v1/vms/{vm_id}/{action}”Vm Lifecycle
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes | |
action | path | string | yes |
Request body, application/json, LifecycleIn
| Field | Type | Required | Description |
|---|---|---|---|
confirm | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/vms/{vm_id}/clone
Section titled “POST /api/v1/vms/{vm_id}/clone”Clone Vm Route
A linked clone is refused here, not by PVE.
The upgrade path this docstring used to describe is now taken: the poller
mirrors /cluster/resources’s template flag onto Vm, so a linked clone
of an ordinary guest is refused with a sentence naming templates instead of
PVE’s 500 Linked clone feature is not supported for '<volume>' (scsi0),
which never mentions them. Its trigger condition was “if PVE’s rejection
proves confusing in practice”, and doc 12 check 18 is that evidence.
Historical note, kept because it explains the shape: PVE permits a linked
clone (full=false) only from a template, and Proxploy could not tell
templates apart, so full was passed through unvalidated.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Request body, application/json, VmCloneIn
| Field | Type | Required | Description |
|---|---|---|---|
full | boolean | no | |
name | string | null | no | |
newid | integer | null | no | |
storage | string | null | no | |
target | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/vms/{vm_id}/network
Section titled “GET /api/v1/vms/{vm_id}/network”Vm Network
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
PUT /api/v1/vms/{vm_id}/network/{iface}
Section titled “PUT /api/v1/vms/{vm_id}/network/{iface}”Vm Network Update
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes | |
iface | path | string | yes |
Request body (required), application/json, NicIn
| Field | Type | Required | Description |
|---|---|---|---|
bridge | string | null | no | |
firewall | boolean | null | no | |
gw | string | null | no | |
gw6 | string | null | no | |
ip | string | null | no | |
ip6 | string | null | no | |
link_down | boolean | null | no | |
mtu | integer | null | no | |
rate | number | null | no | |
tag | integer | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/vms/{vm_id}/options
Section titled “GET /api/v1/vms/{vm_id}/options”Get VM Options
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
PUT /api/v1/vms/{vm_id}/options
Section titled “PUT /api/v1/vms/{vm_id}/options”Update VM Options
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Request body (required), application/json, OptionsIn
| Field | Type | Required | Description |
|---|---|---|---|
enable | integer | null | no | |
policy_in | string | null | no | |
policy_out | string | null | no | |
dhcp | integer | null | no | |
ndp | integer | null | no | |
radv | integer | null | no | |
macfilter | integer | null | no | |
ipfilter | integer | null | no | |
digest | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/vms/{vm_id}/snapshots
Section titled “GET /api/v1/vms/{vm_id}/snapshots”List Vm Snapshots
Live read on every request (doc 05: “List snapshots (live from Proxmox)”); there is no snapshot table and this phase adds none.
PVE always includes a synthetic current entry describing the running
state. It is not a snapshot, has no snaptime, and cannot be rolled back to
or deleted, so it is dropped here rather than in the UI; otherwise every
consumer of this endpoint has to know the same trivia.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/vms/{vm_id}/snapshots
Section titled “POST /api/v1/vms/{vm_id}/snapshots”Create Vm Snapshot
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes |
Request body (required), application/json, SnapshotIn
| Field | Type | Required | Description |
|---|---|---|---|
description | string | null | no | |
name | string | yes | |
vmstate | boolean | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
DELETE /api/v1/vms/{vm_id}/snapshots/{name}
Section titled “DELETE /api/v1/vms/{vm_id}/snapshots/{name}”Delete Vm Snapshot
No typed confirmation: deleting a snapshot leaves the guest and its disk exactly as they are. Only the rollback above destroys live state.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes | |
name | path | string | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/vms/{vm_id}/snapshots/{name}/rollback
Section titled “POST /api/v1/vms/{vm_id}/snapshots/{name}/rollback”Rollback Vm Snapshot
Rollback throws away every write since the snapshot was taken; there is
no undo and no second copy. It therefore reuses the same three-key 409
shape (error/confirm_phrase/detail) enqueue_lifecycle uses, so
the frontend’s existing typed-confirmation dialog renders it with no new
component, but the error value here is "confirm_required", not
enqueue_lifecycle’s self-targeted-stop "self_target": rollback asks
for confirmation from every caller, not only when the VM happens to be
the one Proxploy itself runs in. The frontend keys on this exact string,
so do not conflate the two.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm_id | path | integer | yes | |
name | path | string | yes |
Request body, application/json, RollbackIn
| Field | Type | Required | Description |
|---|---|---|---|
confirm | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |