Create a server
Create a server for a customer and deploy it to a node.
POST/api/application/servers
Creates the server, places it on the least-loaded node that fits, and starts the install. If the customer's email isn't registered yet, an account is created for them.
curl -X POST https://panel.example.com/api/application/servers \
-H "Authorization: Bearer bpnl_..." \
-H "Content-Type: application/json" \
-d '{
"externalId": "whmcs-1042",
"planId": "01JBX2Q7Z9H6R1V8K3M5N4P2T0",
"eggId": "clx9k2m4p0001",
"environment": { "MAX_PLAYERS": "20" },
"user": { "email": "[email protected]", "name": "Sam Player" }
}'Body
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Your ID for this server, up to 191 characters. |
planId | string | Yes | From the catalog. Sets the server's resources. |
eggId | string | Yes | The game to install. |
user.email | string | Yes | The owner's email. |
user.name | string | Yes | The owner's name, up to 100 characters. |
user.password | string | No | 8 to 128 characters. Only used when a new account is created. |
locationId | string or null | No | Where to deploy. Defaults to the plan's location, or any location. |
environment | object | No | Game settings by variable name, as strings. Unset variables use their defaults. |
name | string | No | 3 to 40 characters. Defaults to the plan name. |
startOnCompletion | boolean | No | Start the server once it's installed. Defaults to true. |
Response
Returns 201 Created with the server object:
{
"server": {
"id": "01JBX3A8C2D4E6F8G0H2J4K6M8",
"externalId": "whmcs-1042",
"name": "Starter",
"planId": "01JBX2Q7Z9H6R1V8K3M5N4P2T0",
"status": "installing",
"suspended": false,
"deployed": true,
"url": "https://panel.example.com/dashboard/01JBX3A8C2D4E6F8G0H2J4K6M8",
"userId": "u_8f3k2m",
"uuid": "5f0c2a1e-7b4d-4c8e-9a3f-1d2e3f4a5b6c"
}
}Retries
If a server with the same externalId already exists, it's returned instead of creating a second one. If an earlier request created the server but couldn't place it on a node, the retry tries to deploy it again.
Errors
| Status | When |
|---|---|
422 | Unknown plan or game, the plan isn't sold in locationId, the game needs more ports than the plan has, a game setting fails its rules, or no node has room. |
502 | The chosen node rejected the server. Retry later, or check the node in Admin → Nodes. |