Skip to main content
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)

Build docs developers (and LLMs) love

Get started for freeTalk to us