Alerts API

List, create, and acknowledge alert rules via the API.

The Alerts API lets you manage alert rules and acknowledge firing alerts programmatically.

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>.

List alert rules

GET /api/v1/alerts

Returns all alert rules for the authenticated organization.

Query parameters: status (active, muted), limit, offset

Response 200:

{
  "alerts": [
    {
      "id": "alert_rule_abc123",
      "name": "High CPU on prod-web",
      "metric": "cpu_percent",
      "operator": ">",
      "threshold": 90,
      "durationSeconds": 300,
      "state": "firing",
      "currentValue": 94.2,
      "enabled": true,
      "channels": ["slack_abc", "email_xyz"],
      "createdAt": "2026-05-01T09:00:00Z",
      "firedAt": "2026-06-12T09:55:00Z"
    }
  ],
  "total": 7
}

Create an alert rule

POST /api/v1/alerts

Request:

{
  "name": "High CPU on prod-web",
  "metric": "cpu_percent",
  "operator": ">",
  "threshold": 90,
  "durationSeconds": 300,
  "scope": {
    "agentId": "agent_abc123xyz",
    "containerName": "web-app"
  },
  "channels": ["slack_abc123", "email_xyz456"]
}

Fields:

Field	Type	Required	Description
`name`	string	Yes	Human-readable rule name
`metric`	string	Yes	Metric name (e.g., `cpu_percent`, `memory_percent`, `restart_count`)
`operator`	string	Yes	`>`, `<`, `>=`, `<=`, `==`
`threshold`	number	Yes	Threshold value
`durationSeconds`	integer	No	Seconds condition must be true before firing (default: 0)
`scope.agentId`	string	No	Scope to a specific agent
`scope.containerName`	string	No	Scope to containers matching this name
`channels`	array	No	Notification channel IDs

Response 201:

{
  "id": "alert_rule_new123",
  "name": "High CPU on prod-web",
  "metric": "cpu_percent",
  "operator": ">",
  "threshold": 90,
  "durationSeconds": 300,
  "state": "inactive",
  "enabled": true,
  "createdAt": "2026-06-12T10:00:00Z"
}

Acknowledge a firing alert

POST /api/v1/alerts/{alertRuleId}/acknowledge

Moves a firing alert to the acknowledged state and suppresses repeat notifications for 4 hours.

Request body: empty or {}

Response 200:

{
  "id": "alert_rule_abc123",
  "state": "acknowledged",
  "acknowledgedAt": "2026-06-12T10:05:00Z",
  "acknowledgedBy": "user_abc123",
  "suppressUntil": "2026-06-12T14:05:00Z"
}

Response 409 (if alert is not in firing state):

{
  "error": "alert is not firing",
  "currentState": "resolved"
}

Update an alert rule

PATCH /api/v1/alerts/{alertRuleId}

Update any fields of an existing alert rule. Only include fields you want to change.

Request:

{
  "threshold": 95,
  "durationSeconds": 600
}

Response 200: Updated alert rule object.

Delete an alert rule

DELETE /api/v1/alerts/{alertRuleId}

Response 204: No content on success.