Server Management
- List Servers
- Create Server
- List Specific Server
- Update Server Config
- Update Server Build
- Suspend Server
- Unsuspend Server
- Delete Server
GET /servers[?page=]
This route returns all servers currently existing on the system as a paginated result.
URL Parameters
?page=<id> (optional) — URL querystring indicating which page of pagination to show. e.g. /servers?page=5
Responses
HTTP/200 — Returns paginated result.
{
"data": [
{
"id": 2,
"uuid": "94545fd1-ae41-43c5-8842-3f5e30465691",
"uuidShort": "94545fd1",
"node": 1,
"name": "Test Server",
"suspended": 0,
"owner": 1,
"memory": 512,
"swap": 0,
"disk": 1024,
"io": 500,
"cpu": 0,
"oom_disabled": 0,
"allocation": 1,
"service": 1,
"option": 1,
"startup": "-Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"username": "ptdl-testse_z0ute",
"installed": 1,
"created_at": "2016-01-12 03:53:22",
"updated_at": "2016-01-12 03:53:32"
}
],
"meta": {
"pagination": {
"total": 1,
"count": 1,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": []
}
}
}
POST /servers
Creates a new server on the system as well as the associated remote node.
Request Body
{
"name": "Test Server",
"owner": "woo@wuzzlewoo.com",
"location": 1,
"node": 1,
"ip": "172.28.128.2",
"port": 25566,
"memory": 1024,
"swap": 100,
"disk": 10240,
"cpu": 100,
"io": 500,
"service": 1,
"option": 1,
"startup": "-Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"env_SERVER_JARFILE": "server.jar",
"env_VANILLA_VERSION": "latest"
}
You can also remove the ip and port fields and replace them with allocation which should point to the ID of an allocation to assign to the server.
Responses
Pterodactyl Panel is configured to attempt to connect for up to 5 seconds, and await a timeout for up to 10 seconds. If the daemon is not running, or is running slowly, this query could take up to 10 or more seconds to complete. You should not assume a timeout if it does not finish immediately.
HTTP/201 — returned when the server is created. Returns a Location header with a link to the new resource.
HTTP/422 — returned when there is an error with validating the data or there was an error communicating with the daemon to add the server. Look into the specific error for details on what occurred.
HTTP/503 — returned where there is an error that occurs while attempting to add the server that is unrelated to input data.
GET /servers/:id[?fields=]
Returns information about a given server.
URL Parameters
:id — The ID of the server to return information on.
?fields=<list> (optional) — A comma delimited list of database fields to return. e.g. ?fields=id,name
Responses
HTTP 200
{
"server": {
"id": 2,
"uuid": "94545fd1-ae41-43c5-8842-3f5e30465691",
"uuidShort": "94545fd1",
"node": 1,
"name": "Test Server",
"active": 1,
"owner": 1,
"memory": 512,
"swap": 0,
"disk": 1024,
"io": 500,
"cpu": 0,
"oom_disabled": 0,
"ip": "172.28.128.3",
"port": 25565,
"service": 1,
"option": 1,
"startup": "-Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}",
"username": "ptdl-testse_z0ute",
"installed": 1,
"created_at": "2016-01-12 03:53:22",
"updated_at": "2016-01-12 03:53:32"
}
}
HTTP/400 — returned when the comma delimitated list of fields contains a field (or more) that do not exist.
{
"message": "There was an issue with the fields passed in the request.",
"status_code": 400
}
HTTP/404 — returned when no server by the requested ID exists on the system.
{
"message": "No server by that ID was found.",
"status_code": 404
}
PATCH /servers/:id/config
Updates basic configuration information about the server and can reset the master token. Not all fields are required to be sent.
Request Body
{
"owner": "new_owner@email.net",
"name": "Updated Server Name",
"reset_token": true
}
Note: changing the server owner automatically regenerates the core token for the server, even if reset_token isn't passed or is set to false.
Responses
HTTP 200 — successful update, returns a JSON block of the server info with updated fields.
HTTP/400 — returned when there is a field validation error or a daemon connection issue.
HTTP/404 — returned when no server by the requested ID exists on the system.
PATCH /servers/:id/build
Updates build configuration for server. Not all fields are required.
Request Parameters
default — the default connection to use for the server in ip:port form. This must be an IP and port that is allocated to the server already.
add_additional — an array of additional unassigned allocations to assign to the server in ip:port format.
remove_additional — an array of assigned allocations to remove from the server in ip:port format.
Request Body
{
"default": "192.168.0.1:25565",
"add_additional": [
"192.168.0.1:25566",
"192.168.0.1:25567",
"192.168.0.1:25568"
],
"remove_additional": [],
"memory": 1024,
"swap": 0,
"io": 500,
"cpu": 0,
"disk": 1024
}
Responses
HTTP 200 — successful update, returns a JSON block of the server info with updated fields.
HTTP/400 — returned when there is a field validation error or a daemon connection issue.
HTTP/404 — returned when no server by the requested ID exists on the system.
POST /servers/:id/suspend
Suspends a server instance.
Responses
HTTP 204 — returned on successful suspension.
HTTP/422 — returned when there is a validation error or panel cannot connect to the daemon.
HTTP/503 — returned when there is some other service error.
POST /servers/:id/unsuspend
Unsuspends a server instance.
Responses
HTTP 204 — returned on successful suspension.
HTTP/422 — returned when there is a validation error or panel cannot connect to the daemon.
HTTP/503 — returned when there is some other service error.
DELETE /servers/:id/[:force]
Deletes a server from the system. This will attempt to nicely delete the server from the panel and daemon. If it fails you can pass [:force] to the URL to attempt to forcibly remove the server from the panel, regardless of if the daemon is working.