# Organization API: Customer Portal: Servers

> The 19 Organization API operations for servers.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid) | Get server |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/command`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-command) | Command |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/keep`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-keep) | Tell us this world is still wanted, and lift a hold if one is on |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-listing) | Public-list visibility and tags for the Server Settings tab |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-listing) | Toggle public-list visibility and replace the listing tags |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/permissions`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-permissions) | List grantable permissions |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/power`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-power) | Power |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/reinstall`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-reinstall) | Wipe server files and re-run the template install script + verify |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/resources`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-resources) | Get resources |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/settings`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-settings) | Patch settings |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/sftp`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sftp) | Connection details for this server's SFTP login |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/sleep`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sleep) | Sleep and start-queue state for a free server |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-startup-variables) | Update allowlisted startup env vars for the server's game |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/status-ping`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-status-ping) | Ask the game itself who is online |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/subdomain`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-subdomain) | Rename the gameproxy join-address subdomain for this server |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/wake`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-wake) | Ask for a sleeping free server to be started |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/websocket`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-websocket) | Return panel WS URL + the caller's bearer token for WS query auth |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization) | What unused-chunk cleanup has done to this world, and when |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization) | Queue an unused-chunk trim now, once per minintervalhours |

### Get server {#op-get-api-v1-orgs-org-slug-portal-servers-uuid}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Command {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-command}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/command`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `command` | query | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `command` | string | yes |

#### Responses

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

### Tell us this world is still wanted, and lift a hold if one is on {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-keep}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/keep`

Tell us this world is still wanted, and lift a hold if one is on.

One endpoint for both halves of the inactivity ladder: the nudge's "keep it"
link and the suspension's "reactivate". They differ only in whether the
server is currently suspended, and asking the customer to understand that
distinction would be asking them to understand our sweep.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Public-list visibility and tags for the Server Settings tab {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-listing}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`

Public-list visibility and tags for the Server Settings tab.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Toggle public-list visibility and replace the listing tags {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-listing}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`

Toggle public-list visibility and replace the listing tags.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hidden` | boolean or null | no |
| `tags` | array of string or null | no |

#### Responses

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

### List grantable permissions {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-permissions}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/permissions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Power {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-power}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/power`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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. |

### Wipe server files and re-run the template install script + verify {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-reinstall}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/reinstall`

Wipe server files and re-run the template install script + verify.

On a server that installed, this deletes every file, so it is confirmed
the way every other wipe is: ``confirm_server_name`` must name the server.
The storefront asks for it before the request; a request without it is
refused here so no client can wipe a server on a bare click.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `confirm_server_name` | string or null | no |

#### Responses

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

### Get resources {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-resources}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/resources`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Patch settings {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-settings}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/settings`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `world_optimization_enabled` | boolean or null | no |

#### 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-orgs-org-slug-portal-servers-uuid-sftp}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sftp`

Connection details for this server's SFTP login.

The portal login email is the SFTP identity, and it need not match any
platform user, so the storefront cannot derive this from ``auth/me``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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-orgs-org-slug-portal-servers-uuid-sleep}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sleep`

Sleep and start-queue state for a free server.

``sleeps_at`` is absolute so a client can run the countdown locally instead of
polling for a ticking number. Returns ``policy: none`` for a paid server, so a
frontend can render one component for both.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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 |

### Update allowlisted startup env vars for the server's game {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-startup-variables}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables`

Update allowlisted startup env vars for the server's game.

Values live in ``container_server_variables`` and apply on the next restart
after Wings sync. Arbitrary keys and startup_command are not accepted.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `variables` | Variables | yes |

#### Responses

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

### Ask the game itself who is online {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-status-ping}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/status-ping`

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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 |

### Rename the gameproxy join-address subdomain for this server {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-subdomain}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/subdomain`

Rename the gameproxy join-address subdomain for this server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subdomain` | 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-orgs-org-slug-portal-servers-uuid-wake}

`POST /api/v1/orgs/{org_slug}/portal/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. The response always carries the
queue block (including ``ahead: 0``) so a frontend can show the process.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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. |

### Return panel WS URL + the caller's bearer token for WS query auth {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-websocket}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/websocket`

Return panel WS URL + the caller's bearer token for WS query auth.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | 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 |

### What unused-chunk cleanup has done to this world, and when {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`

What unused-chunk cleanup has done to this world, and when.

A feature that quietly deletes parts of somebody's world owes them the
receipts: how much it reclaimed, when it last ran, and which worlds it left
alone. It is also what turns an abstract switch into "this saved you 1.8 GB".

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Queue an unused-chunk trim now, once per minintervalhours {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`

Queue an unused-chunk trim now, once per ``min_interval_hours``.

Free and paid alike. Safety checks (offline, lease, node concurrency) stay
with the job; this endpoint only gates the once-per-day customer button and
that the feature is on for this server. Platform dry-run mode still applies.

Cooldown is based on ``last_run_at``, not a pre-reserve of ``next_eligible_at``,
so a queued job that exits before recording a run cannot lock the button.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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