Admin API: node and allocation management endpoints

Nodes are the Wings daemon instances that host servers. The endpoints under /api/admin/nodes let you manage nodes, their allocations, and connection settings. The panel automatically generates the Wings configuration for each node.

List nodes

Returns a paginated list of all nodes.

GET /api/admin/nodes

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page (1–100).

string

Filter by node name.

Required admin permission: nodes.read

curl
Response

curl https://your-panel.example.com/api/admin/nodes \
  -H "Authorization: Bearer ptlc_YourAdminKey"

{
  "nodes": {
    "data": [
      {
        "uuid": "abc12345-...",
        "name": "US East 1",
        "deployment_enabled": true,
        "maintenance_enabled": false,
        "memory": 32768,
        "disk": 524288,
        "sftp_port": 2022,
        "created": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "per_page": 10,
    "page": 1
  }
}

Get a node

Returns a single node by UUID.

GET /api/admin/nodes/{node}

node

string (UUID)

required

The node UUID.

Required admin permission: nodes.read

Create a node

Registers a new Wings node with the panel.

POST /api/admin/nodes

location_uuid

string (UUID)

required

UUID of the location this node belongs to.

name

string

required

Node display name. Must be unique.

description

string

Optional description.

url

string

required

Internal URL the panel uses to communicate with Wings (e.g. https://10.0.0.5:8080).

public_url

string

Optional public-facing URL for WebSocket and SFTP connections. Falls back to url if not set.

sftp_host

string

Optional SFTP hostname. Falls back to the host in url if not set.

sftp_port

integer

required

SFTP port (default 2022).

memory

integer

required

Total allocatable memory in MiB.

disk

integer

required

Total allocatable disk in MiB.

deployment_enabled

boolean

default:"true"

Allow the panel to automatically deploy new servers to this node.

maintenance_enabled

boolean

default:"false"

Put the node in maintenance mode (existing servers continue running, no new deployments).

backup_configuration_uuid

string (UUID)

Optional backup configuration for node-level backups.

Required admin permission: nodes.create Returns 409 Conflict if a node with the same name already exists.

Update a node

Updates one or more node fields. All body fields are optional.

PATCH /api/admin/nodes/{node}

node

string (UUID)

required

The node UUID.

The request body accepts the same fields as the create endpoint. Required admin permission: nodes.update

Delete a node

Removes a node from the panel.

DELETE /api/admin/nodes/{node}

node

string (UUID)

required

The node UUID.

Required admin permission: nodes.delete

Deletion fails with 400 Bad Request if any servers are deployed on the node. Delete or transfer all servers first.

Get node configuration

Returns the Wings daemon configuration file content for this node. Use this to bootstrap a Wings instance.

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

node

string (UUID)

required

The node UUID.

Required admin permission: nodes.read

Reset daemon token

Generates a new authentication token for the Wings daemon. The old token is immediately invalidated.

POST /api/admin/nodes/{node}/reset-token

node

string (UUID)

required

The node UUID.

Required admin permission: nodes.update

After resetting the token, you must update the Wings configuration on the node and restart the daemon or it will lose contact with the panel.

Allocations

Allocations are IP/port combinations that can be assigned to servers as their primary or additional network endpoints.

List allocations for a node

GET /api/admin/nodes/{node}/allocations

node

string (UUID)

required

Node UUID.

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page.

Required admin permission: nodes.read

Create allocations

POST /api/admin/nodes/{node}/allocations

node

string (UUID)

required

Node UUID.

string

required

IP address for the allocations.

ports

string[]

required

List of ports or port ranges (e.g. ["25565", "25566-25570"]).

alias

string

Optional alias displayed instead of the IP.

Required admin permission: nodes.update

Node object fields

uuid

string

Node UUID.

name

string

Display name.

description

string | null

Optional description.

location

object

The location this node belongs to.

Show location properties

uuid

string

Location UUID.

short

string

Short location code.

long

string

Long location description.

deployment_enabled

boolean

Whether the node accepts automatic deployments.

maintenance_enabled

boolean

Whether the node is in maintenance mode.

url

string

Internal Wings daemon URL.

public_url

string | null

Public URL for WebSocket and SFTP.

sftp_host

string | null

SFTP hostname.

sftp_port

integer

SFTP port.

memory

integer

Total allocatable memory in MiB.

disk

integer

Total allocatable disk in MiB.

created

string

ISO 8601 creation timestamp.

Overview

Client API

Admin API

Admin API: node and allocation management endpoints

List nodes

Get a node

Create a node

Update a node

Delete a node

Get node configuration

Reset daemon token

Allocations

List allocations for a node

Create allocations

Node object fields

Build docs developers (and LLMs) love

Overview

Client API

Admin API

Documentation Index

​List nodes

​Get a node

​Create a node

​Update a node

​Delete a node

​Get node configuration

​Reset daemon token

​Allocations

​List allocations for a node

​Create allocations

​Node object fields

Build docs developers (and LLMs) love

List nodes

Get a node

Create a node

Update a node

Delete a node

Get node configuration

Reset daemon token

Allocations

List allocations for a node

Create allocations

Node object fields