Servers endpoints (Admin API)

GET/api/admin/servers

Get all servers Retrieve a paginated list of all servers with optional filtering by owner, node, realm, spell, and search functionality.

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

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

GET/api/admin/servers/{id}/mounts/assignable

Mounts that can be toggled for this server

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

GET/api/admin/servers/{id}

Get server by ID Retrieve a specific server by its ID with complete details including related data, variables, SFTP information, and recent activity.

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

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

GET/api/admin/servers/external/{externalId}

Get server by external ID Retrieve a specific server by its external ID with complete details including related data, variables, SFTP information, and recent activity.

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

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

PATCH/api/admin/servers/{id}

Update server Update an existing server with comprehensive validation, Wings synchronization, variable handling, and allocation management.

Request body: ServerUpdate (application/json)

curl -X PATCH "$PANEL_URL/api/admin/servers/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"node_id":0,"name":"","description":"","owner_id":0,"memory":0,"swap":0,"disk":0,"io":0,"cpu":0,"allocation_id":0,"realms_id":0,"spell_id":0,"startup":"","image":"","status":"","allocation_limit":0,"database_limit":0,"backup_limit":0,"external_id":"","threads":"","skip_scripts":false,"show_on_status":false,"auto_start":false,"auto_start_delay":0,"oom_disabled":false,"variables":{},"mount_ids":[]}'

Plugin events: featherpanel:server:reinstall, featherpanel:server:update

Responses: 200 Server updated successfully · 400 Bad request - Invalid JSON, invalid data types, validation errors, invalid foreign keys, or allocation in use · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 500 Internal server error - Failed to update server, Wings sync error, or variables update failed

DELETE/api/admin/servers/{id}

Delete server Permanently delete a server from the database and Wings daemon. Unclaims allocation and sends notification email to the server owner.

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

Plugin events: featherpanel:server:delete

Responses: 200 Server deleted successfully · 400 Bad request - Invalid server configuration · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 422 Unprocessable Entity - Invalid server data · 500 Internal server error - Failed to delete server or Wings error

DELETE/api/admin/servers/{id}/hard

Hard delete server Force delete a server from the database only, without contacting Wings. Use this only when Wings is unreachable or the node is dead. This will NOT remove server files from Wings.

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

Plugin events: featherpanel:server:delete

Responses: 200 Server hard deleted successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 500 Internal server error - Failed to delete server from database

PUT/api/admin/servers

Create new server Create a new server with comprehensive validation, Wings integration, variable handling, and email notifications.

Request body: ServerCreate (application/json)

curl -X PUT "$PANEL_URL/api/admin/servers" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"node_id":0,"name":"","description":"","owner_id":0,"memory":0,"swap":0,"disk":0,"io":0,"cpu":0,"allocation_id":0,"realms_id":0,"spell_id":0,"startup":"","image":"","status":"","allocation_limit":0,"database_limit":0,"backup_limit":0,"external_id":"","threads":"","skip_scripts":false,"show_on_status":false,"auto_start":false,"auto_start_delay":0,"oom_disabled":false,"variables":{},"mount_ids":[]}'

Plugin events: featherpanel:server:created

Responses: 201 Server created successfully · 400 Bad request - Invalid JSON, missing required fields, invalid data types, validation errors, invalid foreign keys, or allocation in use · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 User, node, allocation, realm, or spell not found · 422 Unprocessable Entity - Missing required spell variables or Wings validation failed · 500 Internal server error - Failed to create server, Wings error, or email sending failed

GET/api/admin/servers/owner/{ownerId}

Get servers by owner Retrieve all servers owned by a specific user.

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

Responses: 200 Servers retrieved successfully · 400 Bad request - Invalid owner ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/servers/node/{nodeId}

Get servers by node Retrieve all servers running on a specific node.

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

Responses: 200 Servers retrieved successfully · 400 Bad request - Invalid node ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/servers/realm/{realmId}

Get servers by realm Retrieve all servers belonging to a specific realm.

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

Responses: 200 Servers retrieved successfully · 400 Bad request - Invalid realm ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/servers/spell/{spellId}

Get servers by spell Retrieve all servers using a specific spell.

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

Responses: 200 Servers retrieved successfully · 400 Bad request - Invalid spell ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/servers/{id}/with-relations

Get server with relations Retrieve a specific server with all its related data including owner, node, realm, spell, and allocation information.

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

Responses: 200 Server with relations retrieved successfully · 400 Bad request - Invalid server ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found

GET/api/admin/servers/with-relations

Get all servers with relations Retrieve all servers with their related data including owner, node, realm, spell, and allocation information.

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

Responses: 200 Servers with relations retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions

GET/api/admin/servers/{id}/variables

Get server variables Retrieve all variables for a specific server with their spell variable definitions and metadata.

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

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

POST/api/admin/servers/{id}/custom-variables

