# Client API: Container Apps: Allocations

> The 7 Client API operations for allocations.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/allocations`](#op-get-api-v1-client-servers-uuid-allocations) | List primary + extra ports for this server |
| POST | [`/api/v1/client/servers/{uuid}/allocations`](#op-post-api-v1-client-servers-uuid-allocations) | Create server allocation |
| GET | [`/api/v1/client/servers/{uuid}/allocations/available-ports`](#op-get-api-v1-client-servers-uuid-allocations-available-ports) | Free ports on this server's node (node-wide, not shared across servers) |
| GET | [`/api/v1/client/servers/{uuid}/allocations/rules`](#op-get-api-v1-client-servers-uuid-allocations-rules) | Allocation rules |
| DELETE | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}`](#op-delete-api-v1-client-servers-uuid-allocations-allocation-id) | Release an extra port |
| POST | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}/primary`](#op-post-api-v1-client-servers-uuid-allocations-allocation-id-primary) | Mark an existing port as the primary allocation |
| POST | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}/publish-port`](#op-post-api-v1-client-servers-uuid-allocations-allocation-id-publish-port) | Set allocation publish port |

### List primary + extra ports for this server {#op-get-api-v1-client-servers-uuid-allocations}

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

List primary + extra ports for this server. Requires allocation.read for subusers.

``publish_ip`` / ``effective_port`` / ``endpoint`` are where each port is
reachable once a floating IP is attached; ``ip`` / ``port`` stay the node
inventory.

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

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

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].node_id` | integer |
| `[].ip` | string |
| `[].port` | integer |
| `[].publish_port` | integer or null |
| `[].publish_ip` | string or null |
| `[].effective_port` | integer or null |
| `[].endpoint` | string or null |
| `[].dedicated` | boolean |
| `[].server_id` | integer or null |
| `[].assigned` | boolean |
| `[].is_primary` | boolean or null |
| `[].notes` | string or null |
| `[].purpose` | string or null |
| `[].label` | string or null |
| `[].managed` | boolean |
| `[].created_at` | string (date-time) or null |

### Create server allocation {#op-post-api-v1-client-servers-uuid-allocations}

`POST /api/v1/client/servers/{uuid}/allocations`

Allocate an extra port: the lowest free port or a specific free port in
10000–40000 on the node, or, with ``on_dedicated_ip``, any free unprivileged
port on the server's own floating IP. The server's allocation_limit caps
the node range. Subusers need allocation.create.

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 |
| --- | --- | --- |
| `port` | integer or null | no |
| `notes` | string or null | no |
| `on_dedicated_ip` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `node_id` | integer |
| `ip` | string |
| `port` | integer |
| `publish_port` | integer or null |
| `publish_ip` | string or null |
| `effective_port` | integer or null |
| `endpoint` | string or null |
| `dedicated` | boolean |
| `server_id` | integer or null |
| `assigned` | boolean |
| `is_primary` | boolean or null |
| `notes` | string or null |
| `purpose` | string or null |
| `label` | string or null |
| `managed` | boolean |
| `created_at` | string (date-time) or null |

### Free ports on this server's node (node-wide, not shared across servers) {#op-get-api-v1-client-servers-uuid-allocations-available-ports}

`GET /api/v1/client/servers/{uuid}/allocations/available-ports`

Free ports on this server's node (node-wide, not shared across servers).

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Allocation rules {#op-get-api-v1-client-servers-uuid-allocations-rules}

`GET /api/v1/client/servers/{uuid}/allocations/rules`

Limits and defaults around this server's ports: the node-range limit, the
rules for ports on its dedicated IP (when one is attached) and which default
port its players type. The list route stays a bare array for compatibility.

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

### Release an extra port {#op-delete-api-v1-client-servers-uuid-allocations-allocation-id}

`DELETE /api/v1/client/servers/{uuid}/allocations/{allocation_id}`

Release an extra port. Cannot delete the primary allocation.
Subusers need allocation.delete.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Responses

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

### Mark an existing port as the primary allocation {#op-post-api-v1-client-servers-uuid-allocations-allocation-id-primary}

`POST /api/v1/client/servers/{uuid}/allocations/{allocation_id}/primary`

Mark an existing port as the primary allocation. Needs allocation.update.

The primary is what the process binds as ``SERVER_PORT`` and what the brand
hostname routes to, so Wings is re-synced, the route re-pointed and a running
server restarts onto it; the ``publish`` block says what happened.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Responses

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

### Set allocation publish port {#op-post-api-v1-client-servers-uuid-allocations-allocation-id-publish-port}

`POST /api/v1/client/servers/{uuid}/allocations/{allocation_id}/publish-port`

Publish a port on the game's default port (25565 / 19132) of the attached
floating IP, or clear it. Wings rebinds and a running server restarts, as on
attach; the ``publish`` block says what happened. Needs allocation.update.

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |

#### Responses

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