# Allocations endpoints (Client API: game servers)

> 6 FeatherPanel Client API: game servers endpoints from user/server/allocations.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/user/server/allocations/

Defined in [`backend/app/routes/user/server/allocations.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php). Authentication used here: **Server access**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/user/servers/{uuidShort}/allocations`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-allocations`)
- Route name: `session-server-allocations`
- Controller: [`ServerAllocationController::getServerAllocations`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L27)

**Get server allocations** Retrieve all allocations assigned to a specific server that the user owns or has subuser access to.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Response data: [`AllocationResponse`](https://featherpanel.com/docs/api/schemas/#schema-allocationresponse)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `server` | ServerAllocationInfo |  |
| `allocations` | ServerAllocation\[\] |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Server allocations retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found · `500` Internal server error - Failed to retrieve allocations

### DELETE `/api/user/servers/{uuidShort}/allocations/{allocationId}`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-allocations`)
- Route name: `session-server-delete-allocation`
- Controller: [`ServerAllocationController::deleteAllocation`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L51)

**Delete server allocation** Remove an allocation from a server. Cannot delete the primary allocation.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `allocationId` | path | integer | yes | Allocation ID to delete |

Response data: [`AllocationDeleteResponse`](https://featherpanel.com/docs/api/schemas/#schema-allocationdeleteresponse)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `deleted_allocation_id` | integer | ID of the deleted allocation |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations/$ALLOCATION_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:allocation:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-allocation-deleted)

Responses: `200` Allocation deleted successfully · `400` Bad request - Missing parameters, allocation mismatch, or primary allocation deletion attempt · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or allocation not found · `500` Internal server error - Failed to delete allocation

### POST `/api/user/servers/{uuidShort}/allocations/{allocationId}/primary`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-allocations`)
- Route name: `session-server-set-primary-allocation`
- Controller: [`ServerAllocationController::setPrimaryAllocation`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L76)

**Set primary allocation** Set a specific allocation as the primary allocation for the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `allocationId` | path | integer | yes | Allocation ID to set as primary |

Response data: [`PrimaryAllocationResponse`](https://featherpanel.com/docs/api/schemas/#schema-primaryallocationresponse)

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `new_primary_allocation_id` | integer | ID of the new primary allocation |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations/$ALLOCATION_ID/primary" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:allocation:set_primary`](https://featherpanel.com/docs/plugins/events/server-allocation/#server-allocation-set-primary)

Responses: `200` Primary allocation updated successfully · `400` Bad request - Missing parameters or allocation mismatch · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or allocation not found · `500` Internal server error - Failed to update primary allocation

### PATCH `/api/user/servers/{uuidShort}/allocations/{allocationId}/notes`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-allocation-notes`)
- Route name: `session-server-allocation-notes`
- Controller: [`ServerAllocationController::updateAllocationNotes`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L101)

**Update allocation note** Set or clear the note the server's users keep on one of its allocations. The note is removed automatically when the allocation leaves the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `allocationId` | path | integer | yes | Allocation ID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `notes` | string | no | Note text; empty or null clears it |

```bash
curl -X PATCH "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations/$ALLOCATION_ID/notes" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"notes":""}'
```

Responses: `200` Note updated · `400` Invalid note or allocation mismatch · `403` Missing allocation.update permission · `404` Server or allocation not found

### GET `/api/user/servers/{uuidShort}/allocations/available`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-allocations`)
- Route name: `session-server-available-allocations`
- Controller: [`ServerAllocationController::getAvailableAllocations`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L126)

**Get available allocations** Retrieve all available (unassigned) allocations that can be assigned to the server. Supports pagination and search.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `page` | query | integer | no | Page number (default: 1) |
| `limit` | query | integer | no | Items per page (default: 20, max: 100) |
| `search` | query | string | no | Search query for IP address, port, alias, or notes |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `allocations` | ServerAllocation\[\] |  |
| `pagination` | object |  |
| `search` | object |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations/available" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Available allocations retrieved successfully · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server not found

### POST `/api/user/servers/{uuidShort}/allocations/auto`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-allocations`)
- Route name: `user-server-allocations-auto`
- Controller: [`ServerAllocationController::autoAllocate`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/ServerAllocationController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/allocations.php#L152)

**Auto-allocate allocation** Automatically assign a free allocation to the server. Only assigns one allocation at a time. Optionally accepts an allocation\_id to assign a specific allocation.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Response data: [`AutoAllocationResponse`](https://featherpanel.com/docs/api/schemas/#schema-autoallocationresponse)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `allocation_id` | integer | no | Specific allocation ID to assign. If not provided, a random allocation will be selected. |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `assigned_allocation` | ServerAllocation |  |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/allocations/auto" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"allocation_id":0}'
```

Plugin events: [`featherpanel:server:allocation:create`](https://featherpanel.com/docs/plugins/events/server/#server-allocation-created)

Responses: `200` Allocation assigned successfully · `400` Bad request - Missing UUID, allocation limit reached, no free allocations available, or invalid allocation ID · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or allocation not found · `500` Internal server error - Failed to assign allocation