Alerts endpoints
GET /api/v1/orgs/{org_id}/alert-channels
Section titled “GET /api/v1/orgs/{org_id}/alert-channels”List alert channels
By name. Never includes a secret.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of AlertChannelOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/alert-channels
Section titled “POST /api/v1/orgs/{org_id}/alert-channels”Add an alert channel
Store a channel. A webhook channel’s response carries its signing secret, once.
409 NOT_CONFIGURED for Slack, webhook and PagerDuty without CREDENTIALS_KEYS;
409 CHANNEL_NAME_TAKEN; 422 LIMIT_EXCEEDED past 20 channels; 422 RECIPIENT_NOT_MEMBER;
422 UNSAFE_URL for a webhook URL that is not https:// or resolves to a private address.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes |
Request body (application/json, required): ChannelCreate
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: AlertChannelSecretOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/orgs/{org_id}/alert-channels/{channel_id}
Section titled “DELETE /api/v1/orgs/{org_id}/alert-channels/{channel_id}”Delete an alert channel
Rules that name the channel keep its id and skip it until they are edited.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/alert-channels/{channel_id}
Section titled “GET /api/v1/orgs/{org_id}/alert-channels/{channel_id}”Get an alert channel
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertChannelOut |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/orgs/{org_id}/alert-channels/{channel_id}
Section titled “PATCH /api/v1/orgs/{org_id}/alert-channels/{channel_id}”Edit an alert channel
Change the name, config or secret. The kind never changes.
rotate_secret (webhooks only) generates a new signing secret, returned once. A new config
or secret clears verified_at. Errors as for the create.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes |
Request body (application/json, required): ChannelUpdate
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertChannelSecretOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/orgs/{org_id}/alert-channels/{channel_id}/deliveries
Section titled “GET /api/v1/orgs/{org_id}/alert-channels/{channel_id}/deliveries”List a channel’s deliveries
Newest first. status keeps pending, sent or failed deliveries.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes | |
status |
query | NotificationStatus or null | no | |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_DeliveryOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/alert-channels/{channel_id}/deliveries/{delivery_id}/retry
Section titled “POST /api/v1/orgs/{org_id}/alert-channels/{channel_id}/deliveries/{delivery_id}/retry”Retry a failed delivery
Queue a failed delivery again, with the same id, so receivers still deduplicate on it.
Its attempts start over and the worker picks it up at once; the last error stays until the
next attempt. 409 NOT_RETRYABLE unless the delivery is failed.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes | |
delivery_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: DeliveryOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/orgs/{org_id}/alert-channels/{channel_id}/test
Section titled “POST /api/v1/orgs/{org_id}/alert-channels/{channel_id}/test”Send a test notification
Deliver a test now. A failing channel is a 200 with status: "failed" and the error.
pending when a failure a retry might fix left it to the worker. sent records the channel
as verified. At most 10 tests per channel an hour (429 RATE_LIMITED). An email channel
while no email provider is configured is 409 NOT_CONFIGURED.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
org_id |
path | string (uuid) | yes | |
channel_id |
path | string (uuid) | yes | |
Idempotency-Key |
header | string or null | no | Makes a retry of this request safe: it runs once, then is replayed. min length 1, max length 128, pattern ^[\x21-\x7e]+$ |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: ChannelTestOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/alert-events
Section titled “GET /api/v1/projects/{project_id}/alert-events”List alert events
Newest first. state=firing keeps open events, state=resolved resolved ones.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
rule_id |
query | string (uuid) or null | no | |
state |
query | "firing" | "resolved" or null |
no | |
limit |
query | integer | no | min 1, max 200 Default 50. |
cursor |
query | string or null | no |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: Page_AlertEventOut_ |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/alert-events/{event_id}/acknowledge
Section titled “POST /api/v1/projects/{project_id}/alert-events/{event_id}/acknowledge”Acknowledge an alert event
Record that you have seen the event. 409 ALREADY_ACKNOWLEDGED the second time.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
event_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertEventOut |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/alert-rules
Section titled “GET /api/v1/projects/{project_id}/alert-rules”List alert rules
Firing rules first, then by name. Unpaginated: a project has at most 100 rules.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: array of AlertRuleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/alert-rules
Section titled “POST /api/v1/projects/{project_id}/alert-rules”Add an alert rule
Store a rule. 422 UNKNOWN_CHANNEL for a channel outside the organization; 422 LIMIT_EXCEEDED past 100 rules (budgets’ rules do not count).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): RuleSpec
| Status | Description | Body |
|---|---|---|
| 201 | Successful Response | application/json: AlertRuleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
DELETE /api/v1/projects/{project_id}/alert-rules/{rule_id}
Section titled “DELETE /api/v1/projects/{project_id}/alert-rules/{rule_id}”Delete an alert rule
Delete the rule with its state and events. A firing alert is resolved first and sends
alert.resolved. Notifications already queued still go out.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
rule_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 204 | Successful Response | none |
| 422 | Validation Error | application/json: HTTPValidationError |
GET /api/v1/projects/{project_id}/alert-rules/{rule_id}
Section titled “GET /api/v1/projects/{project_id}/alert-rules/{rule_id}”Get an alert rule
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
rule_id |
path | string (uuid) | yes |
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertRuleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
PATCH /api/v1/projects/{project_id}/alert-rules/{rule_id}
Section titled “PATCH /api/v1/projects/{project_id}/alert-rules/{rule_id}”Edit an alert rule
Replace the rule with the whole rule sent; its kind may change. Errors as for the create.
Changing what a firing rule measures or judges, or disabling it, resolves its alert first
and sends alert.resolved; renaming it or changing its channels or cooldown does not.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
rule_id |
path | string (uuid) | yes |
Request body (application/json, required): RuleSpec
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertRuleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/alert-rules/{rule_id}/mute
Section titled “POST /api/v1/projects/{project_id}/alert-rules/{rule_id}/mute”Mute an alert rule
Stop the rule’s notifications until until (at most 30 days ahead); null unmutes.
A muted rule still fires, resolves and records its events.
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes | |
rule_id |
path | string (uuid) | yes |
Request body (application/json, required): MuteRequest
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: AlertRuleOut |
| 422 | Validation Error | application/json: HTTPValidationError |
POST /api/v1/projects/{project_id}/alert-rules/preview
Section titled “POST /api/v1/projects/{project_id}/alert-rules/preview”Preview an alert rule
What the rule would have measured over the last 7 days, one point per window (at least an hour apart, at most 168 points), with its line at each point.
Reads only; at most 30 previews per person a minute (429 RATE_LIMITED).
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
project_id |
path | string (uuid) | yes |
Request body (application/json, required): RuleDefinition
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | application/json: RulePreviewOut |
| 422 | Validation Error | application/json: HTTPValidationError |