BrightshoalDocsOpen console
MenuAlerts

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_idstring

    Only this project's alerts.

  • archivedboolean

    true: only archived alerts. Absent: only live ones.

Returns

200 OK

Response attributes
  • dataarray of Alertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. 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).
GET /api/alerts
curl "https://api.brightshoal.com/api/alerts" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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_idstring

    Required for an org-wide key.

  • namestringrequirednot empty

  • metricstringrequired

    One of call_count cost_total avg_latency_ms error_rate

  • comparatorstringrequired

    How the metric compares with the threshold to fire.

    One of gt gte lt lte

  • thresholdnumberrequired

  • window_secondsintegerrequiredmin 1

    The rolling window the metric is measured over.

  • channelobjectrequired

    One of 3 shapes

    Option 1

    • typestringrequired

      One of webhook

    • urlstringrequireduri

      Public HTTPS destination. Private addresses and redirects are refused.

    Option 2

    • typestringrequired

      One of slack

    • urlstringrequireduri

      Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

    Option 3

    • typestringrequired

      One of email

    • tostringrequiredemailup to 254 characters

  • enabledboolean

    Default true.

Returns

201 OK

Response attributes
  • dataAlertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
POST /api/alerts
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"
  }
}'
Response 201
{
  "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

  • idstringrequired

    Alert id.

Returns

200 OK

Response attributes
  • dataAlertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
GET /api/alerts/{id}
curl "https://api.brightshoal.com/api/alerts/ALERT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Alert id.

Request body

  • namestringnot empty

  • metricstring

    One of call_count cost_total avg_latency_ms error_rate

  • comparatorstring

    One of gt gte lt lte

  • thresholdnumber

  • window_secondsintegermin 1

  • channelobject

    One of 3 shapes

    Option 1

    • typestringrequired

      One of webhook

    • urlstringrequireduri

      Public HTTPS destination. Private addresses and redirects are refused.

    Option 2

    • typestringrequired

      One of slack

    • urlstringrequireduri

      Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

    Option 3

    • typestringrequired

      One of email

    • tostringrequiredemailup to 254 characters

  • enabledboolean

Returns

200 OK

Response attributes
  • dataAlertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when 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). Wait Retry-After seconds. 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).
PATCH /api/alerts/{id}
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"
}'
Response 200
{
  "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

  • idstringrequired

    Alert id.

Returns

200 OK

Response attributes
  • dataDeleteResultrequired

    2 attributes
    • idstringrequired

    • deletedbooleanrequired

  • 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). Wait Retry-After seconds. 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).
DELETE /api/alerts/{id}
curl -X DELETE "https://api.brightshoal.com/api/alerts/ALERT_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Alert id.

Returns

200 OK

Response attributes
  • dataAlertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/alerts/{id}/archive
curl -X POST "https://api.brightshoal.com/api/alerts/ALERT_ID/archive" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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

  • idstringrequired

    Alert id.

Returns

200 OK

Response attributes
  • dataAlertrequired

    13 attributes
    • idstringrequired

    • org_idstringrequired

    • project_idstringrequired

    • namestringrequired

    • metricstringrequired

      One of call_count cost_total avg_latency_ms error_rate

    • comparatorstringrequired

      One of gt gte lt lte

    • thresholdstringrequired

      Decimal serialized as a string (numeric column).

    • window_secondsstringrequired

      Integer serialized as a string (numeric column).

    • channelobjectrequired

      One of 3 shapes

      Option 1

      • typestringrequired

        One of webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

      Option 2

      • typestringrequired

        One of slack

      • urlstringrequireduri

        Slack incoming webhook URL on hooks.slack.com or hooks.slack-gov.com, under /services/.

      Option 3

      • typestringrequired

        One of email

      • tostringrequiredemailup to 254 characters

    • enabledbooleanrequired

    • archived_atstring | nullISO 8601 timestamp

      When it was archived; null while live. An archived alert never fires.

    • created_atstringISO 8601 timestamp

    • updated_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). Wait Retry-After seconds. 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).
POST /api/alerts/{id}/restore
curl -X POST "https://api.brightshoal.com/api/alerts/ALERT_ID/restore" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "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"
  }
}