Skip to main content

Create an alert policy

POST 
/api/v1/orgs/{orgId}/alert-policies

Create a new alert policy definition. New policies always start disabled; call the enable/disable action afterwards to activate evaluation. Device/data-stream bindings are managed separately via the data-streams sub-resource, not part of this payload.

Request Body

  • policyName (string, required): Policy name. Must be unique within the org (among non-deleted policies). Ex: WaterLevel alert policy.
  • description (string, optional): Policy description. Max length: 500.
  • alertLevel (string, required): Trigger threshold expression, evaluated against the incoming numeric data stream value. A null value is evaluated as 0. Ex: >=70.
  • alertResetLevel (string, required): Reset/release threshold expression. Ex: <65.

Both expressions use the same format. Write one comparison operator (>=, <=, ==, !=, >, &lt;) followed by a number. Spaces are allowed, and the number can be negative or a decimal (Ex: &gt;= -5.5). Not supported: a leading + (+5), exponent notation (1e3), a number without a leading digit (.5), strings, booleans, and combined conditions such as AND/OR. The format is not validated. A policy created with a malformed expression is still created, but it never fires.

  • delay (integer, optional, default: 0): Seconds to wait after the trigger (or reset) condition is met before firing (or releasing) the alert. A reading that meets the opposite threshold during the wait cancels it. A reading that meets neither threshold does not cancel the wait, and another matching reading does not restart it. After a cancellation, the next match starts a new full wait. 0 fires or releases on the first matching reading. Must be non-negative.
  • notification (object, optional): Notification configuration for this policy. Omit to leave the policy without any notification target (no message is sent when it fires).
    • channelIds (string[], required): Existing channel IDs to notify. Ex: channel_3fa85f64-5717-4562-b3fc-2c963f66afa6. Every ID must belong to an existing channel in this org.
    • recipients (array, required): Recipients for the notification. Each item: name (string, optional), target (string, required), type (string, required: to/cc/bcc).
    • templateId (string, optional): Existing template ID to render. Use the templateId returned when the template was created. Ex: tpl_7fa85f64-5717-4562-b3fc-2c963f66afa6. Use together with variables; mutually exclusive with subject/content (providing both results in 400).
    • variables (object, optional): Key/value substitutions used when rendering the template. Ex: {"threshold": "70"}. Only meaningful together with templateId. Provide a value for every variable the template uses. If one is missing, the alert event is still created, but no notification is sent.
    • subject (string, optional): Literal subject line, used instead of a template. Mutually exclusive with templateId/variables.
    • content (string, optional): Literal message content, used instead of a template. Mutually exclusive with templateId/variables.

Responses

  • 201 Created: Alert policy created successfully.
  • 400 Bad Request: Validation error (missing required field, invalid range, or templateId+subject/content both provided).
  • 404 Not Found: A channelIds entry or templateId does not exist in this org.
  • 409 Conflict: An alert policy with the same policyName already exists in this org.

Request​

Responses​

Created