API Reference

Monitoring and alerts

API reference for the fleet monitoring overview, services across servers, firing alerts, acknowledgements and alert rules.

Last updated

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.

MethodPathDescription
GET/api/v1/monitoring/overviewGet the fleet overview
GET/api/v1/monitoring/servicesList services across servers
GET/api/v1/alerts/summaryGet the alert summary
GET/api/v1/alerts/eventsList alerts
POST/api/v1/alerts/events/:id/acknowledgeAcknowledge an alert
GET/api/v1/alerts/rulesList alert rules
POST/api/v1/alerts/rulesCreate an alert rule
PATCH/api/v1/alerts/rules/:idUpdate an alert rule
DELETE/api/v1/alerts/rules/:idDelete an alert rule

Get the fleet overview

GET/api/v1/monitoring/overview
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.read
Token scope
read

Returns 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

GET/api/v1/monitoring/services
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.read
Token scope
read

Returns every watched systemd service on every connected server, as the agents last reported them, with the server each one runs on.

Query parameters

NameTypeRequiredDescription
statestringNoall (default), running (active services only) or problem (failed, or stopped although enabled at boot).
searchstringNoPart 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

GET/api/v1/alerts/summary
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.read
Token scope
read

Counts 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

GET/api/v1/alerts/events
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.read
Token scope
read

Returns alert events a page at a time, newest first.

Query parameters

NameTypeRequiredDescription
statusstringNopending, firing, resolved, or open (pending and firing together).
serverIdstring (UUID)NoOnly alerts for this server.
severitystringNowarning or critical.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNostartedAt (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

POST/api/v1/alerts/events/:id/acknowledge
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.acknowledge
Token scope
manage

Marks 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

StatusCodeWhen
404NOT_FOUNDNo alert with this id.
409ALERT_NOT_ACKNOWLEDGEABLEThe alert is not firing, or was already acknowledged.

List alert rules

GET/api/v1/alerts/rules
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.read
Token scope
read

Returns 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

POST/api/v1/alerts/rules
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.manage
Token scope
manage

Creates a rule. A rule without serverId applies to every server.

Request body

FieldTypeRequiredDescription
namestringYes1 to 100 characters.
metricstringYesOne of the metrics below.
thresholdnumber or nullMetric rulesRequired for the metric kinds, in the metric's range; ignored for the others.
durationSecondsintegerYesHow long the condition must hold before the alert fires: 0 to 86400.
severitystringYeswarning or critical.
serverIdstring (UUID) or nullNoOne server, or every server when left out.
serviceNamestring or nullNoservice_down only: one systemd service to watch. Without it, every watched service is checked.
isEnabledbooleanNoDefault true.
metricKindthreshold
cpu_percentMetric1 to 100 (%)
memory_percentMetric1 to 100 (%)
disk_percentMetric, per filesystem1 to 100 (%)
swap_percentMetric1 to 100 (%)
load_per_coreMetric0.1 to 100
server_offlineThe server stops reportingNone
service_downA service is downNone
website_downA website on the server fails the panel's uptime checks (one alert per website)None
self_check_failedThe server's self-check reports a failureNone

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

StatusCodeWhen
422VALIDATION_ERRORA 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

PATCH/api/v1/alerts/rules/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.manage
Token scope
manage

Changes 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

StatusCodeWhen
404NOT_FOUNDNo rule with this id.
422VALIDATION_ERRORNo field given, or the merged rule is invalid.

Delete an alert rule

DELETE/api/v1/alerts/rules/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
alerts.manage
Token scope
manage

Resolves 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

StatusCodeWhen
404NOT_FOUNDNo rule with this id.