Client API: Container Apps: Allocations
The 7 Client API operations for allocations.
Part of Container Apps.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/client/servers/{uuid}/allocations |
List primary + extra ports for this server |
| POST | /api/v1/client/servers/{uuid}/allocations |
Create server allocation |
| 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 |
Allocation rules |
| DELETE | /api/v1/client/servers/{uuid}/allocations/{allocation_id} |
Release an extra port |
| 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 |
Set allocation publish port |
List primary + extra ports for this server
Section titled List primary + extra ports for this serverGET /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
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. |
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
Section titled Create server allocationPOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
Request body
Section titled Request bodyapplication/json
| Field | Type | Required |
|---|---|---|
port |
integer or null | no |
notes |
string or null | no |
on_dedicated_ip |
boolean | no |
Responses
Section titled 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)
Section titled Free ports on this server's node (node-wide, not shared across servers)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
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
uuid |
path | string | yes | |
limit |
query | integer | no | Default: 50. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Allocation rules
Section titled Allocation rulesGET /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
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. |
Release an extra port
Section titled Release an extra portDELETE /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
allocation_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Mark an existing port as the primary allocation
Section titled Mark an existing port as the primary allocationPOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
allocation_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Set allocation publish port
Section titled Set allocation publish portPOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
uuid |
path | string | yes |
allocation_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/json
| Field | Type | Required |
|---|---|---|
port |
integer or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |