Skip to main content

Reference: Alerting API

The alerting service runs on port 8082 and manages alert rules for your org. The UI reaches it via the nginx proxy (/alerting/ rewrites to alerting:8082). You can also call it directly from scripts or CI pipelines.

All endpoints require a valid session JWT (the bearer token from your AtherOps login). The tenant (org_id) is always derived server-side from the JWT claims. You cannot request data belonging to another org; cross-org requests return 404.

Authentication​

Authorization: Bearer <JWT>

Use POST /api/auth/login to obtain a token (see Ingest API: Get a query token).

Endpoints​

List alert rules​

GET /rules
Authorization: Bearer <JWT>

Returns all alert rules for the authenticated org.

Response 200 OK:

[
  {
    "id": "a1b2c3d4",
    "name": "High CPU",
    "severity": "warning",
    "expr": "cpu_usage_percent > 90",
    "for": "5m",
    "enabled": true,
    "created_at": "2026-05-01T10:00:00Z"
  }
]

An empty array [] means no rules exist yet.

Get rule status​

GET /rules/{id}/status
Authorization: Bearer <JWT>

Returns the live evaluation state of a single alert rule. The alerting service queries vmalert in real time for enabled rules.

Path parameter:

ParameterTypeDescription
idstringThe rule UUID (from GET /rules)

Response 200 OK:

{"state": "firing", "active_alerts": 2, "last_eval": "2026-05-30T00:01:00Z"}
FieldTypeDescription
statestring"firing", "pending", or "inactive" (see below)
active_alertsintNumber of currently active alert instances
last_evalstring (RFC3339)Time of the most recent vmalert evaluation; absent if not yet evaluated

States:

StateMeaning
firingAt least one alert instance is currently active
pendingThe rule expression matches but the for: duration has not elapsed yet
inactiveThe rule is enabled but no alert instances match

Special cases:

  • A disabled rule always returns 200 {"state":"inactive","active_alerts":0}. vmalert is not queried (disabled rules are not pushed to vmalert).
  • If the rule exists in the database but vmalert has not loaded it yet (for example, vmalert is still starting up), the endpoint returns 200 inactive rather than an error.

Error responses:

StatusMeaning
401 UnauthorizedMissing or invalid JWT
404 Not FoundRule does not exist, or belongs to a different org
500 Internal Server ErrorUnexpected failure querying the database or vmalert

How the status is resolved:

Create alert rule​

POST /rules
Content-Type: application/json
Authorization: Bearer <JWT>

Request body:

{
  "name": "High CPU",
  "severity": "warning",
  "expr": "cpu_usage_percent > 90",
  "for": "5m",
  "enabled": true
}

Response 201 Created: the created rule object (same shape as the list response).

Update alert rule​

PUT /rules/{id}
Content-Type: application/json
Authorization: Bearer <JWT>

Same request body as create. Replaces the rule in full.

Response 200 OK: the updated rule object.

Delete alert rule​

DELETE /rules/{id}
Authorization: Bearer <JWT>

Response 204 No Content: rule deleted. Returns 404 if the rule does not exist or belongs to another org.

Environment variables (alerting service)​

VariableDefaultDescription
VMALERT_QUERY_URLhttp://vmalert:8880Base URL of the vmalert instance used to fetch live rule state

See also​