Server Management

List servers, retrieve details, manage power state, and connect to console

The server endpoints provide access to server information, power management, and real-time console connections.

List Servers

Get all servers the authenticated user has access to.

curl -X GET "https://panel.example.com/api/client" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "object": "list",
  "data": [
    {
      "object": "server",
      "attributes": {
        "server_owner": true,
        "identifier": "1a2b3c4d",
        "uuid": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
        "name": "My Minecraft Server",
        "node": "node01",
        "sftp_details": {
          "ip": "node01.example.com",
          "port": 2022
        },
        "description": "A server for friends",
        "limits": {
          "memory": 2048,
          "swap": 0,
          "disk": 10240,
          "io": 500,
          "cpu": 200,
          "threads": null,
          "oom_disabled": true
        },
        "invocation": "java -Xms128M -Xmx2048M -jar server.jar",
        "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
        "feature_limits": {
          "databases": 2,
          "allocations": 1,
          "backups": 3
        },
        "status": null,
        "is_suspended": false,
        "is_installing": false,
        "is_transferring": false
      }
    }
  ]
}

Get Server Details

Retrieve detailed information about a specific server.

curl -X GET "https://panel.example.com/api/client/servers/{server}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

server · string · required

The server identifier (short UUID)

Response

{
  "object": "server",
  "attributes": {
    "server_owner": true,
    "identifier": "1a2b3c4d",
    "internal_id": 5,
    "uuid": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "name": "My Minecraft Server",
    "node": "node01",
    "is_node_under_maintenance": false,
    "sftp_details": {
      "ip": "node01.example.com",
      "port": 2022
    },
    "description": "A server for friends",
    "limits": {
      "memory": 2048,
      "swap": 0,
      "disk": 10240,
      "io": 500,
      "cpu": 200,
      "threads": null,
      "oom_disabled": true
    },
    "invocation": "java -Xms128M -Xmx2048M -jar server.jar",
    "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
    "egg_features": ["eula", "java_version"],
    "feature_limits": {
      "databases": 2,
      "allocations": 1,
      "backups": 3
    },
    "status": null,
    "is_suspended": false,
    "is_installing": false,
    "is_transferring": false
  },
  "meta": {
    "is_server_owner": true,
    "user_permissions": [
      "control.console",
      "control.start",
      "control.stop",
      "control.restart",
      "user.read",
      "file.read",
      "file.write",
      "backup.create",
      "allocation.read",
      "startup.read",
      "database.read"
    ]
  }
}

server_owner · boolean

Whether the authenticated user owns this server

identifier · string

Short UUID identifier for the server

uuid · string

Full UUID of the server

name · string

Server display name

node · string

Name of the node hosting this server

limits · object

Resource limits for the server (memory in MB, disk in MB, CPU as percentage)

status · string|null

Current server status: null (ready), installing, suspended, restoring_backup

Get Resource Usage

Retrieve real-time resource utilization for a server.

curl -X GET "https://panel.example.com/api/client/servers/{server}/resources" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "object": "stats",
  "attributes": {
    "current_state": "running",
    "is_suspended": false,
    "resources": {
      "memory_bytes": 524288000,
      "cpu_absolute": 15.5,
      "disk_bytes": 2147483648,
      "network_rx_bytes": 1024000,
      "network_tx_bytes": 512000,
      "uptime": 3600
    }
  }
}

current_state · string

Current power state: running, starting, stopping, offline

resources.memory_bytes · integer

Current memory usage in bytes

resources.cpu_absolute · number

Current CPU usage percentage

resources.disk_bytes · integer

Current disk usage in bytes

resources.uptime · integer

Server uptime in seconds

Send Power Action

Change the power state of a server.

curl -X POST "https://panel.example.com/api/client/servers/{server}/power" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "signal": "start"
  }'

signal · string · required

Power action to perform:

• start - Start the server
• stop - Gracefully stop the server
• restart - Restart the server
• kill - Forcefully kill the server process

Response

Returns 204 No Content on success.

Send Console Command

Send a command to the server console.

curl -X POST "https://panel.example.com/api/client/servers/{server}/command" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "say Hello, world!"
  }'

command · string · required

The command to execute in the server console

Response

Returns 204 No Content on success.

WebSocket Connection

Get credentials to connect to the server’s WebSocket for real-time console access.

curl -X GET "https://panel.example.com/api/client/servers/{server}/websocket" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "socket": "wss://node01.example.com/api/servers/1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p/ws"
  }
}

token · string

JWT token for WebSocket authentication (valid for 10 minutes)

socket · string

WebSocket URL to connect to

WebSocket Usage

Connect to the WebSocket using the provided URL and token:

const ws = new WebSocket(socket);

ws.onopen = () => {
  // Authenticate with the token
  ws.send(JSON.stringify({
    event: 'auth',
    args: [token]
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Server event:', data);
};

// Send console output
ws.send(JSON.stringify({
  event: 'send command',
  args: ['say Hello!']
}));

// Set server state
ws.send(JSON.stringify({
  event: 'set state',
  args: ['start'] // or 'stop', 'restart', 'kill'
}));

WebSocket Events

Incoming Events:

• token expiring - Token will expire soon, request a new one
• token expired - Token has expired, connection will close
• status - Server status changed
• console output - Console log line
• stats - Resource usage update
• daemon message - Message from Wings daemon
• daemon error - Error from Wings daemon

Outgoing Events:

• auth - Authenticate with JWT token
• send command - Execute console command
• set state - Change power state
• send logs - Request console log history
• send stats - Request current resource stats

Get Activity Logs

Retrieve activity logs for a server.

curl -X GET "https://panel.example.com/api/client/servers/{server}/activity" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Query Parameters

page · integer

Page number for pagination

per_page · integer

Number of results per page (max 100)

sort · string

Sort field (prefix with - for descending)