--- title: Alarms API description: Create, search, update, archive and restore Alarm configurations and query alarm history via the ControlCom Connect REST API. source: https://documentation.controlcomtech.com/api-reference/alarms --- # Alarms An Alarm configuration watches one Device Variable and raises events when the Variable's value crosses a threshold. The Alarms API manages these configurations and queries the history of raised events. > **Workflow Stage: Integrate** ## Search Alarms ``` POST https://api.controlcomtech.com/primary/v1//alarms/search ``` Requires the `ReadAlarmConfigurations` permission. Because alarm filters can be long, the search criteria are sent as a JSON body rather than query parameters. The response has the usual `{ count, items }` shape. * `search` (string): Case-insensitive filter on the Alarm name. * `severities` (string\[]): Limit to severities: `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. * `statuses` (string\[]): `enabled`, `disabled` or both. * `isTriggered` (boolean): Only Alarms currently in the triggered state. * `deviceVariableIds` (string\[]): Limit to Alarms on these Variables. Related filters exist for `assetIds`, `locationIds` and `alarmGroupIds`. * `archivedScope` (string): `active` (default), `archived` or `all`. * `skip` (integer): Records to skip. See [Pagination](https://documentation.controlcomtech.com/api-reference#pagination). * `take` (integer): Records to return per page. **cURL** ```bash curl -X POST 'https://api.controlcomtech.com/primary/v1//alarms/search' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data '{ "severities": ["HIGH", "CRITICAL"], "take": 25 }' ``` ## Retrieve an Alarm ``` GET https://api.controlcomtech.com/primary/v1//alarms/ ``` Returns a single Alarm configuration by id. ## Create an Alarm ``` POST https://api.controlcomtech.com/primary/v1//alarms ``` Requires the `CreateAlarmConfiguration` permission. * `name` (string): Required, 1 to 100 characters. * `isActive` (boolean): Required. Whether the Alarm evaluates incoming readings. * `deviceId` (string): Required. The Device that owns the watched Variable. * `deviceVariableId` (string): Required. The Variable the Alarm watches. * `operator` (string): Required. `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `EQUAL` or `NOT_EQUAL`. * `alarmGroupId` (string | null): Required key, nullable. The Alarm Group used for notification routing, or `null` for ungrouped. * `thresholdValueNumber` (number | null): The threshold for `NUMBER` Variables (0 to 999999). String and boolean Variables use `thresholdValueString` and `thresholdValueBoolean` instead. * `severity` (string): Optional, defaults to `MEDIUM`. One of `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. * `isAcknowledgeable` (boolean): Optional, defaults to `false`. Whether raised events can be acknowledged by users. * `delayProcessingSeconds` (integer | null): Optional, 0 to 900. How long the condition must hold before an event is raised. ## Update an Alarm ``` PATCH https://api.controlcomtech.com/primary/v1//alarms/ ``` Requires the `UpdateAlarmConfiguration` permission. Accepts the same fields as create, all optional; omitted fields keep their stored values. ## Archive and Restore ``` DELETE https://api.controlcomtech.com/primary/v1//alarms/ PATCH https://api.controlcomtech.com/primary/v1//alarms//restore ``` Both require the `DeleteAlarmConfiguration` permission. `DELETE` archives the Alarm rather than destroying it, so its event history is preserved; `restore` brings an archived Alarm back. Archived Alarms appear in searches with `archivedScope` set to `archived` or `all`. ## Alarm History ``` POST https://api.controlcomtech.com/primary/v1//alarm-history ``` Queries raised alarm events over a time window. The body requires `startTime` and `endTime` as epoch milliseconds, and accepts optional filters including `severities`, `assetIds`, `locationIds`, `alarmGroupIds` and `search`, plus `skip` and `take`. The response has the `{ count, items }` shape. Acknowledging events and writing event notes act on behalf of a specific user, so those operations require a user Bearer token rather than an API key. See [Authentication](https://documentation.controlcomtech.com/api-reference/authentication).