Skip to main content
Version: v1.0+

Server Management

The Application API Server Management endpoints allow administrators to manage all servers in the panel. These endpoints provide comprehensive server lifecycle management including creation, configuration, suspension, and deletion.

Administrative Access Required

These endpoints require administrative privileges and should only be used by trusted applications with proper authentication.

Authentication

All Application API requests require authentication using an API key with appropriate permissions:

Authorization: Bearer YOUR_APPLICATION_API_KEY
Accept: Application/vnd.pterodactyl.v1+json
Content-Type: application/json

List All Servers

Retrieve a paginated list of all servers in the panel.

GET /api/application/servers

Query Parameters

ParameterTypeDescriptionDefault
pageintegerPage number for pagination1
per_pageintegerResults per page (1-100)50
filter[name]stringFilter by server name-
filter[uuid]stringFilter by server UUID-
filter[external_id]stringFilter by external ID-
filter[image]stringFilter by Docker image-
sortstringSort field (id, uuid, name, created_at, updated_at)id
includestringInclude relationships (allocations, user, subusers, pack, nest, egg, variables, location, node, databases, backups)-

Example Request

curl "https://your-panel.com/api/application/servers?include=user,node&per_page=25" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Example Response

{
"object": "list",
"data": [
{
"object": "server",
"attributes": {
"id": 1,
"external_id": null,
"uuid": "d3aac109-e5e0-4331-b03e-3454f7e02bbe",
"identifier": "d3aac109",
"name": "Minecraft Server",
"description": "A fun Minecraft server for friends",
"status": null,
"suspended": false,
"limits": {
"memory": 512,
"swap": 0,
"disk": 1024,
"io": 500,
"cpu": 100,
"threads": null,
"oom_disabled": false
},
"feature_limits": {
"databases": 1,
"allocations": 1,
"backups": 1
},
"user": 1,
"node": 1,
"allocation": 1,
"nest": 1,
"egg": 1,
"container": {
"startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"image": "quay.io/pterodactyl/core:java",
"installed": true,
"environment": {
"MINECRAFT_VERSION": "latest",
"SERVER_JARFILE": "server.jar",
"BUILD_TYPE": "recommended"
}
},
"created_at": "2024-01-15T10:26:32+00:00",
"updated_at": "2024-01-15T10:26:32+00:00"
},
"relationships": {
"user": {
"object": "user",
"attributes": {
"id": 1,
"username": "admin",
"email": "[email protected]"
}
},
"node": {
"object": "node",
"attributes": {
"id": 1,
"public": true,
"name": "Node 1",
"fqdn": "node1.example.com"
}
}
}
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 50,
"current_page": 1,
"total_pages": 1,
"links": {}
}
}
}

Get Server Details

Retrieve detailed information about a specific server.

GET /api/application/servers/{server}

Path Parameters

ParameterTypeDescription
serverintegerServer ID

Query Parameters

ParameterTypeDescription
includestringInclude relationships (allocations, user, subusers, pack, nest, egg, variables, location, node, databases, backups)

Example Request

curl "https://your-panel.com/api/application/servers/1?include=allocations,user,node" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Create New Server

Create a new server in the panel.

POST /api/application/servers

Request Body

FieldTypeRequiredDescription
namestringYesServer name
userintegerYesUser ID who owns the server
eggintegerYesEgg ID to use for the server
docker_imagestringNoOverride default Docker image
startupstringNoOverride default startup command
environmentobjectNoEnvironment variables
limitsobjectYesResource limits
feature_limitsobjectYesFeature limits
allocationobjectYesPrimary allocation configuration
deployobjectNoDeployment configuration

Limits Object

FieldTypeRequiredDescription
memoryintegerYesMemory limit in MB
swapintegerYesSwap limit in MB (0 to disable)
diskintegerYesDisk space limit in MB
iointegerYesBlock IO weight (10-1000)
cpuintegerYesCPU limit percentage
threadsstringNoCPU thread pinning
oom_disabledbooleanNoDisable OOM killer

Feature Limits Object

FieldTypeRequiredDescription
databasesintegerYesMaximum databases allowed
allocationsintegerYesMaximum allocations allowed
backupsintegerYesMaximum backups allowed

Allocation Object

FieldTypeRequiredDescription
defaultintegerYesPrimary allocation ID
additionalarrayNoAdditional allocation IDs

Example Request

curl -X POST "https://your-panel.com/api/application/servers" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"name": "My New Server",
"user": 1,
"egg": 5,
"docker_image": "quay.io/pterodactyl/core:java",
"startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"environment": {
"MINECRAFT_VERSION": "latest",
"SERVER_JARFILE": "server.jar"
},
"limits": {
"memory": 1024,
"swap": 0,
"disk": 2048,
"io": 500,
"cpu": 100,
"oom_disabled": false
},
"feature_limits": {
"databases": 2,
"allocations": 1,
"backups": 5
},
"allocation": {
"default": 1
}
}'

