Alerts API

List and manage alert rules, and list/acknowledge/resolve fired alerts, via the API.

Alert rules (the threshold you configure) and fired alerts (an instance of a rule crossing that threshold) are two separate resources, each with its own ID. There's no "sustained duration" concept: a rule fires the moment its condition is true on the latest sample. See Alert Not Firing for how evaluation actually works.

Base URL: https://YOUR_KUBEWATCH_URL (your KubeWatch instance, shown in your dashboard)

All requests require authentication via Authorization: Bearer <token> or X-API-Key: <key>. Responses come back as bare JSON arrays, with no pagination or total count.

List alert rules

GET /api/v1/alerts/rules (or the equivalent /api/v1/alert-rules)

Response 200:

[
  {
    "id": "rule_1749984000000000000",
    "orgId": "org_xyz789",
    "name": "High CPU on prod-web",
    "description": "",
    "metric": "cpu_percent",
    "operator": "gt",
    "threshold": 90,
    "severity": "warning",
    "enabled": true,
    "createdAt": "2026-05-01T09:00:00Z"
  }
]

Create an alert rule

POST /api/v1/alerts/rules (or /api/v1/alert-rules)

Request:

{
  "name": "High CPU on prod-web",
  "description": "",
  "metric": "cpu_percent",
  "operator": "gt",
  "threshold": 90,
  "severity": "warning"
}

Fields:

Field	Type	Required	Description
`name`	string	Yes	Human-readable rule name
`description`	string	No	Optional free-text note
`metric`	string	Yes	A metric name with optional label matchers, e.g. `cpu_percent{container="web-app"}`. Only a single vector selector is accepted, not full PromQL
`operator`	string	Yes	`gt`, `gte`, `lt`, `lte`, `eq`
`threshold`	number	Yes	Threshold value
`severity`	string	No	Free-text severity label (e.g. `warning`, `critical`)

Notification channels are configured separately, not as part of the rule itself. See Settings → Notification channels.

Response 201: The created rule, same shape as the list response above.

Toggle an alert rule

PUT /api/v1/alerts/rules/{id}/toggle

Flips enabled for the rule (on → off or off → on).

Response 204: No content on success.

Update an alert rule

PUT /api/v1/alerts/rules/{id}

Send only the fields you want to change; anything omitted is left untouched. name, enabled, threshold, severity, and targetMetric are all applied. metric and operator can't be changed after creation: delete the rule and create a new one instead.

Request:

{
  "name": "High CPU on prod-web (renamed)",
  "enabled": false,
  "threshold": 95
}

Response 204: No content on success.

Delete an alert rule

DELETE /api/v1/alerts/rules/{id}

Response 204: No content on success.

List fired alerts

GET /api/v1/alerts

Returns up to the 200 most recent fired alerts for your organization, newest first.

Response 200:

[
  {
    "id": "alert_abc123",
    "orgId": "org_xyz789",
    "ruleId": "rule_1749984000000000000",
    "agentId": "agent_abc123xyz",
    "resourceId": "container_xyz",
    "resourceType": "container",
    "state": "firing",
    "message": "",
    "value": 94.2,
    "threshold": 90,
    "severity": "warning",
    "firedAt": "2026-06-12T09:55:00Z"
  }
]

Acknowledge a fired alert

PUT /api/v1/alerts/{id}/acknowledge

Sets the alert's state to acknowledged, which silences it without resolving it (that's different from Resolve, below). This only works while the alert is firing. A 404 means it wasn't found in that state, whether because it's already resolved, already acknowledged, or the ID is wrong.

Request body (optional):

{ "comment": "Investigating, known noisy alert on deploy" }

Response 204: No content on success.

Resolve a fired alert

PUT /api/v1/alerts/{id}/resolve

Marks a firing or acknowledged alert resolved.

Response 204: No content on success.