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.

    Secret API key. How it works

    Query parameters

    • project_idstring

      Only this project's alerts.

    Returns

    200 OK

    Response attributes

    • dataarray of Alertrequired

      12 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).

      • channelAlertChannelrequired

        2 attributes

        • typestringrequired

          One of slack webhook

        • urlstringrequireduri

          Public HTTPS destination. Private addresses and redirects are refused.

      • enabledbooleanrequired

      • 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.myleadsfactory.tech/api/alerts" \
  -H "Authorization: Bearer $MLF_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": "slack",
        "url": "https://example.com/hook"
      },
      "enabled": true,
      "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 posts to a Slack incoming webhook or your HTTPS URL 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 read-only. 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.

    • channelAlertChannelrequired

      2 attributes

      • typestringrequired

        One of slack webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

    • enabledboolean

      Default true.

    Returns

    201 OK

    Response attributes

    • dataAlertrequired

      12 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).

      • channelAlertChannelrequired

        2 attributes

        • typestringrequired

          One of slack webhook

        • urlstringrequireduri

          Public HTTPS destination. Private addresses and redirects are refused.

      • enabledbooleanrequired

      • 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 read-only 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.myleadsfactory.tech/api/alerts" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "metric": "call_count",
  "comparator": "gt",
  "threshold": 1,
  "window_seconds": 1,
  "channel": {
    "type": "slack",
    "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": "slack",
      "url": "https://example.com/hook"
    },
    "enabled": true,
    "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.

    Secret API key. How it works

    Path parameters

    • idstringrequired

      Alert id.

    Returns

    200 OK

    Response attributes

    • dataAlertrequired

      12 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).

      • channelAlertChannelrequired

        2 attributes

        • typestringrequired

          One of slack webhook

        • urlstringrequireduri

          Public HTTPS destination. Private addresses and redirects are refused.

      • enabledbooleanrequired

      • 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.myleadsfactory.tech/api/alerts/ALERT_ID" \
  -H "Authorization: Bearer $MLF_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": "slack",
      "url": "https://example.com/hook"
    },
    "enabled": true,
    "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.

    Secret API key, not read-only. 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

    • channelAlertChannel

      2 attributes

      • typestringrequired

        One of slack webhook

      • urlstringrequireduri

        Public HTTPS destination. Private addresses and redirects are refused.

    • enabledboolean

    Returns

    200 OK

    Response attributes

    • dataAlertrequired

      12 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).

      • channelAlertChannelrequired

        2 attributes

        • typestringrequired

          One of slack webhook

        • urlstringrequireduri

          Public HTTPS destination. Private addresses and redirects are refused.

      • enabledbooleanrequired

      • 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 read-only 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).
    PATCH /api/alerts/{id}
    curl -X PATCH "https://api.myleadsfactory.tech/api/alerts/ALERT_ID" \
  -H "Authorization: Bearer $MLF_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": "slack",
      "url": "https://example.com/hook"
    },
    "enabled": true,
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

    Delete an alert

    DELETE/api/alerts/{id}

    Removes the rule; it stops notifying at once.

    Secret API key, not read-only. 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 read-only 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).
    DELETE /api/alerts/{id}
    curl -X DELETE "https://api.myleadsfactory.tech/api/alerts/ALERT_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"
    Response 200
    {
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "deleted": true
  }
}