Example Response

{
"object": "server",
"attributes": {
"id": 2,
"external_id": null,
"uuid": "bf3b26c0-9d2e-4d8f-8c8a-1234567890ab",
"identifier": "bf3b26c0",
"name": "My New Server",
"description": "",
"status": null,
"suspended": false,
"limits": {
"memory": 2048,
"swap": 0,
"disk": 4096,
"io": 500,
"cpu": 200,
"threads": null,
"oom_disabled": false
},
"feature_limits": {
"databases": 5,
"allocations": 2,
"backups": 10
},
"user": 1,
"node": 1,
"allocation": 1,
"nest": 1,
"egg": 5,
"container": {
"startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"image": "quay.io/pterodactyl/core:java",
"installed": true,
"environment": {
"MINECRAFT_VERSION": "1.19.4",
"SERVER_JARFILE": "server.jar",
"STARTUP": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"P_SERVER_LOCATION": "global",
"P_SERVER_UUID": "bf3b26c0-9d2e-4d8f-8c8a-1234567890ab",
"P_SERVER_ALLOCATION_LIMIT": "2"
}
},
"created_at": "2024-01-20T14:30:45+00:00",
"updated_at": "2024-01-20T15:15:30+00:00"
}
}

Update Server Details

Update server configuration, limits, and settings.

PATCH /api/application/servers/{server}/details

Path Parameters

ParameterTypeDescription
serverintegerServer ID

Request Body

FieldTypeRequiredDescription
namestringNoServer name
userintegerNoOwner user ID
external_idstringNoExternal ID
descriptionstringNoServer description

Example Request

curl -X PATCH "https://your-panel.com/api/application/servers/2/details" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Server Name",
"description": "This is an updated description"
}'

Update Server Build Configuration

Update server resource limits and feature limits.

PATCH /api/application/servers/{server}/build

Request Body

FieldTypeRequiredDescription
allocationintegerYesPrimary allocation ID
memoryintegerYesMemory limit in MB
swapintegerYesSwap limit in MB
diskintegerYesDisk space limit in MB
iointegerYesBlock IO weight (10-1000)
cpuintegerYesCPU limit percentage
threadsstringNoCPU thread pinning
feature_limitsobjectYesFeature limits object
add_allocationsarrayNoAdditional allocation IDs to add
remove_allocationsarrayNoAllocation IDs to remove
oom_disabledbooleanNoDisable OOM killer

Example Request

curl -X PATCH "https://your-panel.com/api/application/servers/2/build" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"allocation": 1,
"memory": 2048,
"swap": 0,
"disk": 4096,
"io": 500,
"cpu": 200,
"feature_limits": {
"databases": 5,
"allocations": 2,
"backups": 10
}
}'

Example Response

{
"object": "server",
"attributes": {
"id": 2,
"external_id": null,
"uuid": "bf3b26c0-9d2e-4d8f-8c8a-1234567890ab",
"identifier": "bf3b26c0",
"name": "Updated Server Name",
"description": "This is an updated description",
"status": null,
"suspended": false,
"limits": {
"memory": 2048,
"swap": 0,
"disk": 4096,
"io": 500,
"cpu": 200,
"threads": null,
"oom_disabled": false
},
"feature_limits": {
"databases": 5,
"allocations": 2,
"backups": 10
},
"user": 1,
"node": 1,
"allocation": 1,
"nest": 1,
"egg": 5,
"created_at": "2024-01-20T14:30:45+00:00",
"updated_at": "2024-01-20T15:15:30+00:00"
}
}

Update Server Startup

Update server startup command and environment variables.

PATCH /api/application/servers/{server}/startup

Request Body

FieldTypeRequiredDescription
startupstringYesServer startup command
environmentobjectYesEnvironment variables
eggintegerYesEgg ID
imagestringNoDocker image override
skip_scriptsbooleanNoSkip install scripts

Example Request

curl -X PATCH "https://your-panel.com/api/application/servers/2/startup" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"environment": {
"MINECRAFT_VERSION": "1.19.4",
"SERVER_JARFILE": "server.jar",
"BUILD_TYPE": "recommended"
},
"egg": 5,
"image": "quay.io/pterodactyl/core:java",
"skip_scripts": false
}'

Example Response

