VM Nodes endpoints (Admin API)

21 FeatherPanel Admin API endpoints from admin/vm-nodes.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/admin/vm-nodes.php. Authentication used here: Admin. 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/admin/vm-nodes`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodesController: VmNodesController::indexroute source

Get all Proxmox VM nodes Retrieve a paginated list of all VM nodes (Proxmox hypervisors) with optional search and VPS-location filtering.

Parameter	In	Type	Required	Description
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page
`search`	query	string	no	Search term to filter VM nodes by name or FQDN
`location_id`	query	integer	no	Location ID to filter VM nodes by (must be type=vps)

Response `data` field	Type	Description
`vm_nodes`	VmNode[]
`pagination`	VmNodePagination
`search`	object

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

Responses: 200 VM nodes retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET`/api/admin/vm-nodes/{id}`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-showController: VmNodesController::showroute source

Get VM node by ID Retrieve a specific VM node by its ID.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Response `data` field	Type	Description
`vm_node`	VmNode

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

Responses: 200 VM node retrieved successfully · 400 Bad request - Invalid VM node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM node not found

PUT`/api/admin/vm-nodes`

Auth: AdminPermission: admin.nodes.createRoute name: admin-vm-nodes-createController: VmNodesController::createroute source

Create new VM node Create a new VM node (Proxmox hypervisor) associated with a VPS/VDS location.

Request body: VmNodeCreate (application/json)

Body field	Type	Required	Description
`name`	string	yes	VM Node name
`description`	string	no	VM Node description
`location_id`	integer	yes	Location ID (must be type=vps)
`fqdn`	string	yes	Proxmox host FQDN or IP
`scheme`	string	no	Connection scheme
`port`	integer	no	Proxmox API port
`user`	string	yes	Proxmox API user (e.g. root@pam)
`token_id`	string	yes	Proxmox API token ID
`secret`	string	yes	Proxmox API token secret
`tls_no_verify`	string	no	Skip TLS verification
`timeout`	integer	no	Timeout in seconds
`addional_headers`	string	no	Additional HTTP headers (JSON encoded, optional)
`additional_params`	string	no	Additional query parameters (JSON encoded, optional)
`id`	integer	no	Optional VM node ID (useful for migrations)

Response `data` field	Type	Description
`vm_node`	VmNode

curl -X PUT "$PANEL_URL/api/admin/vm-nodes" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","description":"","location_id":0,"fqdn":"","scheme":"","port":0,"user":"","token_id":"","secret":"","tls_no_verify":"","timeout":0,"addional_headers":"","additional_params":"","id":0}'

Plugin events: featherpanel:vds:node:create

Responses: 201 VM node created successfully · 400 Bad request - Invalid JSON, validation errors, location not found or not VPS · 401 Unauthorized · 403 Forbidden - Insufficient permissions

PATCH`/api/admin/vm-nodes/{id}`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-updateController: VmNodesController::updateroute source

Update VM node Update an existing VM node. Only provided fields will be updated. Validates location existence and type.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Request body: VmNodeUpdate (application/json)

Body field	Type	Required	Description
`name`	string	no	VM Node name
`description`	string	no	VM Node description
`location_id`	integer	no	Location ID (must be type=vps)
`fqdn`	string	no	Proxmox host FQDN or IP
`scheme`	string	no	Connection scheme
`port`	integer	no	Proxmox API port
`user`	string	no	Proxmox API user (e.g. root@pam)
`token_id`	string	no	Proxmox API token ID
`secret`	string	no	Proxmox API token secret
`tls_no_verify`	string	no	Skip TLS verification
`timeout`	integer	no	Timeout in seconds
`addional_headers`	string	no	Additional HTTP headers (JSON encoded, optional)
`additional_params`	string	no	Additional query parameters (JSON encoded, optional)

Response `data` field	Type	Description
`vm_node`	VmNode

curl -X PATCH "$PANEL_URL/api/admin/vm-nodes/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","description":"","location_id":0,"fqdn":"","scheme":"","port":0,"user":"","token_id":"","secret":"","tls_no_verify":"","timeout":0,"addional_headers":"","additional_params":""}'

Plugin events: featherpanel:vds:node:update

Responses: 200 VM node updated successfully · 400 Bad request - Invalid JSON, no data provided, validation errors, location not found, or invalid location type · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM node not found

DELETE`/api/admin/vm-nodes/{id}`

Auth: AdminPermission: admin.nodes.deleteRoute name: admin-vm-nodes-deleteController: VmNodesController::deleteroute source

Delete VM node Permanently delete a VM node from the database. This does not touch the Proxmox host itself.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Response `data` field	Type	Description
`message`	string	Success message

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

Plugin events: featherpanel:vds:node:delete

Responses: 200 VM node deleted successfully · 400 Bad request - Invalid VM node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM node not found

GET`/api/admin/vm-nodes/{id}/test-connection`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-test-connectionController: VmNodesController::testConnectionroute source

Test connection to Proxmox VM node Performs a lightweight connectivity check to Proxmox using the stored API token and returns basic status and discovered cluster nodes.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Response `data` field	Type	Description
`ok`	boolean
`status_code`	integer
`latency_ms`	integer
`nodes`	object[]

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

Responses: 200 Connection successful · 400 Bad request - Invalid VM node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 VM node not found · 500 Connection failed

POST`/api/admin/vm-nodes/{id}/test-connection`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-test-connectionController: VmNodesController::testConnectionroute source

Test connection to Proxmox VM node Performs a lightweight connectivity check to Proxmox using the stored API token and returns basic status and discovered cluster nodes.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Response `data` field	Type	Description
`ok`	boolean
`status_code`	integer
`latency_ms`	integer
`nodes`	object[]

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

GET`/api/admin/vm-nodes/{id}/info`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-infoController: VmNodesController::getInforoute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/ips`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-ips-indexController: VmNodesController::listIpsroute source

