Servers - Pterodactyl Panel

The Servers API allows you to create, configure, and manage game servers on the Panel. This includes managing server resources, startup parameters, and server state.

List Servers

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

Retrieves a paginated list of all servers on the Panel.

Query Parameters

integer

default:"50"

Number of results per page

string

Filter servers by UUID

string

Filter servers by short UUID

string

Filter servers by name

string

Filter servers by description

string

Filter servers by Docker image

string

Filter servers by external identifier

string

Sort by field. Available: id, uuid. Prefix with - for descending

string

Include related resources. Available: allocations, user, subusers, nest, egg, variables, location, node, databases

Response

string

Always list

array

Array of server objects (see Get Server Details for structure)

Get Server Details

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

Retrieves details for a specific server.

Path Parameters

integer

required

The internal ID of the server

Response

{
  "object": "server",
  "attributes": {
    "id": 1,
    "external_id": null,
    "uuid": "8d4f8c5e-2b7a-4c9d-8e1f-9a3b4c5d6e7f",
    "identifier": "8d4f8c5e",
    "name": "My Minecraft Server",
    "description": "A vanilla Minecraft server",
    "status": "running",
    "suspended": false,
    "limits": {
      "memory": 2048,
      "swap": 0,
      "disk": 10240,
      "io": 500,
      "cpu": 100,
      "threads": null,
      "oom_disabled": true
    },
    "feature_limits": {
      "databases": 1,
      "allocations": 1,
      "backups": 3
    },
    "user": 1,
    "node": 1,
    "allocation": 1,
    "nest": 1,
    "egg": 1,
    "container": {
      "startup_command": "java -Xms128M -Xmx2048M -jar server.jar",
      "image": "ghcr.io/pterodactyl/yolks:java_17",
      "installed": 1,
      "environment": {
        "SERVER_JARFILE": "server.jar",
        "VANILLA_VERSION": "latest"
      }
    },
    "updated_at": "2024-03-04T00:00:00+00:00",
    "created_at": "2024-01-01T00:00:00+00:00"
  }
}

Get Server by External ID

curl "https://panel.example.com/api/application/servers/external/{external_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Retrieves a server by its external identifier.

Path Parameters

string

required

The external identifier of the server

Create Server

curl -X POST "https://panel.example.com/api/application/servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Server",
    "user": 1,
    "egg": 1,
    "docker_image": "ghcr.io/pterodactyl/yolks:java_17",
    "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
    "environment": {
      "SERVER_JARFILE": "server.jar",
      "VANILLA_VERSION": "latest"
    },
    "limits": {
      "memory": 2048,
      "swap": 0,
      "disk": 10240,
      "io": 500,
      "cpu": 100
    },
    "feature_limits": {
      "databases": 1,
      "allocations": 1,
      "backups": 3
    },
    "allocation": {
      "default": 1
    }
  }'

Creates a new server on the Panel.

Request Body

string

required

Server display name

integer

required

ID of the user who will own the server

integer

required

ID of the egg to use for this server

string

required

Docker image to use for the server

string

required

Server startup command

object

required

Environment variables for the server (egg-specific)

object

required

Resource limits for the server

Show Limits Object

integer

required

Memory limit in MB

integer

required

Swap space in MB (0 to disable, -1 for unlimited)

integer

required

Disk space in MB

integer

required

IO weight (10-1000)

integer

required

CPU limit as percentage (0 for unlimited)

string

Specific CPU threads to use (e.g., “0-3” or “0,2,4”)

object

required

Feature limits for the server

Show Feature Limits Object

integer

required

Maximum number of databases (0 for none, null for unlimited)

integer

required

Maximum number of allocations (0 for none, null for unlimited)

integer

required

Maximum number of backups (0 for none)

object

Allocation settings (required if not using deployment)

Show Allocation Object

integer

required

Primary allocation ID

array

Array of additional allocation IDs

object

Automatic deployment settings (alternative to manual allocation)

Show Deploy Object

array

required

Array of location IDs to deploy to

boolean

required

Whether to require a dedicated IP

array

required

Array of port ranges (e.g., [“25565-25570”])

string

Server description

string

