Type at least two characters.

↑ ↓ moveEnter openEsc close
View .md

Web Nodes endpoints (Admin API)

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

Last synced from FeatherPanel 15b94e9 on .

On this page

Defined in backend/app/routes/admin/web-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/web-nodes

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodesController: WebNodesController::indexroute source

Get all FeatherQuilld web nodes Retrieve a paginated list of all web nodes (FeatherQuilld daemons) with optional search and web-location filtering.

ParameterInTypeRequiredDescription
pagequeryintegernoPage number for pagination
limitqueryintegernoNumber of records per page
searchquerystringnoSearch term to filter web nodes by name or FQDN
location_idqueryintegernoLocation ID to filter web nodes by (must be type=web)
curl -X GET "$PANEL_URL/api/admin/web-nodes" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

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

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

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-showController: WebNodesController::showroute source

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

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

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

PUT/api/admin/web-nodes

Auth: AdminPermission: admin.nodes.createRoute name: admin-web-nodes-createController: WebNodesController::createroute source

Create new web node Create a new web node (FeatherQuilld daemon) associated with a web hosting location. Daemon tokens are auto-generated.

Request body: WebNodeCreate (application/json)

Body fieldTypeRequiredDescription
namestringyesWeb Node name
descriptionstringnoWeb Node description
location_idintegeryesLocation ID (must be type=web)
fqdnstringyesFeatherQuilld host FQDN or IP
schemestringnoConnection scheme
publicbooleannoWhether the node is publicly visible
behind_proxybooleannoWhether the node is behind a reverse proxy
maintenance_modebooleannoWhether the node is in maintenance mode
memoryintegernoMemory allocation in MB
memory_overallocateintegernoMemory overallocation percentage
diskintegernoDisk allocation in MB
disk_overallocateintegernoDisk overallocation percentage
upload_sizeintegernoMax upload size in MB
daemonListenintegernoFeatherQuilld daemon listen port
daemonBasestringnoFeatherQuilld daemon base path
websitesPathstringnoPath where hosted websites are stored (defaults to {daemonBase}/websites)
backupsPathstringnoPath where website backups are stored (defaults to {daemonBase}/backups)
backupsProviderstringnoBackup storage provider: local or s3
backupsS3EndpointstringnoS3-compatible endpoint URL (empty = AWS default)
backupsS3RegionstringnoS3 region
backupsS3BucketstringnoS3 bucket name
backupsS3AccessKeystringnoS3 access key
backupsS3SecretKeystringnoS3 secret key
backupsS3PrefixstringnoS3 object key prefix
backupsS3ForcePathStylebooleannoForce path-style S3 addressing (MinIO, etc.)
addonsPathstringnoPlugins path; only emitted in config when explicitly set
quilldConfigOverridesstringnoOptional JSON merged into generated FeatherQuilld config
remoteTimeoutintegernoPanel API request timeout in seconds
remoteRetryLimitintegernoPanel API retry limit
remoteCustomHeadersstringnoOptional JSON object of custom HTTP headers (remote.custom_headers)
sftpEnabledbooleannoWhether SFTP is enabled
sftpKeyAlgorithmstringnoSSH key algorithm for SFTP
sftpPortintegernoSFTP listen port
sftpDisablePasswordAuthbooleannoDisable SFTP password authentication
proxyEnabledbooleannoWhether FeatherQuilld terminates HTTP(S) for WebSpaces
proxyProviderstringnoReverse proxy provider: caddy, nginx, or traefik
acmeEmailstringnoOptional ACME fallback email (site owner account email is preferred)
acmeStagingbooleannoUse Let’s Encrypt staging ACME directory
backendPortMinintegernoLoopback backend port range start (system.proxy.backend_port_min)
backendPortMaxintegernoLoopback backend port range end (system.proxy.backend_port_max)
idintegernoOptional web node ID (useful for migrations)
curl -X PUT "$PANEL_URL/api/admin/web-nodes" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","description":"","location_id":0,"fqdn":"","scheme":"","public":false,"behind_proxy":false,"maintenance_mode":false,"memory":0,"memory_overallocate":0,"disk":0,"disk_overallocate":0,"upload_size":0,"daemonListen":0,"daemonBase":"","websitesPath":"","backupsPath":"","backupsProvider":"","backupsS3Endpoint":"","backupsS3Region":"","backupsS3Bucket":"","backupsS3AccessKey":"","backupsS3SecretKey":"","backupsS3Prefix":"","backupsS3ForcePathStyle":false,"addonsPath":"","quilldConfigOverrides":"","remoteTimeout":0,"remoteRetryLimit":0,"remoteCustomHeaders":"","sftpEnabled":false,"sftpKeyAlgorithm":"","sftpPort":0,"sftpDisablePasswordAuth":false,"proxyEnabled":false,"proxyProvider":"","acmeEmail":"","acmeStaging":false,"backendPortMin":0,"backendPortMax":0,"id":0}'

