VM Instances endpoints (Admin API)

GET/api/admin/vm-instances

List VM instances Get a paginated list of VM instances with optional search.

curl -X GET "$PANEL_URL/api/admin/vm-instances" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 VM instances retrieved successfully · 401 Unauthorized · 403 Forbidden

PUT/api/admin/vm-instances

Create new VM instance Create a new VM instance (server) on a Proxmox node. Returns 202 with creation_id. Poll creation-status until active or failed.

Request body: VmInstanceCreate (application/json)

curl -X PUT "$PANEL_URL/api/admin/vm-instances" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"vm_node_id":0,"template_id":0,"pve_node":"","memory":0,"cpus":0,"cores":0,"disk":0,"storage":"","bridge":"","on_boot":0,"hostname":"","vm_ip_id":0,"networks":[],"user_uuid":"","notes":"","ci_user":"","ci_password":""}'

Plugin events: featherpanel:vds:created

Responses: 202 VM creation started · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM node or template not found · 500 Internal server error

GET/api/admin/vm-instances/creation-status/{creationId}

Poll VM creation status Poll status of an async VM creation. Returns status cloning, active, or failed.

curl -X GET "$PANEL_URL/api/admin/vm-instances/creation-status/$CREATION_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Creation status · 400 Missing creation_id · 401 Unauthorized · 404 Creation not found or already completed · 500 Internal server error

GET/api/admin/vm-instances/task-status/{taskId}

curl -X GET "$PANEL_URL/api/admin/vm-instances/task-status/$TASK_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/vm-instances/{id}

Get VM instance Get a single VM instance by ID.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 VM instance retrieved successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found

PATCH/api/admin/vm-instances/{id}

Update VM instance Update instance: hostname, notes, user_uuid, vm_ip_id, memory, cpus, cores, on_boot, networks.

Request body: VmInstanceUpdate (application/json)

curl -X PATCH "$PANEL_URL/api/admin/vm-instances/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"","notes":"","user_uuid":"","vm_ip_id":0,"memory":0,"cpus":0,"cores":0,"on_boot":false,"networks":[],"nameserver":"","searchdomain":"","bios":"","efi_enabled":false,"efi_storage":"","tpm_enabled":false,"tpm_storage":""}'

Plugin events: featherpanel:vds:updated

Responses: 200 VM instance updated successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox update failed

GET/api/admin/vm-instances/{id}/activities

Get VM instance activities GET activity/task history for this VM instance.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID/activities" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Activities fetched successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found

GET/api/admin/vm-instances/{id}/config

Get VM instance config GET Proxmox config for this instance.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID/config" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Config fetched successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox error

GET/api/admin/vm-instances/{id}/status

Get VM instance status GET current VM/container status and resource usage from Proxmox.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID/status" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Status fetched successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox error

GET/api/admin/vm-instances/{id}/vnc-ticket

Get VNC ticket GET VNC console ticket for QEMU VMs and LXC containers.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID/vnc-ticket" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:console:access

Responses: 200 VNC ticket created · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 VNC proxy failed

POST/api/admin/vm-instances/{id}/resize-disk

Resize VM/container disk Resize a disk on an LXC container or QEMU VM. Body must include "disk" and "size".

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/resize-disk" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"disk":"","size":""}'

Responses: 200 Disk resized successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Resize failed

POST/api/admin/vm-instances/{id}/disks

Create VM/container disk Create an additional disk: LXC mount point or QEMU disk.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/disks" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"storage":"","size_gb":0,"path":""}'

Responses: 200 Disk added successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox update failed

DELETE/api/admin/vm-instances/{id}/disks/{key}

Delete VM/container disk DELETE LXC mount point or QEMU disk.

curl -X DELETE "$PANEL_URL/api/admin/vm-instances/$ID/disks/$KEY" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Disk removed successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox update failed

POST/api/admin/vm-instances/{id}/power

Power action Power action: start | stop | reboot.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/power" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"action":""}'

Plugin events: featherpanel:vds:power:action

Responses: 200 Power action completed · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error / Power failed

POST/api/admin/vm-instances/{id}/reinstall

Start async VM reinstall Kicks off a full reinstall by cloning a fresh VM from the original template. Returns 202 with a reinstall_id immediately. Poll reinstall-status/{reinstallId} until status is active or failed.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/reinstall" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:reinstall

Responses: 202 Reinstall clone started · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance or template not found · 500 Internal server error

