# Client API: External Servers

> Put a server you host yourself behind the game proxy: connection, tests and branding.

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

Put a server you host yourself behind the game proxy: connection, tests and branding.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/external-servers`](#op-get-api-v1-client-external-servers) | List external servers |
| GET | [`/api/v1/client/external-servers/regions`](#op-get-api-v1-client-external-servers-regions) | Regions a new or existing external server can be served from |
| GET | [`/api/v1/client/external-servers/{service_id}`](#op-get-api-v1-client-external-servers-service-id) | Get external server |
| PATCH | [`/api/v1/client/external-servers/{service_id}`](#op-patch-api-v1-client-external-servers-service-id) | Change where players are forwarded, how, and through which region |
| GET | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-get-api-v1-client-external-servers-service-id-custom-domain) | Get custom domain |
| POST | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-post-api-v1-client-external-servers-service-id-custom-domain) | Link custom domain |
| PATCH | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-patch-api-v1-client-external-servers-service-id-custom-domain) | Show the vanity hostname, or the hosted one, in the public server list |
| DELETE | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-delete-api-v1-client-external-servers-service-id-custom-domain) | Unlink custom domain |
| POST | [`/api/v1/client/external-servers/{service_id}/custom-domain/verify`](#op-post-api-v1-client-external-servers-service-id-custom-domain-verify) | Check the CNAME now rather than waiting for the next maintenance pass |
| POST | [`/api/v1/client/external-servers/{service_id}/test`](#op-post-api-v1-client-external-servers-service-id-test) | Status-ping the backend now and record the answer |

### List external servers {#op-get-api-v1-client-external-servers}

`GET /api/v1/client/external-servers`

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

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Regions a new or existing external server can be served from {#op-get-api-v1-client-external-servers-regions}

`GET /api/v1/client/external-servers/regions`

Regions a new or existing external server can be served from.

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

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get external server {#op-get-api-v1-client-external-servers-service-id}

`GET /api/v1/client/external-servers/{service_id}`

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Responses

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

### Change where players are forwarded, how, and through which region {#op-patch-api-v1-client-external-servers-service-id}

`PATCH /api/v1/client/external-servers/{service_id}`

Change where players are forwarded, how, and through which region.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `upstream_host` | string or null | no |
| `upstream_port` | integer or null | no |
| `proxy_protocol` | boolean or null | no |
| `real_ip` | boolean or null | no |
| `mode` | string or null | no |
| `bedrock_bridge` | boolean or null | no |
| `location_id` | integer or null | no |
| `display_name` | string or null | no |

#### Responses

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

### Get custom domain {#op-get-api-v1-client-external-servers-service-id-custom-domain}

`GET /api/v1/client/external-servers/{service_id}/custom-domain`

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Responses

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

### Link custom domain {#op-post-api-v1-client-external-servers-service-id-custom-domain}

`POST /api/v1/client/external-servers/{service_id}/custom-domain`

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `subdomain` | string | no |
| `include_in_list` | boolean | no |

#### Responses

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

### Show the vanity hostname, or the hosted one, in the public server list {#op-patch-api-v1-client-external-servers-service-id-custom-domain}

`PATCH /api/v1/client/external-servers/{service_id}/custom-domain`

Show the vanity hostname, or the hosted one, in the public server list.
This is the same switch the org portal has, for platform-direct customers.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `include_in_list` | boolean | yes |

#### Responses

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

### Unlink custom domain {#op-delete-api-v1-client-external-servers-service-id-custom-domain}

`DELETE /api/v1/client/external-servers/{service_id}/custom-domain`

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Responses

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

### Check the CNAME now rather than waiting for the next maintenance pass {#op-post-api-v1-client-external-servers-service-id-custom-domain-verify}

`POST /api/v1/client/external-servers/{service_id}/custom-domain/verify`

Check the CNAME now rather than waiting for the next maintenance pass.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Responses

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

### Status-ping the backend now and record the answer {#op-post-api-v1-client-external-servers-service-id-test}

`POST /api/v1/client/external-servers/{service_id}/test`

Status-ping the backend now and record the answer.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |

#### Responses

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