Alerts

Alerts are raised when a machine metric crosses a configured threshold. Use these endpoints to review alerts, acknowledge or snooze them, and add comments. All endpoints require a bearer JWT. To configure what triggers an alert, see Alert Rules.

Endpoints

Method	Path	Description
GET	/api/v1/alerts	List alerts
GET	/api/v1/alerts/stats	Aggregated alert counts
GET	/api/v1/alerts/{alert_id}	Get a single alert
POST	/api/v1/alerts/{alert_id}/acknowledge	Acknowledge an alert
POST	/api/v1/alerts/bulk/acknowledge	Acknowledge many alerts
POST	/api/v1/alerts/{alert_id}/snooze	Snooze an alert
GET	/api/v1/alerts/{alert_id}/comments	List comments
POST	/api/v1/alerts/{alert_id}/comments	Add a comment

List alerts

GET /api/v1/alerts

Query parameters

Parameter	Type	Description
alert_id	uuid	Just this alert (what a portal notification links to)
machine_id	uuid	Filter by machine
severity	string	One of info, warning, critical
is_acknowledged	boolean	Filter by acknowledgment state
start_date	datetime	Alerts created on or after this time
end_date	datetime	Alerts created on or before this time
page	integer	Page number (default 1)
page_size	integer	Items per page (default 20, max 100)

Response: 200 OK

{
  "items": [
    {
      "id": "b7e2...",
      "tenant_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "machine_id": "550e8400-e29b-41d4-a716-446655440000",
      "severity": "critical",
      "metric_name": "temperature",
      "trigger_value": 87.3,
      "threshold_value": 85.0,
      "message": "Temperature exceeded the critical threshold.",
      "is_acknowledged": false,
      "acknowledged_at": null,
      "acknowledged_by": null,
      "snoozed_until": null,
      "created_at": "2026-08-07T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

Alert statistics

GET /api/v1/alerts/stats

Returns counts of unacknowledged alerts by severity.

{
  "total_active": 12,
  "critical_count": 3,
  "warning_count": 7,
  "info_count": 2
}

Get a single alert

GET /api/v1/alerts/{alert_id}

Returns one alert, or 404 if it does not exist or is not accessible to you.

Acknowledge an alert

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

Requires an operator or administrator role. Marks the alert acknowledged and records who acknowledged it. Returns 409 Conflict if the alert was already acknowledged.

Response: 200 OK (the updated alert)

Acknowledge many alerts

POST /api/v1/alerts/bulk/acknowledge

Requires an operator or administrator role. Acknowledge up to 1,000 alerts in one call.

{
  "alert_ids": [
    "b7e2...",
    "c8f3...",
    "d9a4..."
  ]
}

Response: 200 OK

{
  "acknowledged_count": 2,
  "already_acknowledged_ids": ["c8f3..."],
  "not_found_ids": []
}

Snooze an alert

POST /api/v1/alerts/{alert_id}/snooze

Requires an operator or administrator role. Suppresses the alert until the given time. The snooze_until value must be in the future and no more than 30 days out.

{
  "snooze_until": "2026-08-07T14:00:00Z"
}

Comments

GET /api/v1/alerts/{alert_id}/comments lists the comment thread for an alert. POST /api/v1/alerts/{alert_id}/comments adds a comment (body up to 2,000 characters).

{
  "body": "Investigated - bearing wear. Scheduling a replacement."
}

Response: 201 Created

{
  "id": "e1a2...",
  "author_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "author_name": "Jordan Rivera",
  "body": "Investigated - bearing wear. Scheduling a replacement.",
  "created_at": "2026-08-07T11:00:00Z",
  "updated_at": "2026-08-07T11:00:00Z"
}

The list response wraps comments in an items array with a total count.

Severity levels

Level	Description
info	Informational
warning	Metric above its warning threshold
critical	Metric above its critical threshold