Client API: Container Apps: Servers
The 12 Client API operations for servers.
Part of Container Apps.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/client/servers |
List servers owned by or accessible to current user |
| GET | /api/v1/client/servers/live |
State and usage for the servers on the list, one request instead of one per server |
| GET | /api/v1/client/servers/{uuid} |
Get server details |
| POST | /api/v1/client/servers/{uuid}/command |
Execute a command on the server |
| POST | /api/v1/client/servers/{uuid}/power |
Execute power action (start, stop, restart, kill) |
| GET | /api/v1/client/servers/{uuid}/resources |
Get server resource usage and limits |
| GET | /api/v1/client/servers/{uuid}/sftp |
Connection details for this server's SFTP login |
| GET | /api/v1/client/servers/{uuid}/sleep |
Sleep and start-queue state for a free server |
| GET | /api/v1/client/servers/{uuid}/status-ping |
Ask the game itself who is online |
| GET | /api/v1/client/servers/{uuid}/updates |
Get available updates for server software |
| POST | /api/v1/client/servers/{uuid}/wake |
Ask for a sleeping free server to be started |
| GET | /api/v1/client/servers/{uuid}/websocket |
Get WebSocket token and endpoint for console access |
List servers owned by or accessible to current user
Section titled List servers owned by or accessible to current userGET /api/v1/client/servers
List servers owned by or accessible to current user.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
tag |
query | string or null | no | Filter by resource tag |
Responses
Section titled Responses| 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 |
[].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
Section titled State and usage for the servers on the list, one request instead of one per serverGET /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
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
uuids |
query | string or null | no | Comma-separated server UUIDs; default is the newest |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Get server details
Section titled Get server detailsGET /api/v1/client/servers/{uuid}
Get server details.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| 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 |
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 |
Execute a command on the server
Section titled Execute a command on the serverPOST /api/v1/client/servers/{uuid}/command
Execute a command on the server.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
command |
query | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Execute power action (start, stop, restart, kill)
Section titled 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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
signal |
string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Get server resource usage and limits
Section titled Get server resource usage and limitsGET /api/v1/client/servers/{uuid}/resources
Get server resource usage and limits.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Connection details for this server's SFTP login
Section titled Connection details for this server's SFTP loginGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| 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
Section titled Sleep and start-queue state for a free serverGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| 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 |
Ask the game itself who is online
Section titled Ask the game itself who is onlineGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| 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 |
Get available updates for server software
Section titled Get available updates for server softwareGET /api/v1/client/servers/{uuid}/updates
Get available updates for server software.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Ask for a sleeping free server to be started
Section titled Ask for a sleeping free server to be startedPOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Request body
Section titled Request bodyapplication/json
| Field | Type | Required |
|---|---|---|
turnstile_token |
string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Get WebSocket token and endpoint for console access
Section titled Get WebSocket token and endpoint for console accessGET /api/v1/client/servers/{uuid}/websocket
Get WebSocket token and endpoint for console access.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Fields of a 200 response:
| Field | Type |
|---|---|
token |
string |
socket |
string |