Skip to main content
Version: v1.0+

Server Management

Manage your servers including power states, resource monitoring, console access, and command execution.

Source Code References

All Client API server management endpoints are implemented in the Pterodactyl Panel source code:

List Servers

Retrieve a list of all servers you have access to.

GET /api/client

Source Reference

Example Request

GET /api/client
curl "https://your-panel.com/api/client" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Example Response

{
"object": "list",
"data": [
{
"object": "server",
"attributes": {
"server_owner": true,
"identifier": "d3aac109",
"internal_id": 4,
"uuid": "d3aac109-e5e0-4331-b03e-3454f7e136dc",
"name": "Survival Server",
"description": "A vanilla Minecraft survival server",
"status": null,
"is_suspended": false,
"is_installing": false,
"is_transferring": false,
"node": "Node 1",
"sftp_details": {
"ip": "node.example.com",
"port": 2022
},
"invocation": "java -Xms128M -Xmx1024M -jar server.jar",
"docker_image": "ghcr.io/pterodactyl/yolks:java_17",
"egg_features": [
"eula",
"java_version",
"pid_limit"
],
"feature_limits": {
"databases": 2,
"allocations": 1,
"backups": 10
},
"user_permissions": [
"control.console",
"control.start",
"control.stop",
"control.restart"
],
"limits": {
"memory": 1024,
"swap": 0,
"disk": 5120,
"io": 500,
"cpu": 200,
"threads": null
},
"relationships": {
"allocations": {
"object": "list",
"data": [
{
"object": "allocation",
"attributes": {
"id": 1,
"ip": "45.86.168.218",
"ip_alias": null,
"port": 25565,
"notes": null,
"is_default": true
}
}
]
},
"variables": {
"object": "list",
"data": [
{
"object": "egg_variable",
"attributes": {
"name": "Server Jar File",
"description": "The name of the server jarfile to run the server with.",
"env_variable": "SERVER_JARFILE",
"default_value": "server.jar",
"server_value": "server.jar",
"is_editable": true,
"rules": "required|regex:/^([\\w\\d._-]+)(\\.jar)$/"
}
}
]
}
}
}
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 25,
"current_page": 1,
"total_pages": 1,
"links": {}
}
}
}

Query Parameters

ParameterTypeDescription
includestringComma-separated list of relationships to include (allocations, variables)
pageintegerPage number for pagination
per_pageintegerNumber of servers per page (max 100)

Get Server Details

Retrieve detailed information about a specific server.

GET /api/client/servers/{server}

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)

Example Request

GET /api/client/servers/{server}
curl "https://your-panel.com/api/client/servers/d3aac109" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Example Response

{
"object": "server",
"attributes": {
"server_owner": true,
"identifier": "d3aac109",
"internal_id": 4,
"uuid": "d3aac109-e5e0-4331-b03e-3454f7e136dc",
"name": "Survival Server",
"description": "A vanilla Minecraft survival server",
"status": "running",
"is_suspended": false,
"is_installing": false,
"is_transferring": false,
"node": "Node 1",
"sftp_details": {
"ip": "node.example.com",
"port": 2022
},
"invocation": "java -Xms128M -Xmx1024M -jar server.jar",
"docker_image": "ghcr.io/pterodactyl/yolks:java_17",
"egg_features": [
"eula",
"java_version",
"pid_limit"
],
"feature_limits": {
"databases": 2,
"allocations": 1,
"backups": 10
},
"user_permissions": [
"control.console",
"control.start",
"control.stop",
"control.restart"
],
"limits": {
"memory": 1024,
"swap": 0,
"disk": 5120,
"io": 500,
"cpu": 200,
"threads": null
}
}
}

Server Resource Usage

Get real-time resource usage statistics for a server.

GET /api/client/servers/{server}/resources

Example Request

GET /api/client/servers/{server}/resources
curl "https://your-panel.com/api/client/servers/d3aac109/resources" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Example Response

{
"object": "stats",
"attributes": {
"current_state": "running",
"is_suspended": false,
"resources": {
"memory_bytes": 671088640,
"memory_limit_bytes": 1073741824,
"cpu_absolute": 1.522,
"disk_bytes": 2147483648,
"network_rx_bytes": 676237,
"network_tx_bytes": 1097738,
"uptime": 3600000
}
}
}

Resource Fields

