---
title: "Creates instance of alarm rules"
method: POST
path: "/v1/enterprise/{enterprise_id}/alarmrules/"
tags: ["esper_cloud_api_Alarms"]
---

# Creates instance of alarm rules

`POST /v1/enterprise/{enterprise_id}/alarmrules/`

⚠️ Android only. 

Creates a new alarm rule in the enterprise, defining the conditions under which a device metric alert is triggered and where notifications are sent. Alarm rules combine a monitored metric, a threshold condition, a set of target devices or groups, and one or more notification destinations into a single automated monitoring configuration.

An alert channel must already exist before it can be referenced in a new alarm rule. Create channels first via POST /v1/enterprise/{enterprise_id}/alertchannels/ if needed.

**Request body fields**

Required

enterprise — UUID of the enterprise

name — Display name for the rule

metric — The device metric to monitor (e.g., battery level, connectivity status)

conditions — Threshold definition object containing

value — Numeric threshold value

unit — Unit of measurement for the threshold

comparator — Comparison operator (e.g., less than, greater than, equals)

toggle_state — Boolean for toggle-based metrics (e.g., connectivity on/off)


realert_interval — Interval in minutes before re-alerting if the condition continues to be met

Optional

description — Human-readable description of the rule's purpose

devices — Array of specific device IDs to monitor; omit to target groups instead

groups — Array of device group IDs to monitor

alert_channels — Array of alert channel IDs (UUIDs) to notify when the rule fires

action_emails — Array of email addresses to notify directly, independent of alert channels

actions — Array of actions to perform when the rule fires

is_active — Whether the rule is active immediately on creation (defaults to active if omitted)

repeat_times — Number of times to repeat the alert

**Workflow**

Create alert channels via POST /alertchannels/ if they don't already exist

Create the alarm rule using this endpoint, referencing the channel IDs in alert_channels

Store the UUID id from the 201 response for future get, update, or delete operations

Monitor firing activity via GET /alarmrules/{alarm_id}/alarmhistory/

**Common use cases**

Setting up automated alerts for low battery thresholds across a device group

Monitoring connectivity status for devices in a specific location or fleet segment

Configuring re-alert intervals for persistent conditions that require ongoing attention

**Best practices**

Target groups rather than individual devices where possible — group-scoped rules automatically apply to new devices added to the group

Supply both alert_channels and action_emails if notifications need to reach both a shared channel and specific individuals

Set a sensible realert_interval to avoid alert fatigue — too short an interval on frequently triggered conditions can flood notification recipients

Use a descriptive name and description so the rule's purpose is clear when auditing via GET /alarmrules/

## Path parameters

- `enterprise_id` string, required

## Request body

- EsperCloudApiUpdateAlarmRule
  - `id` string, uuid
  - `enterprise` string, uuid, required
  - `devices` unknown[]
    - unknown
  - `groups` string[]
  - `name` string, required
  - `description` string
  - `metric` string, required
  - `conditions` object, required
    - `value` number, double
    - `unit` string
    - `comparator` string
    - `toggle_state` boolean
  - `action_emails` string[]
  - `actions` string[]
  - `alert_channels` string[]
  - `created_on` string, date-time
  - `updated_on` string, date-time
  - `is_active` boolean
  - `realert_interval` integer, required
  - `repeat_times` integer
  - `trigger_count` integer
  - `daily_trigger_count` integer

## Response `201`

successful operation

- EsperCloudApiAlarmRule
  - `id` string, uuid
  - `enterprise` string, uuid
  - `devices` object
    - `id` string, uuid
    - `device_name` string
    - `alias_name` string, nullable
  - `groups` string[]
  - `name` string
  - `description` string
  - `metric` string
  - `conditions` object
    - `value` number, double
    - `unit` string
    - `comparator` string
    - `toggle_state` boolean
  - `action_emails` string[]
  - `actions` string[]
  - `alert_channels` string[]
  - `created_on` string, date-time
  - `updated_on` string, date-time
  - `is_active` boolean
  - `realert_interval` integer
  - `repeat_times` integer
  - `trigger_count` integer
  - `daily_trigger_count` integer

## Other responses

- `400` — Bad request
- `401` — Authorization information is missing or invalid.
- `403` — Forbidden, no permission to perform this action.
- `500` — Internal server error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/versions/e1f64cbb488e/schema)