External identifier for third-party integrations

boolean

default:false

Whether to skip the egg installation script

boolean

Whether to disable the OOM killer

boolean

default:false

Whether to start the server after installation completes

Response

Returns the created server object with HTTP status 201 Created.

Update Server Details

curl -X PATCH "https://panel.example.com/api/application/servers/{server_id}/details" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Server Name",
    "description": "Updated description"
  }'

Updates basic server details like name, description, and owner.

Path Parameters

integer

required

The internal ID of the server

Request Body

string

New server name

string

New server description

integer

New owner user ID

string

New external identifier

Update Server Build

curl -X PATCH "https://panel.example.com/api/application/servers/{server_id}/build" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "limits": {
      "memory": 4096,
      "swap": 0,
      "disk": 20480,
      "io": 500,
      "cpu": 200
    },
    "feature_limits": {
      "databases": 2,
      "allocations": 2,
      "backups": 5
    }
  }'

Updates server resource limits and allocations.

Path Parameters

integer

required

The internal ID of the server

Request Body

integer

Primary allocation ID

object

Resource limits (same structure as Create Server)

object

Feature limits (same structure as Create Server)

array

Array of allocation IDs to add

array

Array of allocation IDs to remove

Update Server Startup

curl -X PATCH "https://panel.example.com/api/application/servers/{server_id}/startup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
    "environment": {
      "SERVER_JARFILE": "server.jar",
      "VANILLA_VERSION": "1.20.4"
    },
    "egg": 1,
    "image": "ghcr.io/pterodactyl/yolks:java_17"
  }'

Updates server startup configuration including the egg, Docker image, and environment variables.

Path Parameters

integer

required

The internal ID of the server

Request Body

string

Server startup command

object

Environment variables

integer

Egg ID

string

Docker image

boolean

Whether to skip scripts on reinstall

Suspend Server

curl -X POST "https://panel.example.com/api/application/servers/{server_id}/suspend" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Suspends a server, preventing it from being started.

Path Parameters

integer

required

The internal ID of the server

Unsuspend Server

curl -X POST "https://panel.example.com/api/application/servers/{server_id}/unsuspend" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Unsuspends a server, allowing it to be started.

Path Parameters

integer

required

The internal ID of the server

Reinstall Server

curl -X POST "https://panel.example.com/api/application/servers/{server_id}/reinstall" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Triggers a reinstall of the server, running the egg installation script.

Path Parameters

integer

required

The internal ID of the server

Reinstalling a server will stop it and may result in data loss. Ensure backups are created first.

Delete Server

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

Deletes a server from the Panel.

Path Parameters

integer

required

The internal ID of the server to delete

Force Delete

curl -X DELETE "https://panel.example.com/api/application/servers/{server_id}/force" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Force deletes a server, bypassing daemon checks.

Response

Returns HTTP status 204 No Content on successful deletion.

Server Databases

For managing server databases via the Application API, see the dedicated Server Databases endpoint documentation. This includes:

Listing all databases for a server
Creating new databases
Resetting database passwords
Deleting databases

Server owners can also manage databases via the Client API Databases endpoints.

​List Servers

​Query Parameters

​Response

​Get Server Details

​Path Parameters

​Response

​Get Server by External ID

​Path Parameters

​Create Server

​Request Body

​Response

​Update Server Details

​Path Parameters

​Request Body

​Update Server Build

​Path Parameters

​Request Body

​Update Server Startup

​Path Parameters

​Request Body

​Suspend Server

​Path Parameters

​Unsuspend Server

​Path Parameters

​Reinstall Server

​Path Parameters

​Delete Server

​Path Parameters

​Force Delete

​Response

​Server Databases

List Servers

Query Parameters

Response

Get Server Details

Path Parameters

Response

Get Server by External ID

Path Parameters

Create Server

Request Body

Response

Update Server Details

Path Parameters

Request Body

Update Server Build

Path Parameters

Request Body

Update Server Startup

Path Parameters

Request Body

Suspend Server

Path Parameters

Unsuspend Server

Path Parameters

Reinstall Server

Path Parameters

Delete Server

Path Parameters

Force Delete

Response

Server Databases