REST API - AlarmEventMessage (Optional)

If the customer detects some condition that should be alerted to a RaPTr Scanner UI, this method can be used to display custom text on the alarm banner. The alarm will persist until a request is received where the AlarmKey matched the original alarm and the ActiveStatus bool is false.

Endpoint

POST
[http vs https]://[Supervisor Hostname]:[REST API Supervisor Port (if greater than 0)]/AlarmEventMessage

---

 

Request

Headers
Content-Type: application/json

Request Body
The body of the request should include the following fields in JSON format:

Example JSON Payload:

{
  "LocationID": 3,                        // Unique identifier of the RaPTr unit (unsigned int)
  "AckRequired": true,                   // Whether user acknowledgment is required to clear alarm (boolean)
  "AlarmKey": "TEMP_OVER_THRESHOLD",     // Unique string identifier for this alarm event (string)
  "Text": "TEMPERATURE EXCEEDS LIMIT",   // Alarm message to display (string)
  "Severity": 3,                         // Severity level from 1 (low) to 4 (high) (integer)
  "ActiveStatus": true                   // True to activate alarm, false to clear (boolean)
}

Parameter Types:

• LocationID: unsigned int – Unique identifier of the RaPTr unit where the alarm should appear.

• AckRequired: bool – If true, user must acknowledge the alarm before it is cleared.

• AlarmKey: string – A unique identifier used to match and clear the alarm later.

• Text: string – Text that will be displayed in the RaPTr UI alarm banner.

• Severity: int – An integer from 1 to 4 indicating how severe the alarm is. 1 = low, 4 = critical.

• ActiveStatus: bool – Set to true to raise the alarm, false to deactivate/clear it.

---

 

Response

Success Response
HTTP Status: 200 OK

Response Body:

{
  "ResponseCode": 1,                        // 1 for success, 0 for failure (unsigned int)
  "ResponseString": "Alarm activated"       // Message describing the result (string)
}

Parameter Types:

• ResponseCode: unsigned int – 1 if the alarm message was successfully processed; 0 otherwise.

• ResponseString: string – Message indicating success or failure reason.

---

 

Example Flow: Activating an Alarm

Request:

POST [http vs https]://[Supervisor Hostname]:[REST API Supervisor Port (if greater than 0)]/AlarmEventMessage  

Body:

{
  "LocationID": 5,
  "AckRequired": true,
  "AlarmKey": "DOOR_OPEN_TOO_LONG",
  "Text": "DOOR OPEN TOO LONG",
  "Severity": 4,
  "ActiveStatus": true
}

Response:

{
  "ResponseCode": 1,
  "ResponseString": "Alarm activated"
}

---

 

Example Flow: Clearing an Alarm

Request:

POST [http vs https]://[Supervisor Hostname]:[REST API Supervisor Port (if greater than 0)]/AlarmEventMessage  

Body:

{
  "LocationID": 5,
  "AckRequired": true,
  "AlarmKey": "DOOR_OPEN_TOO_LONG",
  "Text": "DOOR OPEN TOO LONG",
  "Severity": 4,
  "ActiveStatus": false
}

Response:

{
  "ResponseCode": 1,
  "ResponseString": "Alarm cleared"
}

---

 

Notes

• Alarm messages will persist in the RaPTr UI until they are explicitly cleared using the same AlarmKey and setting ActiveStatus to false.

• If AckRequired is true, the UI may block further action until the operator confirms the alarm.

• AlarmKey is essential for correctly identifying and managing the alarm lifecycle.

• Alarms are visually differentiated based on Severity, allowing prioritization of response.