FieldDescription
memory_bytesCurrent memory usage in bytes
memory_limit_bytesMaximum memory allowed in bytes
cpu_absoluteCurrent CPU usage percentage
disk_bytesCurrent disk usage in bytes
network_rx_bytesTotal bytes received
network_tx_bytesTotal bytes transmitted
uptimeServer uptime in milliseconds

Power Management

Control server power states including start, stop, restart, and kill operations.

Source Reference

Start Server

POST /api/client/servers/{server}/power

Request Body

FieldTypeRequiredDescription
signalstringYesPower action: start, stop, restart, kill

Example Request

POST /api/client/servers/{server}/power
curl -X POST "https://your-panel.com/api/client/servers/d3aac109/power" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"signal": "restart"
}'

Success Response (204)

Returns empty response body with status code 204.

Power Actions

ActionDescription
startStart the server
stopGracefully stop the server
restartRestart the server
killForce kill the server process

Error Responses

Server Already Running (400)

{
"errors": [
{
"code": "ConflictingServerStateException",
"status": "400",
"detail": "Cannot start server, server is already running."
}
]
}

Server Installing (400)

{
"errors": [
{
"code": "ConflictingServerStateException",
"status": "400",
"detail": "Cannot perform power action, server is currently installing."
}
]
}

Console Access

WebSocket Console Connection

Connect to the server console via WebSocket for real-time input/output.

GET /api/client/servers/{server}/websocket

This endpoint returns authentication details for establishing a WebSocket connection.

Example Request

GET /api/client/servers/{server}/websocket
curl "https://your-panel.com/api/client/servers/d3aac109/websocket" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Example Response

{
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"socket": "wss://node.example.com:8080/api/servers/d3aac109-e5e0-4331-b03e-3454f7e136dc/ws"
}
}

WebSocket Connection

Use the returned token and socket URL to establish a WebSocket connection:

const socket = new WebSocket('wss://node.example.com:8080/api/servers/d3aac109-e5e0-4331-b03e-3454f7e136dc/ws');

socket.addEventListener('open', function (event) {
// Authenticate with the WebSocket
socket.send(JSON.stringify({
event: 'auth',
args: ['eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...']
}));
});

socket.addEventListener('message', function (event) {
const data = JSON.parse(event.data);
console.log('Console output:', data);
});

WebSocket Events

EventDirectionDescription
authSendAuthenticate with the token
send commandSendExecute a command on the server
set stateSendRequest server state updates
console outputReceiveReal-time console output
statusReceiveServer status changes
statsReceiveResource usage updates

Send Console Command

Execute a command on the server console.

POST /api/client/servers/{server}/command

Request Body

FieldTypeRequiredDescription
commandstringYesCommand to execute on the server

Example Request

POST /api/client/servers/{server}/command
curl -X POST "https://your-panel.com/api/client/servers/d3aac109/command" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"command": "say Hello from the API!"
}'

Success Response (204)

Returns empty response body with status code 204.

Error Responses

Server Offline (400)

{
"errors": [
{
"code": "ConflictingServerStateException",
"status": "400",
"detail": "Cannot send command to stopped server."
}
]
}

Missing Permissions (403)

{
"errors": [
{
"code": "InsufficientPermissionsException",
"status": "403",
"detail": "This action requires the 'control.console' permission."
}
]
}

Server Settings

Update Server Details

Update basic server information like name and description.

POST /api/client/servers/{server}/settings/rename

Request Body

FieldTypeRequiredDescription
namestringYesNew server name (max 255 characters)
descriptionstringNoNew server description (max 500 characters)

Example Request

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/settings/rename" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"name": "New Server Name",
"description": "Updated server description"
}'

Success Response (204)

Returns empty response body with status code 204.

Reinstall Server

Trigger a server reinstallation with a fresh copy of the egg.

POST /api/client/servers/{server}/settings/reinstall

Example Request

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/settings/reinstall" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Success Response (202)

Returns empty response body with status code 202.

Important

Reinstalling a server will permanently delete all files and reinstall the server from scratch. Make sure to create backups before reinstalling.

Update Docker Image

Change the Docker image used by the server.

PUT /api/client/servers/{server}/settings/docker-image

Request Body

FieldTypeRequiredDescription
docker_imagestringYesNew Docker image to use for the server

Example Request

