Nodes endpoints (Admin API)

GET/api/admin/nodes/status/global

Get global node status and utilization Retrieve aggregated utilization and status information from all nodes including CPU, memory, disk usage, and health status.

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

Responses: 200 Global node status retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/nodes

Get all nodes Retrieve a paginated list of all nodes with optional search functionality.

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

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

GET/api/admin/nodes/{id}

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

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

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

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

Generate node diagnostics bundle Fetches diagnostics output from the Wings daemon. Returns plain-text content by default or an uploaded report URL when format=url.

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

Responses: 200 Diagnostics generated successfully · 400 Bad request - Invalid query parameters · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to generate diagnostics

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

List node system log files Lists daemon log files via Calagopus GET /api/system/logs.

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

Responses: 200 System logs listed successfully · 404 Node not found · 500 Failed to list system logs · 501 Daemon feature unsupported

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

Read a node system log file Reads a daemon log file via Calagopus GET /api/system/logs/{file}.

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

Responses: 200 System log file retrieved successfully · 400 Invalid log file name · 404 Node not found · 500 Failed to read system log · 501 Daemon feature unsupported

PATCH/api/admin/nodes/{id}

Update node Update an existing node. Only provided fields will be updated. Validates location existence and UUID format.

Request body: NodeUpdate (application/json)

curl -X PATCH "$PANEL_URL/api/admin/nodes/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","fqdn":"","location_id":0,"uuid":"","daemon_type":"","public_ip_v4":"","public_ip_v6":"","sftp_subdomain":""}'

Plugin events: featherpanel:admin:nodes:node:updated

Responses: 200 Node updated successfully · 400 Bad request - Invalid JSON, no data provided, validation errors, location not found, or invalid UUID format · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to update node

DELETE/api/admin/nodes/{id}

Delete node Permanently delete a node from the database. This action cannot be undone.

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

Plugin events: featherpanel:admin:nodes:node:deleted

Responses: 200 Node deleted successfully · 400 Bad request - Invalid node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to delete node

PUT/api/admin/nodes

Create new node Create a new node with name, FQDN, and location. Automatically generates UUID and daemon tokens. Validates location existence and ensures UUID uniqueness.

Request body: NodeCreate (application/json)

curl -X PUT "$PANEL_URL/api/admin/nodes" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","fqdn":"","location_id":0,"daemon_type":"","public_ip_v4":"","public_ip_v6":"","sftp_subdomain":"","id":0}'

Plugin events: featherpanel:admin:nodes:node:created

Responses: 201 Node created successfully · 400 Bad request - Invalid JSON, validation errors, location not found, or UUID already exists · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 500 Internal server error - Failed to create node

POST/api/admin/nodes/{id}/reset-key

Reset node daemon tokens Generate new daemon token ID and daemon token for a node. This invalidates the current tokens and requires the node to be reconfigured with the new tokens.

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

Responses: 200 Node daemon tokens reset successfully · 400 Bad request - Invalid node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to reset node tokens

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

Get node setup command Returns install command (step 1) and setup command (step 2) to configure the node. Step 1 installs FeatherWings only; step 2 runs the interactive featherwings configure wizard.

curl -X GET "$PANEL_URL/api/admin/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 Node not found

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

Trigger Wings self-update Initiate a self-update on the Wings daemon either via GitHub release channel or a custom download URL.

curl -X POST "$PANEL_URL/api/admin/nodes/$ID/self-update" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"source":"","version":"","url":"","repo_owner":"","repo_name":"","sha256":"","force":false,"disable_checksum":false}'

Responses: 200 Self-update already applied or not required · 202 Self-update accepted and queued · 400 Bad request - Invalid payload or updates disabled · 401 Unauthorized · 403 Forbidden - Insufficient permissions or API updates disabled · 404 Node not found · 500 Failed to trigger self-update

POST/api/admin/nodes/{id}/terminal/exec

Execute command on node host Execute a command on the node host system via Wings terminal API. Requires system.host_terminal.enabled=true in Wings config.

curl -X POST "$PANEL_URL/api/admin/nodes/$ID/terminal/exec" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command":"","timeout_seconds":0,"working_directory":"","environment":{}}'

Responses: 200 Command executed successfully · 400 Bad request - Invalid payload or missing command · 401 Unauthorized · 403 Forbidden - Insufficient permissions or host terminal disabled · 404 Node not found · 500 Internal server error - Failed to execute command · 504 Gateway Timeout - Command execution timed out

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

Get Wings configuration Retrieve the complete Wings configuration file as raw YAML with all comments preserved.

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

Responses: 200 Wings configuration retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to retrieve configuration

PUT/api/admin/nodes/{id}/config

Replace Wings configuration Replace the entire Wings configuration file with new YAML content. All comments and formatting are preserved. Optionally restart Wings after update.

curl -X PUT "$PANEL_URL/api/admin/nodes/$ID/config" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"config":"","restart":false}'

Responses: 200 Configuration updated successfully · 400 Bad request - Invalid JSON or missing config · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to update configuration

PATCH/api/admin/nodes/{id}/config/patch

Patch Wings configuration values Update specific configuration values using dot notation (e.g., "api.port", "system.root_directory"). Preserves comments and other values.

curl -X PATCH "$PANEL_URL/api/admin/nodes/$ID/config/patch" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"values":{},"restart":false}'

Responses: 200 Configuration patched successfully · 400 Bad request - Invalid JSON or missing values · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to patch configuration

GET/api/admin/nodes/{id}/config/schema

Get Wings configuration schema Retrieve a schema describing all configurable fields in the Wings configuration, useful for building GUIs.

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

Responses: 200 Configuration schema retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to retrieve schema

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

Check FeatherWings version status Check if the node's FeatherWings version matches the latest version available on GitHub. Compares the installed version with the latest release from mythicalltd/featherwings repository.

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

Responses: 200 Version status retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Node not found · 500 Internal server error - Failed to check version status

GET/api/admin/nodes/{id}/wings/config

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

PUT/api/admin/nodes/{id}/wings/config

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

POST/api/admin/nodes/{id}/wings/config

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

GET/api/admin/nodes/{id}/mass-transfer/preview

Preview mass server transfer from a node Lists transferable servers on the source node and free allocation capacity on a destination node.

curl -X GET "$PANEL_URL/api/admin/nodes/$ID/mass-transfer/preview?destination_node_id=$DESTINATION_NODE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Preview retrieved successfully · 400 Bad request · 404 Node not found

POST/api/admin/nodes/{id}/mass-transfer

Mass transfer servers from a node Transfer selected servers (or all transferable servers) from this node to another. Free allocations on the destination node are assigned automatically.

curl -X POST "$PANEL_URL/api/admin/nodes/$ID/mass-transfer" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"destination_node_id":0,"server_ids":[],"move_all":false}'

Responses: 200 Mass transfer processed · 400 Bad request · 404 Node not found