View .md

Core endpoints (Client API: VDS)

26 FeatherPanel Client API: VDS endpoints from user/vds/core.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Last synced from FeatherPanel 15b94e9 on .

On this page

Defined in backend/app/routes/user/vds/core.php. Authentication used here: Signed-in user, VDS access. Read Authentication for how to send credentials and Rate limits and errors for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

Endpoints

GET/api/user/vm-instances

Auth: Signed-in userDefault rate limit: 2 / second (user-vm-instances)Route name: user-vm-instancesController: VmUserInstanceController::getUserVmInstancesroute source

List user VM instances Get VM instances owned by or accessible to the authenticated user. Supports optional pagination and search.

ParameterInTypeRequiredDescription
pagequeryintegernoPage number
limitqueryintegernoRecords per page
searchquerystringnoSearch by hostname or IP
Response data fieldTypeDescription
instancesobject[]
paginationobject
curl -X GET "$PANEL_URL/api/user/vm-instances" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 VM instances retrieved successfully · 401 Unauthorized

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

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-getController: VmUserInstanceController::getVmInstanceroute source

Get VM instance details Get detailed information about a specific VM instance.

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
instanceobject
curl -X GET "$PANEL_URL/api/user/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

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

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-statusController: VmUserInstanceController::getVmInstanceStatusroute source

Get VM instance status Get current status and resource usage from Proxmox.

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
statusobject
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/status" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Status retrieved successfully · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Proxmox error

GET/api/user/vm-instances/{id}/qemu-hardware

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-qemu-hardware-getController: VmUserInstanceController::getQemuHardwareroute source

Get QEMU hardware settings (EFI + TPM + Serial) Returns the current QEMU BIOS mode and whether EFI disk, TPM state disk, and serial0 socket are enabled.

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
biosstring
efi_enabledboolean
tpm_enabledboolean
serial0_enabledboolean
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/qemu-hardware" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

PATCH/api/user/vm-instances/{id}/qemu-hardware

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-qemu-hardware-patchController: VmUserInstanceController::patchQemuHardwareroute source

Update QEMU hardware settings (EFI + TPM + Serial) Updates Proxmox config to enable/disable EFI disk, TPM state disk, and serial0 socket. Optional BIOS mode can be updated.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
biosstringno
efi_enabledbooleanno
tpm_enabledbooleanno
serial0_enabledbooleanno
curl -X PATCH "$PANEL_URL/api/user/vm-instances/$ID/qemu-hardware" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bios":"","efi_enabled":false,"tpm_enabled":false,"serial0_enabled":false}'

Plugin events: featherpanel:vds:qemu:hardware:update

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

GET/api/user/vm-instances/{id}/network-options

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-network-optionsController: VmUserInstanceController::getNetworkOptionsroute source

Get DNS options Returns current DNS settings (nameserver/searchdomain). Supports both QEMU and LXC.

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
nameserverstring
searchdomainstring
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/network-options" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

GET/api/user/vm-instances/{id}/networking

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-networkingController: VmUserInstanceController::getNetworkingroute source

Get VM networking details Returns assigned IP addresses and current DNS settings for a VDS instance.

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

Responses: 200 Networking details fetched · 401 Unauthorized · 403 Forbidden · 404 VM instance not found

PATCH/api/user/vm-instances/{id}/network-dns

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-network-dns-patchController: VmUserInstanceController::patchNetworkDnsroute source

Update DNS settings Updates nameserver (and searchdomain for LXC). Primary IP is intentionally not editable for normal users.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
nameserverstringno
searchdomainstringno
curl -X PATCH "$PANEL_URL/api/user/vm-instances/$ID/network-dns" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"nameserver":"","searchdomain":""}'

Plugin events: featherpanel:vds:network:update

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

GET/api/user/vm-instances/{id}/iso-storages

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-iso-storagesController: VmUserInstanceController::getIsoStoragesroute source

List ISO storages Returns ISO-capable Proxmox storage names for the VM node.

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
storagesstring[]
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/iso-storages" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

GET/api/user/vm-instances/{id}/iso-current

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-iso-currentController: VmUserInstanceController::getIsoCurrentroute source

Get currently mounted ISO Returns currently mounted ISO (if any) by inspecting QEMU cdrom devices (media=cdrom).

ParameterInTypeRequiredDescription
idpathintegeryes
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/iso-current" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 ISO current fetched · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 VM instance not found · 500 Internal server error · 503 Proxmox error

POST/api/user/vm-instances/{id}/iso-upload-and-mount

Auth: VDS accessDefault rate limit: 2 / minuteRoute name: user-vm-instance-iso-upload-and-mountController: VmUserInstanceController::uploadAndMountIsoroute source

Upload and mount an ISO Uploads an ISO to Proxmox and mounts it as the VM cdrom (ide2) while enforcing only one ISO/cdrom at a time.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
storagestringyesISO storage name on Proxmox
filestring (binary)yesISO file to upload
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/iso-upload-and-mount" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -F "storage=" \
  -F "file=@./file"

Plugin events: featherpanel:vds:iso:mount

Responses: 200 Mounted successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 500 Internal server error · 503 Proxmox error

POST/api/user/vm-instances/{id}/iso-fetch-and-mount

Auth: VDS accessDefault rate limit: 2 / minuteRoute name: user-vm-instance-iso-fetch-and-mountController: VmUserInstanceController::fetchAndMountIsoFromUrlroute source

Fetch ISO from URL and mount it Proxmox downloads the ISO directly from a remote URL into the ISO storage, then mounts it as VM cdrom (ide2) while enforcing only one ISO/cdrom at a time.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
storagestringnoISO storage name on Proxmox
urlstring (uri)noRemote ISO URL to download
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/iso-fetch-and-mount" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"storage":"","url":""}'

Plugin events: featherpanel:vds:iso:mount

Responses: 200 Mounted successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 500 Internal server error · 503 Proxmox error

POST/api/user/vm-instances/{id}/iso-unmount

Auth: VDS accessDefault rate limit: 5 / minuteRoute name: user-vm-instance-iso-unmountController: VmUserInstanceController::unmountIsoroute source

Unmount ISO Unlinks cdrom devices (media=cdrom) and sets VM boot order back to the main disk.

ParameterInTypeRequiredDescription
idpathintegeryes
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/iso-unmount" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:iso:unmount

Responses: 200 Unmounted successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 500 Internal server error · 503 Proxmox error

GET/api/user/vm-instances/{id}/templates

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-templatesController: VmUserInstanceController::getTemplatesroute source

Get available templates Get available templates for the VM instance to reinstall. Limited to the VM type (qemu/lxc).

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
templatesobject[]
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/templates" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

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

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-powerController: VmUserInstanceController::powerActionroute source

VM power action Perform power action: start, stop, or reboot.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
actionstringno
Response data fieldTypeDescription
instanceobject
curl -X POST "$PANEL_URL/api/user/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 Power action failed

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

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-vncController: VmUserInstanceController::getVncTicketroute source

Get VNC console ticket Get VNC console access ticket. Returns wss_url (and optionally pve_redirect_url when panel can create a short-lived PVE user).

ParameterInTypeRequiredDescription
idpathintegeryes
Response data fieldTypeDescription
ticketstring
portinteger
nodestring
vmidinteger
hoststring
port_apiinteger
wss_urlstring
pve_redirect_urlstringProxmox noVNC URL when available
curl -X GET "$PANEL_URL/api/user/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 VNC proxy failed

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

Auth: VDS accessDefault rate limit: 5 / minuteRoute name: user-vm-instance-reinstallController: VmUserInstanceController::reinstallroute source

Start async VM reinstall Starts a full reinstall by cloning from the instance template. Returns 202 with reinstall_id. Poll GET /api/user/vm-instances/reinstall-status/{reinstallId} until status is active or failed. For QEMU/KVM, send ci_user and ci_password in the request body.

ParameterInTypeRequiredDescription
idpathintegeryesVM instance ID
Body fieldTypeRequiredDescription
ci_userstringnoCloud-init username (required for QEMU/KVM)
ci_passwordstringnoCloud-init password (required for QEMU/KVM)
Response data fieldTypeDescription
reinstall_idstring
messagestring
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/reinstall" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ci_user":"","ci_password":""}'

Plugin events: featherpanel:vds:reinstall

Responses: 202 Reinstall started · 400 Bad request (e.g. missing ci_user/ci_password for QEMU) · 401 Unauthorized · 403 Forbidden · 404 VM or template not found · 500 Server error

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

Auth: Signed-in userDefault rate limit: 30 / minute (user-vm-instances)Route name: user-vm-instance-reinstall-statusController: VmUserInstanceController::reinstallStatusroute source

Poll reinstall status Poll until status is active or failed. Use the reinstall_id returned from POST .../reinstall. Returns status: cloning (keep polling), failed (with error), or active (with instance).

