API reference
Alerts
Rules that notify you when a metric crosses a threshold.
List alerts
GET/api/alerts
Alert rules in scope, with their thresholds and where they notify. Archived alerts are left out unless archived=true.
Secret API key. How it works
Query parameters
project_idstringOnly this project's alerts.
archivedbooleantrue: only archived alerts. Absent: only live ones.
Returns
200 OK
Response attributes
dataarray of Alertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/alerts" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
]
}Create an alert
POST/api/alerts
A rule that watches one call metric (count, total cost, average latency or error rate) over a rolling window and notifies a webhook, Slack incoming webhook or email address when it crosses the threshold, and again when it recovers. It does not repeat while it stays breached. An org-wide key must name project_id.
Secret API key, not a viewer key. How it works
Request body
project_idstringRequired for an org-wide key.
namestringrequirednot emptymetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredHow the metric compares with the threshold to fire.
One of
gtgteltltethresholdnumberrequiredwindow_secondsintegerrequiredmin 1The rolling window the metric is measured over.
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanDefault true.
Returns
201 OK
Response attributes
dataAlertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/alerts" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": 1,
"window_seconds": 1,
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
}
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Get an alert
GET/api/alerts/{id}
One alert rule, archived or not.
Secret API key. How it works
Path parameters
idstringrequiredAlert id.
Returns
200 OK
Response attributes
dataAlertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/alerts/ALERT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Update an alert
PATCH/api/alerts/{id}
Change any field of the rule, or turn it off with enabled: false. Send at least one field. An archived alert cannot be changed: restore it first.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredAlert id.
Request body
namestringnot emptymetricstringOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringOne of
gtgteltltethresholdnumberwindow_secondsintegermin 1channelobjectOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledboolean
Returns
200 OK
Response attributes
dataAlertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409
alert_archived: restore the alert first. - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PATCH "https://api.brightshoal.com/api/alerts/ALERT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Front desk",
"metric": "call_count"
}'{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Delete an alert permanently
DELETE/api/alerts/{id}
Only an archived alert can be deleted: 409 not_archived otherwise. Removes the rule for good; its audit entries stay. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredAlert id.
Returns
200 OK
Response attributes
dataDeleteResultrequired2 attributes
idstringrequireddeletedbooleanrequired
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 409
not_archived: archive the alert first. - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/alerts/ALERT_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"deleted": true
}
}Archive an alert
POST/api/alerts/{id}/archive
It stops firing at once and leaves the alerts list. Nothing is deleted and it can be restored. Archiving an archived alert is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredAlert id.
Returns
200 OK
Response attributes
dataAlertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/alerts/ALERT_ID/archive" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}Restore an archived alert
POST/api/alerts/{id}/restore
It is evaluated again on the next sweep (if enabled). Restoring a live alert is a no-op. Needs the admin role; audited.
Secret API key, not a viewer key. How it works
Path parameters
idstringrequiredAlert id.
Returns
200 OK
Response attributes
dataAlertrequired13 attributes
idstringrequiredorg_idstringrequiredproject_idstringrequirednamestringrequiredmetricstringrequiredOne of
call_countcost_totalavg_latency_mserror_ratecomparatorstringrequiredOne of
gtgteltltethresholdstringrequiredDecimal serialized as a string (numeric column).
window_secondsstringrequiredInteger serialized as a string (numeric column).
channelobjectrequiredOne of 3 shapes
Option 1
typestringrequiredOne of
webhookurlstringrequireduriPublic HTTPS destination. Private addresses and redirects are refused.
Option 2
typestringrequiredOne of
slackurlstringrequireduriSlack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.
Option 3
typestringrequiredOne of
emailtostringrequiredemailup to 254 characters
enabledbooleanrequiredarchived_atstring | nullISO 8601 timestampWhen it was archived; null while live. An archived alert never fires.
created_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X POST "https://api.brightshoal.com/api/alerts/ALERT_ID/restore" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"name": "Front desk",
"metric": "call_count",
"comparator": "gt",
"threshold": "string",
"window_seconds": "string",
"channel": {
"type": "webhook",
"url": "https://example.com/hook"
},
"enabled": true,
"archived_at": "2026-10-28T09:30:00.000Z",
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z"
}
}