Alert rules watch a server’s metrics and raise an alert when a value crosses a threshold, using the data the agent has already sent. Rules are evaluated on Alpacon’s own schedule, about once a minute—see Monitoring rules for how a rule decides to fire and clear.
Requires the Metrics extension to be enabled for the workspace, for every action—including reading the seeded default disk-usage rule that every server carries regardless of plan. That rule is still evaluated on a workspace with the extension off; this API just isn’t how you’d read it there.
List
List alert rules
Retrieve a paginated list of alert rules.
Request
GET /api/metrics/alert-rules/
Query parameters
| Parameter | Type | Description |
|---|
name | string | Filter by rule name |
owner | string | Filter by owner username |
target | string | Filter by target metric |
threshold | number | Filter by threshold |
operator | string | Filter by direction (gte or lte) |
device | string | Filter by device |
severity | string | Filter by severity (critical, warning, info) |
is_default | boolean | Filter by default status |
server | UUID | Only rules attached to this server |
exclude_server | UUID | Only rules not attached to this server |
search | string | Search across name, target, and default status |
ordering | string | Sort order. Default: -added_at |
page | integer | Page number |
page_size | integer | Results per page (default: 15, max: 100) |
Response
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "3f1c9b2e-6a4d-4e8f-9b1a-2c3d4e5f6a7b",
"owner": null,
"name": "Core disk usage",
"target": "disk-usage",
"threshold": 90,
"operator": "gte",
"duration_s": 0,
"recovery_threshold": 85,
"no_data_after_s": null,
"device": "",
"severity": "warning",
"is_default": true
},
{
"id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
"owner": {
"id": 1,
"name": "admin",
"email": "admin@example.com"
},
"name": "Sustained high CPU",
"target": "cpu-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 300,
"recovery_threshold": 70,
"no_data_after_s": 600,
"device": "",
"severity": "critical",
"is_default": false
}
]
}
Required scope: alert_rule:read
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/alert-rules/?target=cpu-usage" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Create
Create alert rule
Create a new alert rule.
Request
POST /api/metrics/alert-rules/
Request body
{
"name": "Sustained high CPU",
"target": "cpu-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 300,
"recovery_threshold": 70,
"no_data_after_s": 600,
"severity": "critical"
}
Parameters
| Field | Type | Required | Description |
|---|
name | string | Yes | Rule name. Must be unique in the workspace |
target | string | Yes | Metric to watch: cpu-usage, memory-usage, disk-usage, peak-read-bps, peak-write-bps, avg-read-bps, avg-write-bps, peak-input-pps, peak-input-bps, peak-output-pps, peak-output-bps, avg-input-pps, avg-input-bps, avg-output-pps, avg-output-bps |
threshold | number | Yes | The value that raises the alert |
operator | string | No | gte—raise at or above the threshold (default)—or lte—raise at or below it |
duration_s | integer | No | How long the condition has to hold before the alert raises, in seconds. Default 0: the first breaching sample raises it |
recovery_threshold | number | No | The value the metric has to reach before the alert clears. Must sit on the recovering side of threshold for the chosen operator—below it for gte, above it for lte. Leave empty and the threshold itself clears the alert |
no_data_after_s | integer | No | Raise a separate alert when no sample arrives for this many seconds. Must be at least this target’s collection interval and at most 86400 (24 hours). Leave empty to turn this off |
device | string | No | Limit the rule to one disk or network interface. Only valid on a device-scoped target—disk-usage and every disk I/O and network target above. Rejected on cpu-usage and memory-usage, which apply to the whole server |
severity | string | No | Severity the raised alert carries: critical, warning, or info. Default warning |
is_default | boolean | No | Whether this rule is automatically attached to every server registered afterward. Only one default rule per target and device |
Response
{
"id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
"owner": {
"id": 1,
"name": "admin",
"email": "admin@example.com"
},
"name": "Sustained high CPU",
"target": "cpu-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 300,
"recovery_threshold": 70,
"no_data_after_s": 600,
"device": "",
"severity": "critical",
"is_default": false
}
Required scope: alert_rule:create
Example
curl -X POST "https://your-workspace.us1.alpacon.io/api/metrics/alert-rules/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"name": "Sustained high CPU", "target": "cpu-usage", "threshold": 80, "duration_s": 300}'
Get
Get alert rule
Retrieve a specific alert rule by ID.
Request
GET /api/metrics/alert-rules/{rule_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
rule_id | UUID | Yes | Alert rule ID |
Response
{
"id": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
"owner": {
"id": 1,
"name": "admin",
"email": "admin@example.com"
},
"name": "Sustained high CPU",
"target": "cpu-usage",
"threshold": 80,
"operator": "gte",
"duration_s": 300,
"recovery_threshold": 70,
"no_data_after_s": 600,
"device": "",
"severity": "critical",
"is_default": false
}
Required scope: alert_rule:read
Example
curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
Update
Update alert rule
Update an existing alert rule. Supports partial updates via PATCH.
Request
PATCH /api/metrics/alert-rules/{rule_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
rule_id | UUID | Yes | Alert rule ID |
Request body
{
"threshold": 85,
"recovery_threshold": 75
}
Parameters
Same fields as Create alert rule, all optional. Changing operator or threshold is refused if it would leave this rule’s own recovery threshold or any server override’s recovery threshold on the wrong side of the new value.
Response
Returns the full alert rule object with updated fields (same schema as Get alert rule).
Required scope: alert_rule:update
Example
curl -X PATCH "https://your-workspace.us1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
-H "Content-Type: application/json" \
-d '{"threshold": 85, "recovery_threshold": 75}'
Delete
Delete alert rule
Remove an alert rule. A default rule (is_default: true) can’t be deleted while it’s still marked as default—unset is_default first.
Request
DELETE /api/metrics/alert-rules/{rule_id}/
Path parameters
| Parameter | Type | Required | Description |
|---|
rule_id | UUID | Yes | Alert rule ID |
Response
204 No Content
Required scope: alert_rule:delete
Example
curl -X DELETE "https://your-workspace.us1.alpacon.io/api/metrics/alert-rules/8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e/" \
-H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""