Plugin events: featherpanel:web:node:create

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

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

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-updateController: WebNodesController::updateroute source

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

ParameterInTypeRequiredDescription
idpathintegeryesWeb Node ID

Request body: WebNodeUpdate (application/json)

Body fieldTypeRequiredDescription
namestringnoWeb Node name
descriptionstringnoWeb Node description
location_idintegernoLocation ID (must be type=web)
fqdnstringnoFeatherQuilld host FQDN or IP
schemestringnoConnection scheme
publicbooleannoWhether the node is publicly visible
behind_proxybooleannoWhether the node is behind a reverse proxy
maintenance_modebooleannoWhether the node is in maintenance mode
memoryintegernoMemory allocation in MB
memory_overallocateintegernoMemory overallocation percentage
diskintegernoDisk allocation in MB
disk_overallocateintegernoDisk overallocation percentage
upload_sizeintegernoMax upload size in MB
daemonListenintegernoFeatherQuilld daemon listen port
daemonBasestringnoFeatherQuilld daemon base path
websitesPathstringnoVolumes path (system.data); defaults to {daemonBase}/volumes
backupsPathstringnoBackup path (system.backup_directory); defaults to {daemonBase}/backups
backupsProviderstringnoBackup storage provider: local or s3
backupsS3EndpointstringnoS3-compatible endpoint URL (empty = AWS default)
backupsS3RegionstringnoS3 region
backupsS3BucketstringnoS3 bucket name
backupsS3AccessKeystringnoS3 access key
backupsS3SecretKeystringnoS3 secret key
backupsS3PrefixstringnoS3 object key prefix
backupsS3ForcePathStylebooleannoForce path-style S3 addressing (MinIO, etc.)
addonsPathstringnoPlugins path; only emitted in config when explicitly set
quilldConfigOverridesstringnoOptional JSON merged into generated FeatherQuilld config
remoteTimeoutintegernoPanel API request timeout in seconds
remoteRetryLimitintegernoPanel API retry limit
remoteCustomHeadersstringnoOptional JSON object of custom HTTP headers (remote.custom_headers)
sftpEnabledbooleannoWhether SFTP is enabled
sftpKeyAlgorithmstringnoSSH key algorithm for SFTP
sftpPortintegernoSFTP listen port
sftpDisablePasswordAuthbooleannoDisable SFTP password authentication
proxyEnabledbooleannoWhether FeatherQuilld terminates HTTP(S) for WebSpaces
proxyProviderstringnoReverse proxy provider: caddy, nginx, or traefik
acmeEmailstringnoOptional ACME fallback email (site owner account email is preferred)
acmeStagingbooleannoUse Let’s Encrypt staging ACME directory
backendPortMinintegernoLoopback backend port range start (system.proxy.backend_port_min)
backendPortMaxintegernoLoopback backend port range end (system.proxy.backend_port_max)
curl -X PATCH "$PANEL_URL/api/admin/web-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":"","public":false,"behind_proxy":false,"maintenance_mode":false,"memory":0,"memory_overallocate":0,"disk":0,"disk_overallocate":0,"upload_size":0,"daemonListen":0,"daemonBase":"","websitesPath":"","backupsPath":"","backupsProvider":"","backupsS3Endpoint":"","backupsS3Region":"","backupsS3Bucket":"","backupsS3AccessKey":"","backupsS3SecretKey":"","backupsS3Prefix":"","backupsS3ForcePathStyle":false,"addonsPath":"","quilldConfigOverrides":"","remoteTimeout":0,"remoteRetryLimit":0,"remoteCustomHeaders":"","sftpEnabled":false,"sftpKeyAlgorithm":"","sftpPort":0,"sftpDisablePasswordAuth":false,"proxyEnabled":false,"proxyProvider":"","acmeEmail":"","acmeStaging":false,"backendPortMin":0,"backendPortMax":0}'