{
"object": "server",
"attributes": {
"id": 2,
"external_id": null,
"uuid": "bf3b26c0-9d2e-4d8f-8c8a-1234567890ab",
"identifier": "bf3b26c0",
"name": "Updated Server Name",
"description": "This is an updated description",
"status": null,
"suspended": false,
"limits": {
"memory": 2048,
"swap": 0,
"disk": 4096,
"io": 500,
"cpu": 200,
"threads": null,
"oom_disabled": false
},
"feature_limits": {
"databases": 5,
"allocations": 2,
"backups": 10
},
"user": 1,
"node": 1,
"allocation": 1,
"nest": 1,
"egg": 5,
"container": {
"startup_command": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"image": "quay.io/pterodactyl/core:java",
"installed": true,
"environment": {
"MINECRAFT_VERSION": "1.19.4",
"SERVER_JARFILE": "server.jar",
"BUILD_TYPE": "recommended",
"STARTUP": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"P_SERVER_LOCATION": "global",
"P_SERVER_UUID": "bf3b26c0-9d2e-4d8f-8c8a-1234567890ab",
"P_SERVER_ALLOCATION_LIMIT": "2"
}
},
"created_at": "2024-01-20T14:30:45+00:00",
"updated_at": "2024-01-20T15:30:15+00:00"
}
}

Suspend Server

Suspend a server to prevent it from starting.

POST /api/application/servers/{server}/suspend

Example Request

curl -X POST "https://your-panel.com/api/application/servers/2/suspend" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Response

Returns HTTP 204 No Content on successful suspension.

Unsuspend Server

Remove suspension from a server to allow it to start.

POST /api/application/servers/{server}/unsuspend

Example Request

curl -X POST "https://your-panel.com/api/application/servers/2/unsuspend" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Response

Returns HTTP 204 No Content on successful unsuspension.

Reinstall Server

Reinstall a server from its egg configuration.

POST /api/application/servers/{server}/reinstall

Example Request

curl -X POST "https://your-panel.com/api/application/servers/2/reinstall" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Response

Returns HTTP 204 No Content on successful reinstall trigger.

Delete Server

Delete a server from the panel. This action is irreversible.

DELETE /api/application/servers/{server}

Query Parameters

ParameterTypeDescription
forcebooleanForce deletion even if server is running

Example Request

curl -X DELETE "https://your-panel.com/api/application/servers/2?force=true" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Response

Returns HTTP 204 No Content on successful deletion.

Error Responses

Common Error Codes

Status CodeDescription
400Bad Request - Invalid input data
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Server does not exist
422Validation Error - Invalid field values
429Too Many Requests - Rate limit exceeded

Example Error Response

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The name field is required.",
"source": {
"field": "name"
}
}
]
}

Best Practices

Security Considerations

  1. API Key Protection: Store API keys securely and never expose them in client-side code
  2. HTTPS Only: Always use HTTPS for API requests
  3. Resource Limits: Set appropriate resource limits to prevent abuse
  4. Input Validation: Validate all input data before sending API requests
  5. Force Deletion: Use force deletion carefully as it can cause data loss

Performance Tips

  1. Pagination: Use pagination for large server lists
  2. Filtering: Apply filters to reduce response size
  3. Selective Includes: Only include necessary relationships
  4. Caching: Implement caching strategies for server data
  5. Bulk Operations: Consider bulk operations for multiple servers

Integration Examples

// Server management service example
class ServerService {
constructor(apiKey, baseUrl) {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
this.headers = {
'Authorization': `Bearer ${apiKey}`,
'Accept': 'Application/vnd.pterodactyl.v1+json',
'Content-Type': 'application/json'
};
}

async getAllServers(options = {}) {
const params = new URLSearchParams(options);
const response = await fetch(`${this.baseUrl}/api/application/servers?${params}`, {
headers: this.headers
});
return response.json();
}

async createServer(serverData) {
const response = await fetch(`${this.baseUrl}/api/application/servers`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify(serverData)
});
return response.json();
}

async updateServerDetails(serverId, updateData) {
const response = await fetch(`${this.baseUrl}/api/application/servers/${serverId}/details`, {
method: 'PATCH',
headers: this.headers,
body: JSON.stringify(updateData)
});
return response.json();
}

async suspendServer(serverId) {
const response = await fetch(`${this.baseUrl}/api/application/servers/${serverId}/suspend`, {
method: 'POST',
headers: this.headers
});
return response.status === 204;
}

async deleteServer(serverId, force = false) {
const url = `${this.baseUrl}/api/application/servers/${serverId}${force ? '?force=true' : ''}`;
const response = await fetch(url, {
method: 'DELETE',
headers: this.headers
});
return response.status === 204;
}
}

Rate Limiting

The Application API implements rate limiting to prevent abuse:

  • Default Limit: 240 requests per minute per API key
  • Burst Limit: Up to 10 requests per second
  • Headers: Response includes rate limit headers
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 235
X-RateLimit-Reset: 1642686400