curl -X POST "$PANEL_URL/api/admin/servers/$ID/custom-variables" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

DELETE/api/admin/servers/{id}/custom-variables/{variableId}

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

POST/api/admin/servers/{id}/suspend

Suspend server Suspend a server by killing it in Wings and updating the suspended status. Sends notification email to the server owner.

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

Plugin events: featherpanel:server:suspended

Responses: 200 Server suspended successfully · 400 Bad request - Invalid server configuration · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 422 Unprocessable Entity - Invalid server data · 500 Internal server error - Failed to suspend server or Wings error

POST/api/admin/servers/{id}/warn

Send warning to server owner Create an in-panel warning for the server owner (optionally emailed), e.g. high CPU stop notices.

curl -X POST "$PANEL_URL/api/admin/servers/$ID/warn" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"","message":"","type":"","send_email":false,"is_dismissible":false,"is_sticky":false}'

Responses: 201 Warning sent successfully · 400 Bad request · 401 Unauthorized · 403 Forbidden · 404 Server not found · 500 Internal server error

POST/api/admin/servers/{id}/unsuspend

Unsuspend server Unsuspend a server by updating the suspended status. Sends notification email to the server owner.

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

Plugin events: featherpanel:server:unsuspended

Responses: 200 Server unsuspended successfully · 400 Bad request - Invalid server ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 500 Internal server error - Failed to unsuspend server

POST/api/admin/servers/{id}/reconcile

Force runtime reconcile Asks Wings to recover a server stuck in starting/stopping or desynchronized from Docker/containerd.

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

Responses: 200 Reconciliation completed · 404 Server or node not found · 409 Server is busy (install/transfer/restore) · 500 Wings reconciliation failed

GET/api/admin/servers/{id}/runtime

Get Wings runtime health Returns the live Wings process state and runtime health (Docker desync detection).

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

Responses: 200 Runtime health · 404 Server or node not found · 500 Failed to query Wings

GET/api/admin/server-activities

Get all server activities Retrieve a paginated list of all server activities with optional filtering by server, node, user, and search functionality.

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

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

GET/api/admin/servers/{id}/activities

Get server activities by server ID Retrieve a paginated list of activities for a specific server with optional search functionality.

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

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

GET/api/admin/servers/{id}/allocations

Get server allocations (Admin) Retrieve all allocations assigned to a specific server.

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

Responses: 200 Server allocations retrieved successfully · 404 Server not found · 500 Internal server error

POST/api/admin/servers/{id}/allocations

Assign allocation to server (Admin) Assign a specific allocation to a server.

curl -X POST "$PANEL_URL/api/admin/servers/$ID/allocations" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"allocation_id":0}'

Responses: 200 Allocation assigned successfully · 400 Bad request · 404 Server or allocation not found · 500 Internal server error

DELETE/api/admin/servers/{serverId}/allocations/{allocationId}

Delete server allocation (Admin) Remove an allocation from a server. Cannot delete the primary allocation.

curl -X DELETE "$PANEL_URL/api/admin/servers/$SERVER_ID/allocations/$ALLOCATION_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Allocation deleted successfully · 400 Cannot delete primary allocation · 404 Server or allocation not found · 500 Internal server error

POST/api/admin/servers/{serverId}/allocations/{allocationId}/primary

Set primary allocation (Admin) Set a specific allocation as the primary allocation for the server.

curl -X POST "$PANEL_URL/api/admin/servers/$SERVER_ID/allocations/$ALLOCATION_ID/primary" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Primary allocation updated successfully · 400 Bad request · 404 Server or allocation not found · 500 Internal server error

POST/api/admin/servers/{id}/transfer

Initiate server transfer Start a transfer of a server from its current node to a destination node. Generates a transfer JWT token and instructs the source node to begin the transfer process.

curl -X POST "$PANEL_URL/api/admin/servers/$ID/transfer" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"destination_node_id":0,"destination_allocation_id":0,"backups":[],"include_all_backups":false,"delete_backups":false}'

Responses: 200 Server transfer initiated successfully · 400 Bad request - Invalid destination node, server already transferring, or same source and destination · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found or destination node not found · 500 Internal server error - Failed to initiate transfer or Wings error

GET/api/admin/servers/{id}/transfer

Get server transfer status Retrieve the current status of a server transfer including progress, start time, and any error messages.

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

Responses: 200 Transfer status retrieved successfully · 400 Bad request - Server is not being transferred · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 500 Internal server error - Failed to get transfer status

DELETE/api/admin/servers/{id}/transfer

Cancel server transfer Cancel an in-progress server transfer. This will revert the server to its original node and release any allocated resources on the destination node.

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

Plugin events: featherpanel:server:transfer:cancelled

Responses: 200 Transfer cancelled successfully · 400 Bad request - Server is not being transferred · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Server not found · 500 Internal server error - Failed to cancel transfer