Client API: Deployment servers: Servers

Name	In	Type	Required	Description
`tag`	query	string or null	no	Filter by resource tag

Responses

Section titled State and usage for the servers on the list, one request instead of one per server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].uuid`	string
`[].uuidShort`	string or null
`[].name`	string
`[].owner_id`	integer
`[].service_id`	integer or null
`[].template_uuid`	string or null
`[].template_name`	string or null
`[].template_slug`	string or null
`[].docker_image`	string or null
`[].startup_command`	string or null
`[].memory_mb`	integer
`[].boost_memory_mb`	integer or null
`[].disk_mb`	integer
`[].cpu_percent`	integer
`[].io_weight`	integer or null
`[].swap_mb`	integer or null
`[].allocation_limit`	integer or null
`[].database_limit`	integer or null
`[].backup_limit`	integer or null
`[].node_id`	integer or null
`[].node_name`	string or null
`[].node_fqdn`	string or null
`[].owner_email`	string or null
`[].location`	string or null
`[].location_id`	integer or null
`[].location_name`	string or null
`[].location_country_code`	string or null
`[].cpu_model`	string or null
`[].storage_type`	string or null
`[].network_speed`	string or null
`[].installed_os`	string or null
`[].allocation_id`	integer or null
`[].ip_address`	string or null
`[].port`	integer or null
`[].join_address`	string or null
`[].players_online`	integer or null
`[].usage`	object or null
`[].uptime_seconds`	integer or null
`[].variables`	object or null
`[].recipe_uuid`	string or null
`[].specialization_slug`	string or null
`[].specialization_name`	string or null
`[].status`	string
`[].last_error`	string or null
`[].last_error_at`	string (date-time) or null
`[].created_at`	string (date-time)
`[].updated_at`	string (date-time)
`[].tags`	array of string
`[].sleep_policy`	string or null
`[].sleep`	object or null
`[].entitlements`	array of object or null
`[].install`	object or null
`[].power`	object or null
`[].lock`	object or null
`[].base_memory_mb`	integer or null
`[].memory_boost`	object or null

State and usage for the servers on the list, one request instead of one per server

GET /api/v1/client/servers/live

State and usage for the servers on the list, one request instead of one per server.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuids`	query	string or null	no	Comma-separated server UUIDs; default is the newest

Responses

Section titled Get server details

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get server details

GET /api/v1/client/servers/{uuid}

Get server details.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Auto backups status

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`uuid`	string
`uuidShort`	string or null
`name`	string
`owner_id`	integer
`service_id`	integer or null
`template_uuid`	string or null
`template_name`	string or null
`template_slug`	string or null
`docker_image`	string or null
`startup_command`	string or null
`memory_mb`	integer
`boost_memory_mb`	integer or null
`disk_mb`	integer
`cpu_percent`	integer
`io_weight`	integer or null
`swap_mb`	integer or null
`allocation_limit`	integer or null
`database_limit`	integer or null
`backup_limit`	integer or null
`node_id`	integer or null
`node_name`	string or null
`node_fqdn`	string or null
`owner_email`	string or null
`location`	string or null
`location_id`	integer or null
`location_name`	string or null
`location_country_code`	string or null
`cpu_model`	string or null
`storage_type`	string or null
`network_speed`	string or null
`installed_os`	string or null
`allocation_id`	integer or null
`ip_address`	string or null
`port`	integer or null
`join_address`	string or null
`players_online`	integer or null
`usage`	object or null
`uptime_seconds`	integer or null
`variables`	object or null
`recipe_uuid`	string or null
`specialization_slug`	string or null
`specialization_name`	string or null
`status`	string
`last_error`	string or null
`last_error_at`	string (date-time) or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`tags`	array of string
`sleep_policy`	string or null
`sleep`	object or null
`entitlements`	array of object or null
`install`	object or null
`power`	object or null
`lock`	object or null
`base_memory_mb`	integer or null
`memory_boost`	object or null

Auto backups status

GET /api/v1/client/servers/{uuid}/auto-backups

This server's automatic backups: whether it has them, whether they are on, and the last run.

available is true when the account's plan includes automatic backups (Pro and up) or the server has the automatic backups add-on; otherwise reason_unavailable says why, in words for the customer. We take one snapshot a day (every_hours) and keep the newest keep. They count against the account's snapshot storage. last_error is why the last run could not take one, such as full snapshot storage. Subusers need snapshot.read.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Switch this server's automatic backups on or off, and answer as GET does

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Switch this server's automatic backups on or off, and answer as GET does

PUT /api/v1/client/servers/{uuid}/auto-backups

Switch this server's automatic backups on or off, and answer as GET does.

Answers 409, naming why, when the server has no automatic backups to switch. Switching them off keeps the backups already taken. Subusers need snapshot.create.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`enabled`	boolean	yes

Responses

Section titled Execute a command on the server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Execute a command on the server