ParameterInTypeRequiredDescription
reinstallIdpathstringyesReinstall ID from start reinstall response
Response data fieldTypeDescription
statusstring
messagestringWhen status=cloning
errorstringWhen status=failed
instanceobjectWhen status=active
curl -X GET "$PANEL_URL/api/user/vm-instances/reinstall-status/$REINSTALL_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Status (cloning | failed | active) · 400 Missing reinstall_id · 401 Unauthorized · 404 Reinstall not found or access denied · 500 Server error

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

Auth: Signed-in userDefault rate limit: 30 / minute (user-vm-instances)Route name: user-vm-instance-task-statusController: VmUserInstanceController::taskStatusroute source
ParameterInTypeRequiredDescription
taskIdpath-yes
curl -X GET "$PANEL_URL/api/user/vm-instances/task-status/$TASK_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

Auth: VDS accessDefault rate limit: 30 / minuteRoute name: user-vm-instance-backups-listController: VmUserBackupController::listBackupsroute source

List VM backups List backups for this VM instance. Returns backups, backup_limit (max allowed), and available Proxmox storages. Respects instance backup limit.

ParameterInTypeRequiredDescription
idpathintegeryesVM instance ID
Response data fieldTypeDescription
backupsobject[]
backup_limitintegerMax backups allowed for this instance
storagesstring[]Available backup storages on node
curl -X GET "$PANEL_URL/api/user/vm-instances/$ID/backups" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Backups listed · 401 Unauthorized · 403 Forbidden · 404 VM instance not found

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

Auth: VDS accessDefault rate limit: 5 / minuteRoute name: user-vm-instance-backup-recoverController: VmUserBackupController::recoverBackuproute source
ParameterInTypeRequiredDescription
idpath-yes
backupIdpath-yes
curl -X POST "$PANEL_URL/api/user/vm-instances/$ID/backups/$BACKUP_ID/recover" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-backup-createController: VmUserBackupController::createBackuproute source

Create VM backup Start an async vzdump backup. Returns 202 with backup_id. Poll GET /api/user/vm-instances/backup-status/{backupId} until status is done or failed. Fails with 422 if backup limit reached.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
storagestringnoProxmox storage (optional)
compressstringno
modestringno
Response data fieldTypeDescription
backup_idstring
curl -X POST "$PANEL_URL/api/user/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 not found · 422 Backup limit reached · 500 Proxmox error

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

Auth: Signed-in userDefault rate limit: 30 / minute (user-vm-instances)Route name: user-vm-instance-backup-statusController: VmUserBackupController::backupStatusroute source

Poll backup status Poll until status is done or failed. Use backup_id from create backup response.

ParameterInTypeRequiredDescription
backupIdpathstringyes
Response data fieldTypeDescription
statusstring
errorstring
curl -X GET "$PANEL_URL/api/user/vm-instances/backup-status/$BACKUP_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Status (running | done | failed) · 400 Invalid task · 401 Unauthorized · 404 Not found or access denied

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

Auth: VDS accessDefault rate limit: 10 / minuteRoute name: user-vm-instance-backup-deleteController: VmUserBackupController::deleteBackuproute source

Delete VM backup Delete a backup volume. Request body: volid and storage (from list backups).

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
volidstringyes
storagestringyes
curl -X DELETE "$PANEL_URL/api/user/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 Forbidden or backup does not belong to this VM · 404 VM not found

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

Auth: VDS accessDefault rate limit: 5 / minuteRoute name: user-vm-instance-restore-backupController: VmUserBackupController::restoreBackuproute source

Restore VM from backup Start async restore from a backup. Returns 202 with restore_id. Poll GET /api/user/vm-instances/restore-status/{restoreId} until status is active or failed.

ParameterInTypeRequiredDescription
idpathintegeryes
Body fieldTypeRequiredDescription
volidstringyes
storagestringyes
Response data fieldTypeDescription
restore_idstring
curl -X POST "$PANEL_URL/api/user/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 not found · 500 Proxmox error

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

Auth: Signed-in userDefault rate limit: 30 / minute (user-vm-instances)Route name: user-vm-instance-restore-statusController: VmUserBackupController::restoreBackupStatusroute source

Poll restore status Poll until status is active or failed. Use restore_id from restore backup response.

ParameterInTypeRequiredDescription
restoreIdpathstringyes
Response data fieldTypeDescription
statusstring
instanceobject
errorstring
curl -X GET "$PANEL_URL/api/user/vm-instances/restore-status/$RESTORE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Status (restoring | active | failed) · 400 Invalid task · 401 Unauthorized · 404 Not found or access denied