API reference
Alerts
5 operations in this area of the contract. Every one declares the permission it requires.
Contract version 0.2.0All areas
Operations
GET
/v1/alertsThe triage queue
Required permission: monitoring.alert.readlistAlerts
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | open | in_review | escalated | closed | — |
priority | query | p1 | p2 | p3 | p4 | — |
typology | query | string | — |
party_id | query | string | Narrows the queue to the alerts raised against one party, matched on the alert's own subject rather than looked up per row. This is what a customer profile asks for; without it the only way to show one customer's alert history is to read the whole triage queue and filter client-side, which silently goes wrong at the first page boundary. A value that is not a UUID is a 400, not an ignored filter. |
limit | query | integer | Page size, capped at 200. |
cursor | query | string | Opaque keyset cursor from a previous response. Offset pagination is deliberately not offered: `OFFSET 500000` is a table scan, and if it were offered it would be used (ADR-0012). Only the collections that document this parameter can be resumed. The rest report `truncated: true` and refuse a cursor rather than silently returning the first page again — see the `truncated` field on the page schemas. |
Responses
200Alerts, highest priority firstAlertPage
GET
/v1/alerts/{alertID}One alert
Required permission: monitoring.alert.readgetAlert
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
alertIDrequired | path | string | — |
Responses
200The alertAlert404—
POST
/v1/alerts/{alertID}/assignTake an alert
Required permission: monitoring.alert.triageassignAlert
Assigns the alert to the calling user. Self-assignment only, which is what a triage queue needs.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
alertIDrequired | path | string | — |
Responses
204Assigned404—
POST
/v1/alerts/{alertID}/closeClose an alert without escalating
Required permission: monitoring.alert.triagecloseAlert
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
alertIDrequired | path | string | — |
Responses
200The closed alertAlert404—422—
GET
/v1/alerts/{alertID}/traceWhy this alert fired
Required permission: monitoring.alert.readgetAlertTrace
The arithmetic, not the outcome: the rule version and its expression, the parameter values that were in force at evaluation time, the window, the computed aggregates, and the transactions the rule was looking at.
This is what makes an alert defensible two years later, when the thresholds have been retuned three times and nobody remembers what they were in August (mandate 7).
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
alertIDrequired | path | string | — |
Responses
200The evaluation trace and its evidenceobject404—