POST /api/v1/client/servers/{uuid}/command

Execute a command on the server.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`command`	query	string	yes

Responses

Section titled Execute power action (start, stop, restart, kill)

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Execute power action (start, stop, restart, kill)

POST /api/v1/client/servers/{uuid}/power

Execute power action (start, stop, restart, kill).

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`signal`	string	yes

Responses

Section titled Delete every file on the server and run its software's install again

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete every file on the server and run its software's install again

POST /api/v1/client/servers/{uuid}/reinstall

Delete every file on the server and run its software's install again.

confirm_server_name must name the server, in any case, the way every other wipe is confirmed; a server whose install never finished (installing or install_failed) has nothing to lose and is not asked. The name is checked before the rate limit, so a refused request does not spend the budget. Needs settings.reinstall.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json

Field	Type	Required
`confirm_server_name`	string or null	no

Responses

Section titled Get server resource usage and limits

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get server resource usage and limits

GET /api/v1/client/servers/{uuid}/resources

Get server resource usage and limits.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Rename the server, or switch the removal of unused world chunks

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Rename the server, or switch the removal of unused world chunks

PATCH /api/v1/client/servers/{uuid}/settings

Rename the server, or switch the removal of unused world chunks.

name follows the one rule every intake of a server name uses (2 to 48 characters; letters, numbers, spaces and - _ . ' ! & ( ) [ ] , : +) and needs settings.rename. world_optimization_enabled needs settings.reinstall; a free server may switch it on but not off. Answers the server as GET /{uuid} does.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`name`	string or null	no	2–48 characters once spaces are collapsed
`world_optimization_enabled`	boolean or null	no

Responses

Section titled Connection details for this server's SFTP login

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`uuid`	string
`uuidShort`	string or null
`name`	string
`owner_id`	integer
`service_id`	integer or null
`template_uuid`	string or null
`template_name`	string or null
`template_slug`	string or null
`docker_image`	string or null
`startup_command`	string or null
`memory_mb`	integer
`boost_memory_mb`	integer or null
`disk_mb`	integer
`cpu_percent`	integer
`io_weight`	integer or null
`swap_mb`	integer or null
`allocation_limit`	integer or null
`database_limit`	integer or null
`backup_limit`	integer or null
`node_id`	integer or null
`node_name`	string or null
`node_fqdn`	string or null
`owner_email`	string or null
`location`	string or null
`location_id`	integer or null
`location_name`	string or null
`location_country_code`	string or null
`cpu_model`	string or null
`storage_type`	string or null
`network_speed`	string or null
`installed_os`	string or null
`allocation_id`	integer or null
`ip_address`	string or null
`port`	integer or null
`join_address`	string or null
`players_online`	integer or null
`usage`	object or null
`uptime_seconds`	integer or null
`variables`	object or null
`recipe_uuid`	string or null
`specialization_slug`	string or null
`specialization_name`	string or null
`status`	string
`last_error`	string or null
`last_error_at`	string (date-time) or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`tags`	array of string
`sleep_policy`	string or null
`sleep`	object or null
`entitlements`	array of object or null
`install`	object or null
`power`	object or null
`lock`	object or null
`base_memory_mb`	integer or null
`memory_boost`	object or null

Connection details for this server's SFTP login

GET /api/v1/client/servers/{uuid}/sftp

Connection details for this server's SFTP login.

Built here rather than in the browser: Wings validates the username's shape before it calls the panel, so a client assembling its own can be rejected on the node with nothing to show for it.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Sleep and start-queue state for a free server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`host`	string
`port`	integer
`username`	string

Sleep and start-queue state for a free server

GET /api/v1/client/servers/{uuid}/sleep

Sleep and start-queue state for a free server.

sleeps_at is absolute so a client counts down locally rather than polling for a ticking number.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Every startup variable the server runs with, and which of them its owner may change

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`sleep`	Sleep
`entitlements`	array of object

Every startup variable the server runs with, and which of them its owner may change

GET /api/v1/client/servers/{uuid}/startup-variables

Every startup variable the server runs with, and which of them its owner may change.

variables lists each one with its value, secret (a password: show it masked), editable (PATCH .../startup-variables takes it), source (server for the server's own value, default for the template's) and rule (what a new password must be, for a declared password). game is the game whose settings are editable, or null. Needs startup.read.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Change the server's passwords or its game's allowlisted startup variables

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change the server's passwords or its game's allowlisted startup variables

PATCH /api/v1/client/servers/{uuid}/startup-variables

Change the server's passwords or its game's allowlisted startup variables.

It follows the org portal's rule. A password the server's template or recipe declares (a database's POSTGRES_PASSWORD, for one) takes 12 to 128 characters: letters, numbers and _ . @ % + = : , -, no spaces, starting with a letter or a number. Other keys must be on the game's allowlist; anything else answers 400. The value applies on the next restart. A database that reads its password only on first boot keeps the old one inside until its owner changes it there too.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`variables`	Variables	yes

Responses

Section titled Ask the game itself who is online

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`uuid`	string
`uuidShort`	string or null
`name`	string
`owner_id`	integer
`service_id`	integer or null
`template_uuid`	string or null
`template_name`	string or null
`template_slug`	string or null
`docker_image`	string or null
`startup_command`	string or null
`memory_mb`	integer
`boost_memory_mb`	integer or null
`disk_mb`	integer
`cpu_percent`	integer
`io_weight`	integer or null
`swap_mb`	integer or null
`allocation_limit`	integer or null
`database_limit`	integer or null
`backup_limit`	integer or null
`node_id`	integer or null
`node_name`	string or null
`node_fqdn`	string or null
`owner_email`	string or null
`location`	string or null
`location_id`	integer or null
`location_name`	string or null
`location_country_code`	string or null
`cpu_model`	string or null
`storage_type`	string or null
`network_speed`	string or null
`installed_os`	string or null
`allocation_id`	integer or null
`ip_address`	string or null
`port`	integer or null
`join_address`	string or null
`players_online`	integer or null
`usage`	object or null
`uptime_seconds`	integer or null
`variables`	object or null
`recipe_uuid`	string or null
`specialization_slug`	string or null
`specialization_name`	string or null
`status`	string
`last_error`	string or null
`last_error_at`	string (date-time) or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`tags`	array of string
`sleep_policy`	string or null
`sleep`	object or null
`entitlements`	array of object or null
`install`	object or null
`power`	object or null
`lock`	object or null
`base_memory_mb`	integer or null
`memory_boost`	object or null

Ask the game itself who is online

GET /api/v1/client/servers/{uuid}/status-ping

Ask the game itself who is online. Best-effort; never fails the request.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Patch subdomain

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`reachable`	boolean
`players_online`	integer or null
`players_max`	integer or null
`sample`	array of string
`version`	string or null
`protocol`	integer or null
`motd`	string or null
`favicon`	string or null
`latency_ms`	integer or null

Patch subdomain

PATCH /api/v1/client/servers/{uuid}/subdomain

Change the first part of the server's join address (survival in survival.example.gg), on the same domain.

Only a server with a join address has one to change; the others answer 400. The name must be free and allowed; the same name again changes nothing. Proxies stop answering the old name at once. Needs settings.rename.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`subdomain`	string	yes

Responses

Section titled Get available updates for server software

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`id`	integer
`uuid`	string
`uuidShort`	string or null
`name`	string
`owner_id`	integer
`service_id`	integer or null
`template_uuid`	string or null
`template_name`	string or null
`template_slug`	string or null
`docker_image`	string or null
`startup_command`	string or null
`memory_mb`	integer
`boost_memory_mb`	integer or null
`disk_mb`	integer
`cpu_percent`	integer
`io_weight`	integer or null
`swap_mb`	integer or null
`allocation_limit`	integer or null
`database_limit`	integer or null
`backup_limit`	integer or null
`node_id`	integer or null
`node_name`	string or null
`node_fqdn`	string or null
`owner_email`	string or null
`location`	string or null
`location_id`	integer or null
`location_name`	string or null
`location_country_code`	string or null
`cpu_model`	string or null
`storage_type`	string or null
`network_speed`	string or null
`installed_os`	string or null
`allocation_id`	integer or null
`ip_address`	string or null
`port`	integer or null
`join_address`	string or null
`players_online`	integer or null
`usage`	object or null
`uptime_seconds`	integer or null
`variables`	object or null
`recipe_uuid`	string or null
`specialization_slug`	string or null
`specialization_name`	string or null
`status`	string
`last_error`	string or null
`last_error_at`	string (date-time) or null
`created_at`	string (date-time)
`updated_at`	string (date-time)
`tags`	array of string
`sleep_policy`	string or null
`sleep`	object or null
`entitlements`	array of object or null
`install`	object or null
`power`	object or null
`lock`	object or null
`base_memory_mb`	integer or null
`memory_boost`	object or null

Get available updates for server software

GET /api/v1/client/servers/{uuid}/updates

Get available updates for server software.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Ask for a sleeping free server to be started

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Ask for a sleeping free server to be started

POST /api/v1/client/servers/{uuid}/wake

Ask for a sleeping free server to be started.

First in line with headroom starts in this request so the customer is not left waiting on a worker poll. Otherwise the row stays queued and a tick job releases it when the node has room.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json

Field	Type	Required
`turnstile_token`	string or null	no

Responses

Section titled Get WebSocket token and endpoint for console access

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get WebSocket token and endpoint for console access

GET /api/v1/client/servers/{uuid}/websocket

Warning

Deprecated. It still answers, but new code should not use it.

Get WebSocket token and endpoint for console access.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses