VMs API

Note

Generated from src/openapi.json by npm run reference:generate. Do not hand-edit: changes will be overwritten on the next run.

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

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}

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}

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}

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

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

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}

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

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

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

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

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}

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

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