Plugin events: featherpanel:web:node:update

Responses: 200 Web 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 Web node not found

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

Auth: AdminPermission: admin.nodes.deleteRoute name: admin-web-nodes-deleteController: WebNodesController::deleteroute source

Delete web node Permanently delete a web node from the database. This does not touch the FeatherQuilld daemon itself.

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

Plugin events: featherpanel:web:node:delete

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

POST/api/admin/web-nodes/{id}/reset-token

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-reset-tokenController: WebNodesController::resetTokenroute source

Reset FeatherQuilld daemon token Generate a new daemon token ID and secret for the web node. The FeatherQuilld daemon must be reconfigured with the new credentials.

ParameterInTypeRequiredDescription
idpathintegeryesWeb Node ID
curl -X POST "$PANEL_URL/api/admin/web-nodes/$ID/reset-token" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:web:node:key:reset

Responses: 200 Daemon token reset successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Web node not found

GET/api/admin/web-nodes/{id}/setup-command

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-setup-commandController: WebNodesController::getSetupCommandroute source

Get FeatherQuilld setup command Returns install command (step 1) and setup command (step 2) to configure the web node. Step 2 embeds full panel-generated config via join-data (Calagopus-style) or fetches from the panel.

ParameterInTypeRequiredDescription
idpathintegeryesWeb Node ID
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/setup-command" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Setup commands (install + config) · 401 Unauthorized · 403 Forbidden · 404 Web node not found

GET/api/admin/web-nodes/{id}/config

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-configController: WebNodesController::getConfigroute source

Get FeatherQuilld config YAML Returns the full FeatherQuilld config.yml content for this web node (for manual copy or inspection).

ParameterInTypeRequiredDescription
idpathintegeryesWeb Node ID
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/config" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 FeatherQuilld config YAML · 401 Unauthorized · 403 Forbidden · 404 Web node not found

GET/api/admin/web-nodes/{id}/health

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-healthController: WebNodesController::healthCheckroute source

Probe FeatherQuilld daemon health Calls GET /api/system/health on the web node daemon using its stored credentials.

ParameterInTypeRequiredDescription
idpathintegeryesWeb Node ID
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/health" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Health probe result · 401 Unauthorized · 403 Forbidden · 404 Web node not found

GET/api/admin/web-nodes/{id}/system

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-systemController: WebNodesController::systemInforoute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/system" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/utilization

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-utilizationController: WebNodesController::utilizationroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/utilization" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/diagnostics

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-diagnosticsController: WebNodesController::diagnosticsroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/diagnostics" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/system-logs

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-system-logsController: WebNodesController::systemLogsroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/system-logs" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/system-logs/{file}

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-system-log-fileController: WebNodesController::systemLogFileroute source
ParameterInTypeRequiredDescription
idpath-yes
filepath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/system-logs/$FILE" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/packages

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-packagesController: WebNodesController::packagesroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/packages" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/packages/socket

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-packages-socketController: WebNodesController::packageSocketroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/packages/socket" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

POST/api/admin/web-nodes/{id}/packages/{packageId}/install

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-packages-installController: WebNodesController::installPackageroute source
ParameterInTypeRequiredDescription
idpath-yes
packageIdpath-yes
curl -X POST "$PANEL_URL/api/admin/web-nodes/$ID/packages/$PACKAGE_ID/install" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

POST/api/admin/web-nodes/{id}/packages/{packageId}/remove

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-packages-removeController: WebNodesController::removePackageroute source
ParameterInTypeRequiredDescription
idpath-yes
packageIdpath-yes
curl -X POST "$PANEL_URL/api/admin/web-nodes/$ID/packages/$PACKAGE_ID/remove" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET/api/admin/web-nodes/{id}/version-status

Auth: AdminPermission: admin.nodes.viewRoute name: admin-web-nodes-version-statusController: WebNodesController::versionStatusroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X GET "$PANEL_URL/api/admin/web-nodes/$ID/version-status" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

POST/api/admin/web-nodes/{id}/self-update

Auth: AdminPermission: admin.nodes.editRoute name: admin-web-nodes-self-updateController: WebNodesController::triggerSelfUpdateroute source
ParameterInTypeRequiredDescription
idpath-yes
curl -X POST "$PANEL_URL/api/admin/web-nodes/$ID/self-update" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
Written from the source:FeatherPanel/backend/app/routes/admin/web-nodes.php
View source on GitHubReport a problemLast updated