Alert Rules

Alert rules define what triggers an alert. Threshold rules watch a single metric, composite rules combine several conditions, and escalation policies re-notify when critical alerts go unresolved. All endpoints require a bearer JWT. To review the alerts these rules produce, see Alerts.

Endpoints

Method	Path	Description
POST	/api/v1/alert-rules	Create a threshold rule
GET	/api/v1/alert-rules	List threshold rules
PUT	/api/v1/alert-rules/{rule_id}	Update a threshold rule
DELETE	/api/v1/alert-rules/{rule_id}	Delete a threshold rule
GET	/api/v1/alert-rules/suggestions	Suggested thresholds
POST	/api/v1/composite-rules	Create a composite rule
GET	/api/v1/composite-rules	List composite rules
PUT	/api/v1/composite-rules/{rule_id}	Update a composite rule
DELETE	/api/v1/composite-rules/{rule_id}	Delete a composite rule
GET	/api/v1/escalation-policies	List escalation policies
POST	/api/v1/escalation-policies	Create an escalation policy
PUT	/api/v1/escalation-policies/{policy_id}	Update an escalation policy
DELETE	/api/v1/escalation-policies/{policy_id}	Delete an escalation policy

Threshold rules

A threshold rule defines a warning and a critical threshold for one metric. Set warning below critical for high-side alerts (value too high), or critical below warning for low-side alerts (value too low); the two thresholds must differ.

Create a threshold rule

POST /api/v1/alert-rules

Requires an account administrator role.

Field	Type	Required	Description
machine_id	uuid	No	Target machine; omit to apply across machines
metric_name	string	Yes	Metric to monitor (1–100 chars)
warning_threshold	number	Yes	Warning-level threshold
critical_threshold	number	Yes	Critical-level threshold

{
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "metric_name": "temperature",
  "warning_threshold": 75.0,
  "critical_threshold": 85.0
}

Response — 201 Created

{
  "id": "f0a1...",
  "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "metric_name": "temperature",
  "warning_threshold": 75.0,
  "critical_threshold": 85.0,
  "is_active": true,
  "created_by": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-08-07T10:00:00Z"
}

List threshold rules

GET /api/v1/alert-rules

Accepts an optional machine_id query parameter to filter by machine. Returns an array of rules.

Update and delete

PUT /api/v1/alert-rules/{rule_id} updates the thresholds or the active flag. DELETE /api/v1/alert-rules/{rule_id} removes the rule (204 No Content). Both require an account administrator role.

{
  "warning_threshold": 78.0,
  "critical_threshold": 88.0,
  "is_active": true
}

Suggested thresholds

GET /api/v1/alert-rules/suggestions

Returns suggested warning and critical thresholds derived from recent alert patterns. Accepts an optional language query parameter (default en).

{
  "suggestions": [
    {
      "metric_name": "temperature",
      "suggested_warning": 76.0,
      "suggested_critical": 86.0,
      "reason": "Based on recent readings and prior alerts.",
      "existing_rule_id": null
    }
  ],
  "message": null
}

Composite rules

A composite rule combines up to ten conditions with AND or OR logic, so an alert only fires when the whole expression is satisfied.

Create a composite rule

POST /api/v1/composite-rules

Requires an account administrator role.

Field	Type	Required	Description
machine_id	uuid	Yes	Target machine
name	string	Yes	Rule name (1–255 chars)
description	string	No	Free-text description
expression	object	Yes	The condition expression
expression.operator	string	No	AND or OR (default AND)
expression.conditions	array	Yes	1–10 conditions
severity	string	Yes	One of info, warning, critical
is_active	boolean	No	Whether the rule is active (default true)

Each condition has a metric, a comparison op (>, >=, <, <=, ==), a value, and an optional duration_seconds (how long the condition must hold; 0 checks instantaneously).

{
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "High temp and vibration",
  "severity": "critical",
  "expression": {
    "operator": "AND",
    "conditions": [
      { "metric": "temperature", "op": ">", "value": 80.0, "duration_seconds": 60 },
      { "metric": "vibration", "op": ">", "value": 7.0, "duration_seconds": 0 }
    ]
  },
  "is_active": true
}

Response — 201 Created

{
  "id": "aa11...",
  "machine_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "High temp and vibration",
  "description": null,
  "expression": {
    "operator": "AND",
    "conditions": [
      { "metric": "temperature", "op": ">", "value": 80.0, "duration_seconds": 60 },
      { "metric": "vibration", "op": ">", "value": 7.0, "duration_seconds": 0 }
    ]
  },
  "severity": "critical",
  "is_active": true,
  "created_at": "2026-08-07T10:00:00Z"
}

List, update, and delete

GET /api/v1/composite-rules lists composite rules and accepts an optional machine_id filter. PUT /api/v1/composite-rules/{rule_id} updates a rule and DELETE /api/v1/composite-rules/{rule_id} removes it. Update and delete require an account administrator role.

Escalation policies

An escalation policy re-notifies a chosen notification channel when an alert of a given severity remains open past a wait period.

List and create

GET /api/v1/escalation-policies returns all policies. POST /api/v1/escalation-policies creates one and requires an account administrator role.

Field	Type	Required	Description
name	string	Yes	Policy name (1–200 chars)
severity	string	Yes	One of critical, warning, info
wait_minutes	integer	Yes	Delay before escalating (1–1440)
channel_id	uuid	Yes	Notification channel to escalate to
is_active	boolean	No	Whether the policy is active (default true)

{
  "name": "Critical after 15 minutes",
  "severity": "critical",
  "wait_minutes": 15,
  "channel_id": "bb22...",
  "is_active": true
}

Response — 201 Created

{
  "id": "cc33...",
  "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "name": "Critical after 15 minutes",
  "severity": "critical",
  "wait_minutes": 15,
  "channel_id": "bb22...",
  "is_active": true,
  "created_at": "2026-08-07T10:00:00Z",
  "updated_at": "2026-08-07T10:00:00Z"
}

The channel_id references a notification channel — see Notifications.

Update and delete

PUT /api/v1/escalation-policies/{policy_id} updates a policy and DELETE /api/v1/escalation-policies/{policy_id} removes it (204 No Content). Both require an account administrator role.