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
List user VM instances Get VM instances owned by or accessible to the authenticated user. Supports optional pagination and search.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | no | Page number |
limit | query | integer | no | Records per page |
search | query | string | no | Search by hostname or IP |
Response data field | Type | Description |
|---|---|---|
instances | object[] | |
pagination | object |
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}
Get VM instance details Get detailed information about a specific VM instance.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
instance | object |
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
Get VM instance status Get current status and resource usage from Proxmox.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
status | object |
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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
bios | string | |
efi_enabled | boolean | |
tpm_enabled | boolean | |
serial0_enabled | boolean |
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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
bios | string | no | |
efi_enabled | boolean | no | |
tpm_enabled | boolean | no | |
serial0_enabled | boolean | no |
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
Get DNS options Returns current DNS settings (nameserver/searchdomain). Supports both QEMU and LXC.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
nameserver | string | |
searchdomain | string |
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
Get VM networking details Returns assigned IP addresses and current DNS settings for a VDS instance.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
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
Update DNS settings Updates nameserver (and searchdomain for LXC). Primary IP is intentionally not editable for normal users.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
nameserver | string | no | |
searchdomain | string | no |
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
List ISO storages Returns ISO-capable Proxmox storage names for the VM node.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
storages | string[] |
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
Get currently mounted ISO Returns currently mounted ISO (if any) by inspecting QEMU cdrom devices (media=cdrom).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
storage | string | yes | ISO storage name on Proxmox |
file | string (binary) | yes | ISO 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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
storage | string | no | ISO storage name on Proxmox |
url | string (uri) | no | Remote 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
Unmount ISO Unlinks cdrom devices (media=cdrom) and sets VM boot order back to the main disk.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
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
Get available templates Get available templates for the VM instance to reinstall. Limited to the VM type (qemu/lxc).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
templates | object[] |
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
VM power action Perform power action: start, stop, or reboot.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
action | string | no |
Response data field | Type | Description |
|---|---|---|
instance | object |
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
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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
Response data field | Type | Description |
|---|---|---|
ticket | string | |
port | integer | |
node | string | |
vmid | integer | |
host | string | |
port_api | integer | |
wss_url | string | |
pve_redirect_url | string | Proxmox 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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | VM instance ID |
| Body field | Type | Required | Description |
|---|---|---|---|
ci_user | string | no | Cloud-init username (required for QEMU/KVM) |
ci_password | string | no | Cloud-init password (required for QEMU/KVM) |
Response data field | Type | Description |
|---|---|---|
reinstall_id | string | |
message | string |
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}
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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
reinstallId | path | string | yes | Reinstall ID from start reinstall response |
Response data field | Type | Description |
|---|---|---|
status | string | |
message | string | When status=cloning |
error | string | When status=failed |
instance | object | When 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}
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
taskId | path | - | 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
List VM backups List backups for this VM instance. Returns backups, backup_limit (max allowed), and available Proxmox storages. Respects instance backup limit.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | VM instance ID |
Response data field | Type | Description |
|---|---|---|
backups | object[] | |
backup_limit | integer | Max backups allowed for this instance |
storages | string[] | 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
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | - | yes | |
backupId | path | - | 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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
storage | string | no | Proxmox storage (optional) |
compress | string | no | |
mode | string | no |
Response data field | Type | Description |
|---|---|---|
backup_id | string |
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}
Poll backup status Poll until status is done or failed. Use backup_id from create backup response.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
backupId | path | string | yes |
Response data field | Type | Description |
|---|---|---|
status | string | |
error | string |
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
Delete VM backup Delete a backup volume. Request body: volid and storage (from list backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
volid | string | yes | |
storage | string | yes |
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
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes |
| Body field | Type | Required | Description |
|---|---|---|---|
volid | string | yes | |
storage | string | yes |
Response data field | Type | Description |
|---|---|---|
restore_id | string |
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}
Poll restore status Poll until status is active or failed. Use restore_id from restore backup response.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
restoreId | path | string | yes |
Response data field | Type | Description |
|---|---|---|
status | string | |
instance | object | |
error | string |
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