PUT /api/client/servers/{server}/settings/docker-image
curl -X PUT "https://your-panel.com/api/client/servers/d3aac109/settings/docker-image" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"docker_image": "ghcr.io/pterodactyl/yolks:java_17"
}'

Success Response (204)

Returns empty response body with status code 204.

Error Responses

Invalid Docker Image (422)

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The selected docker image is invalid.",
"meta": {
"rule": "in"
}
}
]
}

Missing Permissions (403)

{
"errors": [
{
"code": "InsufficientPermissionsException",
"status": "403",
"detail": "This action requires the 'startup.docker-image' permission."
}
]
}
Available Images

The available Docker images are defined by the server's egg configuration. Use the startup configuration endpoint to see available images in the meta.docker_images field.


Common Error Codes

StatusCodeDescription
400ConflictingServerStateExceptionServer is in a state that prevents the action
401InvalidCredentialsExceptionInvalid API key
403InsufficientPermissionsExceptionMissing required permissions
404NotFoundHttpExceptionServer not found or no access
409TooManyRequestsHttpExceptionRate limit exceeded

Required Permissions

Different server actions require specific permissions:

PermissionDescription
control.consoleView console output and send commands
control.startStart the server
control.stopStop the server
control.restartRestart the server
control.killForce kill server process
admin.websocketAccess WebSocket console
settings.renameUpdate server name and description
settings.reinstallReinstall the server
startup.readView startup configuration and variables
startup.updateModify startup variables
startup.docker-imageChange Docker image

Startup Configuration

Retrieve and update server startup configuration including environment variables.

Get Startup Configuration

Retrieve the current startup configuration and environment variables for a server.

GET /api/client/servers/{server}/startup

Example Request

GET /api/client/servers/{server}/startup
curl "https://your-panel.com/api/client/servers/d3aac109/startup" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Example Response

{
"object": "list",
"data": [
{
"object": "egg_variable",
"attributes": {
"name": "Server Jar File",
"description": "The name of the server jarfile to run the server with.",
"env_variable": "SERVER_JARFILE",
"default_value": "server.jar",
"server_value": "server.jar",
"is_editable": true,
"rules": "required|regex:/^([\\w\\d._-]+)(\\.jar)$/"
}
},
{
"object": "egg_variable",
"attributes": {
"name": "Server Version",
"description": "The version of Minecraft to download and use.",
"env_variable": "MINECRAFT_VERSION",
"default_value": "latest",
"server_value": "1.19.4",
"is_editable": true,
"rules": "required|string|between:1,20"
}
}
],
"meta": {
"startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"raw_startup_command": "java -Xms128M -Xmx1024M -jar server.jar",
"docker_images": {
"ghcr.io/pterodactyl/yolks:java_17": "Java 17",
"ghcr.io/pterodactyl/yolks:java_11": "Java 11",
"ghcr.io/pterodactyl/yolks:java_8": "Java 8"
}
}
}

Update Startup Variable

Update a specific environment variable for the server startup configuration.

PUT /api/client/servers/{server}/startup/variable

Request Body

FieldTypeRequiredDescription
keystringYesEnvironment variable name
valuestringYesNew value for the variable

Example Request

PUT /api/client/servers/{server}/startup/variable
curl -X PUT "https://your-panel.com/api/client/servers/d3aac109/startup/variable" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"key": "MINECRAFT_VERSION",
"value": "1.20.1"
}'

Example Response

{
"object": "egg_variable",
"attributes": {
"name": "Server Version",
"description": "The version of Minecraft to download and use.",
"env_variable": "MINECRAFT_VERSION",
"default_value": "latest",
"server_value": "1.20.1",
"is_editable": true,
"rules": "required|string|between:1,20"
}
}

Variable Field Descriptions

FieldDescription
nameHuman-readable variable name
descriptionDescription of what the variable controls
env_variableEnvironment variable name used in startup command
default_valueDefault value defined by the egg
server_valueCurrent value set for this server
is_editableWhether the variable can be modified by users
rulesValidation rules for the variable value

Error Responses

Variable Not Found (422)

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The selected key is invalid.",
"meta": {
"rule": "in"
}
}
]
}

Invalid Value (422)

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The value field must be between 1 and 20 characters.",
"meta": {
"rule": "between"
}
}
]
}

Variable Not Editable (400)

{
"errors": [
{
"code": "BadRequestException",
"status": "400",
"detail": "This environment variable is not editable."
}
]
}

Next Steps