List IPs for a VM node Retrieve all IP addresses configured for a specific VM node.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page

Response `data` field	Type	Description
`ips`	object[]
`pagination`	object

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

Responses: 200 VM node IPs retrieved successfully · 400 Invalid VM node ID · 404 VM node not found

PUT`/api/admin/vm-nodes/{id}/ips`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-ips-createController: VmNodesController::createIproute source

Create IP for VM node Create a new IP address for a specific VM node.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID

Body field	Type	Required	Description
`ip`	string	yes	IP address
`cidr`	integer	no	CIDR prefix length
`gateway`	string	no	Gateway IP
`is_primary`	string	no	Mark as primary IP
`notes`	string	no	Notes

curl -X PUT "$PANEL_URL/api/admin/vm-nodes/$ID/ips" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ip":"","cidr":0,"gateway":"","is_primary":"","notes":""}'

Plugin events: featherpanel:vds:node:ip:create

Responses: 201 IP created successfully · 400 Invalid VM node ID or payload · 404 VM node not found

PATCH`/api/admin/vm-nodes/{id}/ips/{ipId}`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-ips-updateController: VmNodesController::updateIproute source

Update IP for VM node Update an existing IP entry for a VM node.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID
`ipId`	path	integer	yes	VM IP ID

Body field	Type	Required	Description
`ip`	string	no	IP address
`cidr`	integer	no	CIDR prefix length
`gateway`	string	no	Gateway IP
`is_primary`	string	no	Mark as primary IP
`notes`	string	no	Notes

curl -X PATCH "$PANEL_URL/api/admin/vm-nodes/$ID/ips/$IP_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ip":"","cidr":0,"gateway":"","is_primary":"","notes":""}'

Plugin events: featherpanel:vds:node:ip:update

Responses: 200 IP updated successfully · 400 Invalid IDs or payload · 404 VM node or IP not found

DELETE`/api/admin/vm-nodes/{id}/ips/{ipId}`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-ips-deleteController: VmNodesController::deleteIproute source

Delete IP from VM node Delete an IP entry from a VM node.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID
`ipId`	path	integer	yes	VM IP ID

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

Plugin events: featherpanel:vds:node:ip:delete

Responses: 200 IP deleted successfully · 400 Invalid IDs · 404 VM node or IP not found

POST`/api/admin/vm-nodes/{id}/ips/{ipId}/primary`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-ips-set-primaryController: VmNodesController::setPrimaryIproute source

Set primary IP for VM node Mark a specific IP as the primary IP for a VM node. Clears the primary flag on all other IPs for this node.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	VM Node ID
`ipId`	path	integer	yes	VM IP ID

curl -X POST "$PANEL_URL/api/admin/vm-nodes/$ID/ips/$IP_ID/primary" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:vds:node:ip:primary

Responses: 200 Primary IP set successfully · 400 Invalid IDs · 404 VM node or IP not found

GET`/api/admin/vm-nodes/{id}/free-ips`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-free-ipsController: VmNodesController::freeIpsroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/proxmox-vms`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-proxmox-vmsController: VmNodesController::proxmoxVmsroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/cluster-nodes`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-cluster-nodesController: VmNodesController::clusterNodesroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/bridges`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-bridgesController: VmNodesController::bridgesroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/storage`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-storageController: VmNodesController::storageroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/backup-storage`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-backup-storageController: VmNodesController::backupStorageroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

GET`/api/admin/vm-nodes/{id}/templates`

Auth: AdminPermission: admin.nodes.viewRoute name: admin-vm-nodes-templatesController: VmNodesController::templatesroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

POST`/api/admin/vm-nodes/{id}/templates`

Auth: AdminPermission: admin.nodes.editRoute name: admin-vm-nodes-templates-createController: VmNodesController::createTemplateroute source

Parameter	In	Type	Required	Description
`id`	path	-	yes

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

Plugin events: featherpanel:vds:template:create

VM Nodes endpoints (Admin API)

Endpoints

GET/api/admin/vm-nodes

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

PUT/api/admin/vm-nodes

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

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

GET/api/admin/vm-nodes/{id}/test-connection

POST/api/admin/vm-nodes/{id}/test-connection

GET/api/admin/vm-nodes/{id}/info

GET/api/admin/vm-nodes/{id}/ips

PUT/api/admin/vm-nodes/{id}/ips

PATCH/api/admin/vm-nodes/{id}/ips/{ipId}

DELETE/api/admin/vm-nodes/{id}/ips/{ipId}

POST/api/admin/vm-nodes/{id}/ips/{ipId}/primary

GET/api/admin/vm-nodes/{id}/free-ips

GET/api/admin/vm-nodes/{id}/proxmox-vms

GET/api/admin/vm-nodes/{id}/cluster-nodes

GET/api/admin/vm-nodes/{id}/bridges

GET/api/admin/vm-nodes/{id}/storage

GET/api/admin/vm-nodes/{id}/backup-storage

GET/api/admin/vm-nodes/{id}/templates

POST/api/admin/vm-nodes/{id}/templates