Manage servers registered in your Alpacon workspace.
List
List servers
Retrieve a paginated list of servers.
Request
GET /api/servers/servers/
Query parameters
| Parameter | Type | Description |
|---|
name | string | Filter by server name |
version | string | Filter by agent version |
enabled | boolean | Filter by enabled status |
commissioned | boolean | Filter by commissioned status |
owner | string | Filter by owner username |
groups | UUID | Filter by group ID |
exclude_group | UUID | Exclude servers in this group |
is_connected | boolean | Filter by connection status |
starred | boolean | Filter by starred status |
firewall_backend | string | Filter by firewall backend (iptables, nftables, firewalld, ufw) |
firewall_managed_by_alpacon | boolean | Filter by Alpacon-managed firewall |
search | string | Search across name, version, IP, owner, and group names |
ordering | string | Sort order (e.g., name, -load, starred). Default: starred, then name |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 25,
"next": "https://your-workspace.us1.alpacon.io/api/servers/servers/?page=2",
"previous": null,
"results": [
{
"id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
"name": "web-server-01",
"remote_ip": "203.0.113.10",
"is_root": true,
"is_connected": true,
"commissioned": true,
"starred": true,
"platform": "debian",
"cpu_physical_cores": 4,
"cpu_logical_cores": 8,
"cpu_type": "x86_64",
"physical_memory": 8589934592,
"os_name": "Ubuntu",
"os_version": "22.04",
"load": 0.45,
"boot_time": "2024-01-10T08:00:00Z",
"owner": {
"id": 1,
"name": "admin",
"email": "admin@example.com"
},
"groups": [
"b651cf10-9c48-5g14-9657-ee82d7c14430"
],
"rules": [1, 2],
"status": {
"code": "online",
"text": "Online"
},
"firewall_backend": "nftables",
"firewall_backend_version": "1.0.6",
"firewall_managed_by_alpacon": true
}
]
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/servers/servers/?is_connected=true&ordering=-load" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Get
Get server
Retrieve detailed information about a specific server. The retrieve response includes additional fields such as version, uptime, last_connectivity, started_at, added_at, and updated_at, but does not include starred or status.
Request
GET /api/servers/servers/{server_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
server_id | UUID | Yes | Server ID |
Response
{
"id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
"name": "web-server-01",
"remote_ip": "203.0.113.10",
"is_root": true,
"is_connected": true,
"commissioned": true,
"platform": "debian",
"cpu_physical_cores": 4,
"cpu_logical_cores": 8,
"cpu_type": "x86_64",
"physical_memory": 8589934592,
"os_name": "Ubuntu",
"os_version": "22.04",
"load": 0.45,
"boot_time": "2024-01-10T08:00:00Z",
"version": "3.2.1",
"uptime": 864000,
"last_connectivity": "2024-01-20T15:30:00Z",
"started_at": "2024-01-10T08:00:00Z",
"added_at": "2023-06-15T12:00:00Z",
"updated_at": "2024-01-20T15:30:00Z",
"owner": {
"id": 1,
"name": "admin",
"email": "admin@example.com"
},
"groups": [
"b651cf10-9c48-5g14-9657-ee82d7c14430"
],
"rules": [1, 2],
"firewall_backend": "nftables",
"firewall_backend_version": "1.0.6",
"firewall_managed_by_alpacon": true
}
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/servers/servers/7e3984de-49ab-4cc6-bcdf-21fbd35858b8/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create server
Register a new server in your workspace. Returns a one-time key and installation instructions. Default alert rules are automatically added.
Request
POST /api/servers/servers/
Request body
{
"name": "web-server-02",
"platform": "debian",
"groups": ["b651cf10-9c48-5g14-9657-ee82d7c14430"],
"rules": [1]
}
Parameters
| Field | Type | Required | Description |
|---|
name | string | Yes | Server name (slug format, max 20 characters). Disallowed names: join, localhost, null |
platform | string | Yes | OS platform (debian or rhel). Write-only |
groups | array[UUID] | No | Group IDs to assign |
rules | array[integer] | No | Alert rule IDs to assign |
Response
{
"id": "8f4985df-50bc-42e5-b827-32fcc46959a2",
"name": "web-server-02",
"platform": "debian",
"key": "alpacon_server_key_xxxxxxxxxx",
"instruction_1": "curl -fsSL https://repo.alpacon.io/install.sh | sudo bash",
"instruction_2": "sudo alpacon-client setup --key alpacon_server_key_xxxxxxxxxx --endpoint your-workspace.us1.alpacon.io",
"groups": ["b651cf10-9c48-5g14-9657-ee82d7c14430"],
"rules": [1, 2]
}
The key is only shown once. Use the provided instructions to install and configure the Alpacon agent on your server.
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/servers/servers/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"name": "web-server-02", "platform": "debian"}'
Update
Update server
Update server properties. Supports partial updates via PATCH.
Request
PATCH /api/servers/servers/{server_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
server_id | UUID | Yes | Server ID |
Request body
{
"name": "web-server-01-updated",
"owner": "a540bf0f-8b37-4f03-8546-dd71c6b03329",
"groups": [
"b651cf10-9c48-5g14-9657-ee82d7c14430"
],
"rules": [1, 3]
}
Parameters
| Field | Type | Required | Description |
|---|
name | string | No | New server name (slug format, max 20 characters) |
owner | UUID | No | New owner user ID |
groups | array[UUID] | No | Group IDs to assign |
rules | array[integer] | No | Alert rule IDs to assign |
Response
Returns the full server object with updated fields (same schema as Get server).
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/servers/servers/7e3984de-49ab-4cc6-bcdf-21fbd35858b8/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"name": "web-server-01-updated", "owner": "a540bf0f-8b37-4f03-8546-dd71c6b03329"}'
Delete
Delete server
Remove a server from your workspace. The server must be disconnected before deletion. Use the ?auto=true query parameter to remotely uninstall the agent before deleting.
Request
DELETE /api/servers/servers/{server_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
server_id | UUID | Yes | Server ID |
Query parameters
| Parameter | Type | Description |
|---|
auto | boolean | When true, remotely uninstalls the agent before deletion |
Response
204 No Content
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/servers/servers/7e3984de-49ab-4cc6-bcdf-21fbd35858b8/?auto=true" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
The server must be disconnected to delete it. If the server is still connected, pass ?auto=true to remotely uninstall the agent first, or manually disconnect before deleting.