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/<organizationId>/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.

Name
search
Type
string
Description
Case-insensitive filter on the Alarm name.
Name
severities
Type
string[]
Description
Limit to severities: INFO, LOW, MEDIUM, HIGH, CRITICAL.
Name
statuses
Type
string[]
Description
enabled, disabled or both.
Name
isTriggered
Type
boolean
Description
Only Alarms currently in the triggered state.
Name
deviceVariableIds
Type
string[]
Description
Limit to Alarms on these Variables. Related filters exist for assetIds, locationIds and alarmGroupIds.
Name
archivedScope
Type
string
Description
active (default), archived or all.
Name
skip
Type
integer
Description
Records to skip. See Pagination.
Name
take
Type
integer
Description
Records to return per page.

curl -X POST 'https://api.controlcomtech.com/primary/v1/<organizationId>/alarms/search' \
--header 'Authorization: Basic <Base64 encoded key ID and secret>' \
--header 'Content-Type: application/json' \
--data '{ "severities": ["HIGH", "CRITICAL"], "take": 25 }'

Retrieve an Alarm

GET https://api.controlcomtech.com/primary/v1/<organizationId>/alarms/<alarmId>

Returns a single Alarm configuration by id.

Create an Alarm

POST https://api.controlcomtech.com/primary/v1/<organizationId>/alarms

Requires the CreateAlarmConfiguration permission.

Name
name
Type
string
Description
Required, 1 to 100 characters.
Name
isActive
Type
boolean
Description
Required. Whether the Alarm evaluates incoming readings.
Name
deviceId
Type
string
Description
Required. The Device that owns the watched Variable.
Name
deviceVariableId
Type
string
Description
Required. The Variable the Alarm watches.
Name
operator
Type
string
Description
Required. LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, EQUAL or NOT_EQUAL.
Name
alarmGroupId
Type
string | null
Description
Required key, nullable. The Alarm Group used for notification routing, or null for ungrouped.
Name
thresholdValueNumber
Type
number | null
Description
The threshold for NUMBER Variables (0 to 999999). String and boolean Variables use thresholdValueString and thresholdValueBoolean instead.
Name
severity
Type
string
Description
Optional, defaults to MEDIUM. One of INFO, LOW, MEDIUM, HIGH, CRITICAL.
Name
isAcknowledgeable
Type
boolean
Description
Optional, defaults to false. Whether raised events can be acknowledged by users.
Name
delayProcessingSeconds
Type
integer | null
Description
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/<organizationId>/alarms/<alarmId>

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/<organizationId>/alarms/<alarmId>
PATCH  https://api.controlcomtech.com/primary/v1/<organizationId>/alarms/<alarmId>/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/<organizationId>/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.