Monitoring and alerts
API reference for the fleet monitoring overview, services across servers, firing alerts, acknowledgements and alert rules.
Monitoring endpoints read what agents already report in their heartbeats: the latest metrics, a one-hour trend and the state of watched services on every server. Alert rules are evaluated by the panel's worker like Prometheus rules: when a rule's condition becomes true an event is pending, it becomes firing once the condition has held for the rule's durationSeconds, and resolved when it clears. A pending event whose condition clears is deleted.
For a single server's metric history, see Servers. For the concepts and the panel pages, see Monitoring and alerts.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/monitoring/overview | Get the fleet overview |
| GET | /api/v1/monitoring/services | List services across servers |
| GET | /api/v1/alerts/summary | Get the alert summary |
| GET | /api/v1/alerts/events | List alerts |
| POST | /api/v1/alerts/events/:id/acknowledge | Acknowledge an alert |
| GET | /api/v1/alerts/rules | List alert rules |
| POST | /api/v1/alerts/rules | Create an alert rule |
| PATCH | /api/v1/alerts/rules/:id | Update an alert rule |
| DELETE | /api/v1/alerts/rules/:id | Delete an alert rule |
Get the fleet overview
/api/v1/monitoring/overviewReturns every server with its latest metrics, its fullest filesystem, how many watched services have a problem (failed, or stopped although enabled at boot), a one-hour CPU and memory trend of up to 30 points, and its firing alerts by severity. firingAlerts is null when you lack alerts.read.
Example request
curl https://panel.example.com/api/v1/monitoring/overview \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items, totals } = await panel.monitoring.overview();Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"name": "web-1",
"status": "online",
"hostname": "web-1",
"cpuCores": 4,
"lastSeenAt": "2026-11-10T10:15:02.000Z",
"latestMetrics": {
"collectedAt": "2026-11-10T10:15:00.000Z",
"cpuPercent": 12.4,
"load": [0.42, 0.38, 0.35],
"memoryUsedBytes": 1879048192,
"memoryTotalBytes": 4294967296,
"swapUsedBytes": 0,
"swapTotalBytes": 1073741824,
"diskUsedBytes": 21474836480,
"diskTotalBytes": 85899345920,
"netRxBytesPerSec": 10240,
"netTxBytesPerSec": 20480,
"processCount": 187,
"uptimeSeconds": 864000
},
"fullestFilesystem": { "mount": "/", "percent": 25, "usedBytes": 21474836480, "totalBytes": 85899345920 },
"services": { "total": 14, "problems": 0 },
"trend": [{ "t": "2026-11-10T09:16:00.000Z", "cpu": 10.2, "memory": 43.1 }],
"firingAlerts": { "warning": 0, "critical": 0 }
}
],
"totals": { "servers": 1, "byStatus": { "pending": 0, "online": 1, "offline": 0, "disabled": 0 } }
},
"message": "OK",
"requestId": "…"
}List services across servers
/api/v1/monitoring/servicesReturns every watched systemd service on every connected server, as the agents last reported them, with the server each one runs on.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
state | string | No | all (default), running (active services only) or problem (failed, or stopped although enabled at boot). |
search | string | No | Part of a service or server name, up to 100 characters. |
Example request
curl "https://panel.example.com/api/v1/monitoring/services?state=problem" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.monitoring.services({ state: 'problem' });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"name": "nginx",
"loadState": "loaded",
"active": "failed",
"sub": "failed",
"enabled": "enabled",
"description": "A high performance web server and a reverse proxy server",
"problem": true,
"server": { "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "name": "web-1", "status": "online", "lastSeenAt": "2026-11-10T10:15:02.000Z" }
}
]
},
"message": "OK",
"requestId": "…"
}Get the alert summary
/api/v1/alerts/summaryCounts firing alerts, in total, not yet acknowledged and by severity. The panel's top bar uses it.
Example request
curl https://panel.example.com/api/v1/alerts/summary \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { firing, unacknowledged, bySeverity } = await panel.alerts.summary();Response 200 OK
{
"success": true,
"data": { "firing": 2, "unacknowledged": 1, "bySeverity": { "warning": 1, "critical": 1 } },
"message": "OK",
"requestId": "…"
}List alerts
/api/v1/alerts/eventsReturns alert events a page at a time, newest first.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | pending, firing, resolved, or open (pending and firing together). |
serverId | string (UUID) | No | Only alerts for this server. |
severity | string | No | warning or critical. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | startedAt (default) or resolvedAt; desc (default) or asc. |
Example request
curl "https://panel.example.com/api/v1/alerts/events?status=open" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.alerts.events({ status: 'open' });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "c0d1e2f3-…",
"ruleId": "b7c8d9e0-…",
"ruleName": "Disk almost full",
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"serverName": "web-1",
"metric": "disk_percent",
"subject": "/",
"severity": "critical",
"status": "firing",
"threshold": 90,
"value": 93.4,
"message": "Disk usage on / is 93% (threshold 90%)",
"startedAt": "2026-11-10T09:50:00.000Z",
"firedAt": "2026-11-10T09:55:00.000Z",
"resolvedAt": null,
"acknowledgedAt": null,
"acknowledgedBy": null,
"lastEvaluatedAt": "2026-11-10T10:15:00.000Z"
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}subject names what the alert is about when a rule covers several things: the filesystem for disk_percent, the service for service_down, the website's address for website_down.
Acknowledge an alert
/api/v1/alerts/events/:id/acknowledgeMarks a firing alert as acknowledged by you, so others know someone is on it. It keeps firing until its condition clears.
Example request
curl https://panel.example.com/api/v1/alerts/events/c0d1e2f3-a4b5-4c6d-8e7f-9a0b1c2d3e4f/acknowledge \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const event = await panel.alerts.acknowledge(eventId);Response 200 OK: the alert event, with acknowledgedAt and acknowledgedBy; message Alert acknowledged.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No alert with this id. |
| 409 | ALERT_NOT_ACKNOWLEDGEABLE | The alert is not firing, or was already acknowledged. |
List alert rules
/api/v1/alerts/rulesReturns every rule, oldest first, each with firingCount: how many of its alerts are firing now.
Example request
curl https://panel.example.com/api/v1/alerts/rules \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.alerts.rules();Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "b7c8d9e0-…",
"name": "Disk almost full",
"metric": "disk_percent",
"threshold": 90,
"durationSeconds": 300,
"severity": "critical",
"serverId": null,
"serverName": null,
"serviceName": null,
"isEnabled": true,
"createdAt": "2026-10-04T08:00:00.000Z",
"updatedAt": "2026-10-04T08:00:00.000Z",
"firingCount": 1
}
]
},
"message": "OK",
"requestId": "…"
}Create an alert rule
/api/v1/alerts/rulesCreates a rule. A rule without serverId applies to every server.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | 1 to 100 characters. |
metric | string | Yes | One of the metrics below. |
threshold | number or null | Metric rules | Required for the metric kinds, in the metric's range; ignored for the others. |
durationSeconds | integer | Yes | How long the condition must hold before the alert fires: 0 to 86400. |
severity | string | Yes | warning or critical. |
serverId | string (UUID) or null | No | One server, or every server when left out. |
serviceName | string or null | No | service_down only: one systemd service to watch. Without it, every watched service is checked. |
isEnabled | boolean | No | Default true. |
metric | Kind | threshold |
|---|---|---|
cpu_percent | Metric | 1 to 100 (%) |
memory_percent | Metric | 1 to 100 (%) |
disk_percent | Metric, per filesystem | 1 to 100 (%) |
swap_percent | Metric | 1 to 100 (%) |
load_per_core | Metric | 0.1 to 100 |
server_offline | The server stops reporting | None |
service_down | A service is down | None |
website_down | A website on the server fails the panel's uptime checks (one alert per website) | None |
self_check_failed | The server's self-check reports a failure | None |
Example request
curl https://panel.example.com/api/v1/alerts/rules \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Disk almost full", "metric": "disk_percent", "threshold": 90, "durationSeconds": 300, "severity": "critical" }'const rule = await panel.alerts.createRule({
name: 'Disk almost full',
metric: 'disk_percent',
threshold: 90,
durationSeconds: 300,
severity: 'critical',
});Response 201 Created: the rule, message Alert rule created.
Errors
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | A missing or out-of-range threshold, serviceName on a rule that is not service_down, an unknown server, or another invalid field. |
Update an alert rule
/api/v1/alerts/rules/:idChanges any of the rule's fields (the same fields as Create an alert rule, all optional; send at least one). The merged rule is checked again. Changing metric, threshold, serverId or serviceName, or turning the rule off, resolves its open alerts, since they no longer mean the same thing.
Example request
curl https://panel.example.com/api/v1/alerts/rules/b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e \
-X PATCH \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "threshold": 85 }'const rule = await panel.alerts.updateRule(ruleId, { threshold: 85 });Response 200 OK: the rule, message Alert rule updated.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No rule with this id. |
| 422 | VALIDATION_ERROR | No field given, or the merged rule is invalid. |
Delete an alert rule
/api/v1/alerts/rules/:idResolves the rule's open alerts and deletes it.
Example request
curl https://panel.example.com/api/v1/alerts/rules/b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.alerts.removeRule(ruleId);Response 200 OK: data is null, message Alert rule deleted.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No rule with this id. |
Server groups and bulk actions
API reference for server groups and bulk actions, which run one operation on many servers at once, in parallel or one server at a time.
Security
API reference for server firewalls, SSH settings and keys, Fail2ban, security updates, the login message, panel access by address, two-factor policy and sessions.