GET/api/admin/vm-instances/reinstall-status/{reinstallId}

curl -X GET "$PANEL_URL/api/admin/vm-instances/reinstall-status/$REINSTALL_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/vm-instances/{id}/backups

List VM backups List vzdump backups for a specific VM or container on its Proxmox node.

curl -X GET "$PANEL_URL/api/admin/vm-instances/$ID/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Backups listed · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance or node not found · 500 Proxmox error

POST/api/admin/vm-instances/{id}/backups/{backupId}/recover

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/backups/$BACKUP_ID/recover" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

POST/api/admin/vm-instances/{id}/backups

Create VM backup Start an async vzdump backup for a VM or container. Returns 202 with backup_id; poll backup-status until done or failed.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"storage":"","compress":"","mode":""}'

Plugin events: featherpanel:vds:backup:create

Responses: 202 Backup started · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance or node not found · 422 Backup limit reached · 500 Proxmox error

GET/api/admin/vm-instances/backup-status/{backupId}

Poll VM backup status Poll status of an async vzdump backup. Returns running, done, or failed.

curl -X GET "$PANEL_URL/api/admin/vm-instances/backup-status/$BACKUP_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Backup status · 400 Missing or invalid backupId · 401 Unauthorized · 404 Backup task or instance not found · 500 Internal server error

DELETE/api/admin/vm-instances/{id}/backups

Delete VM backup Delete a single vzdump backup volume belonging to a VM or container.

curl -X DELETE "$PANEL_URL/api/admin/vm-instances/$ID/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"volid":"","storage":""}'

Plugin events: featherpanel:vds:backup:delete

Responses: 200 Backup deleted · 400 Missing volid or storage · 401 Unauthorized · 403 Backup does not belong to this VM · 404 VM instance or node not found · 500 Proxmox error

POST/api/admin/vm-instances/{id}/backups/restore

Restore VM from backup Start an async restore of a VM or container from a vzdump backup. Returns 202 with restore_id; poll restore-status until active or failed.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/backups/restore" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"volid":"","storage":""}'

Plugin events: featherpanel:vds:backup:restore

Responses: 202 Restore started · 400 Missing volid or storage · 401 Unauthorized · 403 Forbidden · 404 VM instance or node not found · 500 Proxmox error

GET/api/admin/vm-instances/restore-status/{restoreId}

Poll VM restore status Poll status of an async restore from backup. Returns restoring, active, or failed.

curl -X GET "$PANEL_URL/api/admin/vm-instances/restore-status/$RESTORE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Restore status · 400 Missing or invalid restoreId · 401 Unauthorized · 404 Restore task or instance not found · 500 Internal server error

PATCH/api/admin/vm-instances/{id}/backup-limit

Set VM backup limit Update the maximum number of backups allowed for a VM instance.

curl -X PATCH "$PANEL_URL/api/admin/vm-instances/$ID/backup-limit" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"limit":0}'

Plugin events: featherpanel:vds:updated

Responses: 200 Backup limit updated · 400 Invalid limit · 401 Unauthorized · 404 VM instance not found · 500 Internal server error

POST/api/admin/vm-instances/{id}/suspend

Suspend VM instance Suspend a VM instance by stopping it in Proxmox and updating the suspended status. Sends notification email to the VM owner.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/suspend" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:suspended

Responses: 200 VM instance suspended successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM instance not found · 500 Internal server error - Failed to suspend VM

POST/api/admin/vm-instances/{id}/unsuspend

Unsuspend VM instance Unsuspend a VM instance by updating the suspended status. Sends notification email to the VM owner.

curl -X POST "$PANEL_URL/api/admin/vm-instances/$ID/unsuspend" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:unsuspended

Responses: 200 VM instance unsuspended successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM instance not found · 500 Internal server error - Failed to unsuspend VM

DELETE/api/admin/vm-instances/{id}

Delete VM instance Delete VM instance: stop on Proxmox (if running), delete from Proxmox, then remove from DB.

curl -X DELETE "$PANEL_URL/api/admin/vm-instances/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:deleted

Responses: 200 VM instance deleted successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found

DELETE/api/admin/vm-instances/{id}/hard

Hard delete VM instance Remove the VM instance and panel records without contacting Proxmox. The VM and its files remain on the Proxmox host.

curl -X DELETE "$PANEL_URL/api/admin/vm-instances/$ID/hard" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:deleted

Responses: 200 VM instance hard deleted successfully · 404 VM instance not found