Skip to main content
POST
/
v1
/
alarms
Create Alarm
curl --request POST \
  --url https://api.bland.ai/v1/alarms \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "metric_type": "<string>",
  "threshold": 123,
  "webhook_config": {},
  "email_addresses": [
    "<string>"
  ],
  "sms_numbers": [
    "<string>"
  ]
}
'
{
  "data": {
    "alarm": {
      "id": "c92e5e2d-0d41-4c6f-a194-7d9f99e34ab1",
      "metric_type": "api_errors",
      "enabled": true,
      "threshold": 33,
      "webhook_config": {
        "url": "https://example.com/webhooks/alarms",
        "headers": {
          "Content-Type": "appl***"
        }
      },
      "email_addresses": ["alerts@example.com"],
      "sms_numbers": ["+15555550123"],
      "created_at": "2026-03-12T15:56:21.836Z",
      "updated_at": "2026-03-12T15:56:21.836Z"
    }
  },
  "errors": null
}

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
metric_type
string
required
Metric to monitor. Allowed values: latency, api_errors, call_length.
​
threshold
number
required
Positive numeric threshold used for alarm trigger evaluation.Notes:
  • threshold is a sensitivity scalar (higher values are less sensitive; lower values are more sensitive).
  • The Dashboard may display an approximate ”% change” visualization for this value. Treat that UI percentage as a directional aid, not an exact conversion.
Dashboard sensitivity presets map to these threshold values:
  • Sensitive → 0.5
  • Normal → 1.0
  • Relaxed → 2.0
  • Critical → 2.5
​
webhook_config
object
Optional webhook destination for alarm notifications.webhook_config should be a JSON object with:
  • url (string, required)
  • headers (object, optional)
Example:
{
  "webhook_config": {
    "url": "https://example.com/webhooks/alarms",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer test-token"
    }
  }
}
​
email_addresses
string[]
Optional email recipients for notifications.
​
sms_numbers
string[]
Optional SMS recipients for notifications.

​
Response

​
data.alarm
object
Created alarm configuration object.
​
data.alarm.id
string
Alarm configuration ID.
​
data.alarm.metric_type
string
Metric tracked by this alarm.
​
data.alarm.threshold
number
Configured trigger threshold.
​
data.alarm.enabled
boolean
Whether this alarm is enabled.
​
errors
null|array
null on success, otherwise an array of error objects.
{
  "data": {
    "alarm": {
      "id": "c92e5e2d-0d41-4c6f-a194-7d9f99e34ab1",
      "metric_type": "api_errors",
      "enabled": true,
      "threshold": 33,
      "webhook_config": {
        "url": "https://example.com/webhooks/alarms",
        "headers": {
          "Content-Type": "appl***"
        }
      },
      "email_addresses": ["alerts@example.com"],
      "sms_numbers": ["+15555550123"],
      "created_at": "2026-03-12T15:56:21.836Z",
      "updated_at": "2026-03-12T15:56:21.836Z"
    }
  },
  "errors": null
}