Server Database Management

Manage server databases through the Application API for administrative control.

List Server Databases

Retrieve all databases assigned to a specific server.

GET /api/application/servers/{server}/databases

Example Request

curl "https://your-panel.com/api/application/servers/2/databases" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Example Response

{
"object": "list",
"data": [
{
"object": "server_database",
"attributes": {
"id": 3,
"server": 2,
"host": 1,
"database": "s2_gamedata",
"username": "u2_dbuser",
"remote": "%",
"max_connections": 50,
"created_at": "2023-10-20T10:30:00+00:00",
"updated_at": "2023-10-20T10:30:00+00:00",
"relationships": {
"host": {
"object": "database_host",
"attributes": {
"id": 1,
"name": "MySQL Server 1",
"host": "mysql.example.com",
"port": 3306,
"username": "pterodactyl",
"max_databases": 100,
"created_at": "2023-10-15T09:00:00+00:00",
"updated_at": "2023-10-15T09:00:00+00:00"
}
}
}
}
}
]
}

Get Database Details

Retrieve detailed information about a specific server database.

GET /api/application/servers/{server}/databases/{database}

Example Request

curl "https://your-panel.com/api/application/servers/2/databases/3" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Create Server Database

Create a new database for a server.

POST /api/application/servers/{server}/databases

Request Body

FieldTypeRequiredDescription
databasestringYesDatabase name (without prefix)
remotestringYesRemote connection string (% for all)
hostintegerYesDatabase host ID

Example Request

curl -X POST "https://your-panel.com/api/application/servers/2/databases" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"database": "gamedata",
"remote": "%",
"host": 1
}'

Update Database

Update database configuration including remote connection settings.

PATCH /api/application/servers/{server}/databases/{database}

Request Body

FieldTypeRequiredDescription
remotestringNoRemote connection string

Example Request

curl -X PATCH "https://your-panel.com/api/application/servers/2/databases/3" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"remote": "192.168.1.%"
}'

Reset Database Password

Generate a new password for the database user.

POST /api/application/servers/{server}/databases/{database}/reset-password

Example Request

curl -X POST "https://your-panel.com/api/application/servers/2/databases/3/reset-password" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Example Response

{
"object": "server_database",
"attributes": {
"id": 3,
"server": 2,
"host": 1,
"database": "s2_gamedata",
"username": "u2_dbuser",
"remote": "%",
"max_connections": 50,
"password": "new_generated_password_here",
"created_at": "2023-10-20T10:30:00+00:00",
"updated_at": "2023-10-20T16:45:00+00:00"
}
}
Password Security

The new password is only returned in this response. Store it securely as it cannot be retrieved again through the API.

Delete Database

Permanently delete a server database and all its data.

DELETE /api/application/servers/{server}/databases/{database}

Example Request

curl -X DELETE "https://your-panel.com/api/application/servers/2/databases/3" \
-H "Authorization: Bearer ptla_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json"

Success Response (204)

Returns empty response body with status code 204.

Warning

Database deletion is permanent and irreversible. All data will be lost.


Source Code References

Controllers and Routes

Method: ServerController@index (List Servers)
Route: GET /api/application/servers
Source: ServerController.php

Method: ServerController@view (Get Server)
Route: GET /api/application/servers/{server}
Source: ServerController.php

Method: ServerController@store (Create Server)
Route: POST /api/application/servers
Source: ServerController.php

Method: ServerDetailsController@details (Update Details)
Route: PATCH /api/application/servers/{server}/details
Source: Servers Controllers

Method: ServerBuildController@build (Update Build)
Route: PATCH /api/application/servers/{server}/build
Source: Servers Controllers

Method: StartupController@startup (Update Startup)
Route: PATCH /api/application/servers/{server}/startup
Source: StartupController.php

Method: ServerManagementController@suspend (Suspend Server)
Route: POST /api/application/servers/{server}/suspend
Source: ServerManagementController.php

Method: ServerManagementController@unsuspend (Unsuspend Server)
Route: POST /api/application/servers/{server}/unsuspend
Source: ServerManagementController.php

Method: ServerController@delete (Delete Server)
Route: DELETE /api/application/servers/{server}
Source: ServerController.php

Services

Server Creation Service: ServerCreationService.php
Server Build Modification Service: BuildModificationService.php
Server Deletion Service: ServerDeletionService.php
Startup Modification Service: StartupModificationService.php

Models and Validation

Server Model: Server.php
Server Store Request: StoreServerRequest.php
Server Update Requests: Server Request Classes

Route Definitions

Application Routes: api-application.php - Lines 55-75

For detailed implementation and the latest updates, refer to the Pterodactyl Panel repository.