# Client API: Container Apps: Servers

> The 12 Client API operations for servers.

Source: https://docs.coritan.com/api/reference/client/container-apps/servers/

Part of [Container Apps](/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers`](#op-get-api-v1-client-servers) | List servers owned by or accessible to current user |
| GET | [`/api/v1/client/servers/live`](#op-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}`](#op-get-api-v1-client-servers-uuid) | Get server details |
| POST | [`/api/v1/client/servers/{uuid}/command`](#op-post-api-v1-client-servers-uuid-command) | Execute a command on the server |
| POST | [`/api/v1/client/servers/{uuid}/power`](#op-post-api-v1-client-servers-uuid-power) | Execute power action (start, stop, restart, kill) |
| GET | [`/api/v1/client/servers/{uuid}/resources`](#op-get-api-v1-client-servers-uuid-resources) | Get server resource usage and limits |
| GET | [`/api/v1/client/servers/{uuid}/sftp`](#op-get-api-v1-client-servers-uuid-sftp) | Connection details for this server's SFTP login |
| GET | [`/api/v1/client/servers/{uuid}/sleep`](#op-get-api-v1-client-servers-uuid-sleep) | Sleep and start-queue state for a free server |
| GET | [`/api/v1/client/servers/{uuid}/status-ping`](#op-get-api-v1-client-servers-uuid-status-ping) | Ask the game itself who is online |
| GET | [`/api/v1/client/servers/{uuid}/updates`](#op-get-api-v1-client-servers-uuid-updates) | Get available updates for server software |
| POST | [`/api/v1/client/servers/{uuid}/wake`](#op-post-api-v1-client-servers-uuid-wake) | Ask for a sleeping free server to be started |
| GET | [`/api/v1/client/servers/{uuid}/websocket`](#op-get-api-v1-client-servers-uuid-websocket) | Get WebSocket token and endpoint for console access |

### List servers owned by or accessible to current user {#op-get-api-v1-client-servers}

`GET /api/v1/client/servers`

List servers owned by or accessible to current user.

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

#### Parameters

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

#### 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 |
| `[].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 {#op-get-api-v1-client-servers-live}

`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

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

### Get server details {#op-get-api-v1-client-servers-uuid}

`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

| 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 |

### Execute a command on the server {#op-post-api-v1-client-servers-uuid-command}

`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

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

### Execute power action (start, stop, restart, kill) {#op-post-api-v1-client-servers-uuid-power}

`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

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

### Get server resource usage and limits {#op-get-api-v1-client-servers-uuid-resources}

`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

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

### Connection details for this server's SFTP login {#op-get-api-v1-client-servers-uuid-sftp}

`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

| 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 {#op-get-api-v1-client-servers-uuid-sleep}

`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

| 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 {#op-get-api-v1-client-servers-uuid-status-ping}

`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

| 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 {#op-get-api-v1-client-servers-uuid-updates}

`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

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

### Ask for a sleeping free server to be started {#op-post-api-v1-client-servers-uuid-wake}

`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

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

### Get WebSocket token and endpoint for console access {#op-get-api-v1-client-servers-uuid-websocket}

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

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

| 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 |