Appearance
Alarm
Description
The alarm module allows to setup logical expression that can be monitored. Those logical expression operate on the properties of the services of devices. For example one could create an expression that simply checks if the speed of a property is greater than a safe threshold. Those alarms can further be supported by Apple Push Notification and Google Cloud Messaging to enable easy integration in other applications and enable push notifications.
Guide
Due to the fact that the alarm module is rather complex and offers different kinds of API endpoints, this guide has been added. It will explain the steps that are required to set up an alarm. From the creation of the expression, up to push notifications.
Table of contents:
Expressions
An expression, in the context of the alarm feature, means a logical expression that can be checked and will be reevaluated once values used in the expression change. A very basic example would be: Property greater than zero. This logical expression will be reevaluated once the value for the property used changes. An alarm is considered to be active, when this expression returns true. As with other logical statements, the expression can be deeply nested and should offer enough flexibility to cover all cases. For a more structured explanation head over to the API section, especially the create configuration endpoint. Following are a few examples to offer a quick insight in the expression configuration.
json
{
"type": "AND",
"operatorA": {
"type": "AND",
"operatorA": {
"type": "AND",
"operatorA": {
"type": "LESSER",
"operatorB": -0.15,
"operatorA": {
"type": "SUBTRACT",
"operatorA": {
"property": "ride-speed"
},
"operatorB": {
"property": "rated-speed-min"
}
}
},
"operatorB": {
"type": "AND",
"operatorA": {
"type": "UNEQUAL",
"operatorA": {
"property": "rated-speed-min"
},
"operatorB": 0
},
"operatorB": {
"type": "UNEQUAL",
"operatorA": {
"property": "ride-speed"
},
"operatorB": 0
}
}
},
"operatorB": {
"type": "EQUAL",
"operatorA": {
"property": "calibrated"
},
"operatorB": true
}
},
"operatorB": {
"type": "GREATER",
"operatorA": {
"property": "total-rides"
},
"operatorB": 100
}
}
Starting of with a rather complex example, this expression checks whenever the device is running on a lower speed than expected. However, this will only be checked, whenever the device has a speed, is calibrated and has more than one hundred rides. Written as a logical statement this turns out to.
text
ride-speed - rated-speed-min < - 0.15
&& rated-speed-min != 0
&& ride-speed != 0
&& calibrated == true
&& total-rides > 100
In total there are four properties: ride-speed, rated-speed-min, -calibrated_, and total-rides. Whenever one of these properties changes, the expression will be reevaluated. Adding this expression as a config, with all other properties that are required to set up an alarm configuration, will return a watcherIdentifier
. This identifier can and will be used to identify this specific config. This is necessary, due to the fact that a device can have more than one alarm configured. The expression does offer the option to add the time dimension in to the logical statement. For example the expression
json
{
"type": "DURATION",
"operatorA": {
"type": "EQUAL",
"operatorA": {
"property": "maintenance"
},
"operatorB": 1
},
"operatorB": 30000
}
will check if the expression
text
maintenance == 1
is true for 30000 milliseconds. The duration feature can only be applied to expressions that resolve to a boolean value and should be used at the topmost level. Furthermore, an exemplary request body to create a configuration might look like the following:
json
{
"data": {
"icon": "in-maintenance"
},
"expression": {
"type": "DURATION",
"operatorA": {
"type": "EQUAL",
"operatorA": {
"property": "maintenance"
},
"operatorB": 1
},
"operatorB": 30000
},
"notification": {
"title": "Maintenance Title",
"body": "Maintenance Body"
},
"serviceIdentifier": "00000000-0000-0000-0000-000000000000",
"severity": 1
}
INFO
The service identifier needs to match the service identifier the properties belong to. The alarm will not function properly if the schema for the service at hand does not have a property named maintenance. This information will be directly taken from the schema feature. For a looser coupling with the schema feature, you can use the identifier and type property description, e.g. 0x2000.UINT8
. In this case this would indicate the property maintenance has the property identifier 0x2000 and is of type UINT8. This will be checked by the alarm feature while updating the status based on the expression used.
Status
The status is basically the result of the application of the expression on a given device with a given service. To stay within the maintenance example and the previous configuration, if the property maintenance of the service 00000000-0000-0000-0000-000000000000 changes from e.g. zero to one, and stays at one the for at least five minutes, a status change is generated. The alarm is considered active and the active status set to true. Afterwards, any change to the property to a different number will result in the status to be changed to false. This will change the status as well as the status history.
INFO
Currently, at most of one hundred status changes will be stored within the coldwave backend. Furthermore, these changes are an alternating pattern between false and true. Meaning, only fifty statues are stored, where the expression was actually resolved to true (meaning the alarm was considered active). However, the false entries can be used to calculate how long an alarm was active, or inactive.
The best endpoint, to fetch all the status data, would be the list status endpoint with the query parameter depth of five or greater.
shell
curl --location '<<URL>>/api/v1/alarms/status?depth=5&fixTypo=true' --header 'Authorization: Bearer <<TOKEN>>'
Details
The fixTypo query parameter set to true should be used. It resolves a typo within the response body. This query parameter will be ignored on later major releases, where the typo will be fixed, but was introduced to not add breaking changes for current deployments.
Push Notifications
Due to the fact that alarms are rather crucial, and you might not want to miss them, there is the option to subscribe to them. With some additional setup regarding, apple push notification (iOS) or google cloud messaging (Android) in the configuration part of this section, you are able to get notifications for alarms once subscribed. The most important information on how to set up a push notification service can be found in the create subscription endpoint.
Events
Following events are transmitted via the websocket.
An event that is sent over the websocket when a config has been added. This event requires read
access to the resource alarm.config
.
Name | Description |
---|---|
typestring constant | Constant value: ALARM_CONFIG_ADD |
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
severityinteger | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
expression | An expression that defines the alarm. The expression will be used to calculate whenever an alarm event is considered active or not. If the expression evaluates to true, an alarm is considered active. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Alternative 3LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 4AccumulateExpression | The accumulate operation can be used to check if a certain boolean value is true for a given duration. |
notificationoptional | |
Alternative 1object | An optional object that contains further information for push notifications. |
notification.titlestring | A short description title that will be shown to the user as the push notification. |
notification.bodystring | A more elaborative text that will provide additional information to the user. |
Alternative 2object | |
notification.__i18nSupportboolean optional | A required key for easier parsing when actually using translations. Default: true |
notification.translationsdictionary | |
notification.translations. #.title string | A short description title that will be shown to the user as the push notification. |
notification.translations. #.body string | A more elaborative text that will provide additional information to the user. |
datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
whitelistarray string optional | Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
blacklistarray string optional | Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
serviceIdentifierstring optional | The service identifier that will be used for the devices. This value is now deprecated and the service identifier should be added to the property itself. This field is here for backwards compatibility. |
References
ComputeExpressionName | Description |
---|---|
typestring enum | Possible values: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULO, BITWISE_AND, BITWISE_OR, BITWISE_XOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: GREATER, EQUAL_GREATER, LESSER, EQUAL_LESSER, EQUAL, UNEQUAL |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: AND, NAND, OR, NOR, XOR, NXOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Name | Description |
---|---|
typestring constant | Constant value: DURATION |
operatorA | The operator that has to evaluate to true for the given amount of milliseconds in the second operator. |
Alternative 1LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorBinteger | The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement. |
API
EndpointsCreate ConfigurationList ConfigurationGet ConfigurationUpdate ConfigurationDelete ConfigurationList Alarm StatusList Alarm Status for Service IdentifierList Alarm Status for Device IdentifierGet Alarm StatusGet Alarm StatusDelete Device Alarm StatusList Alarm MessagesCreate Alarm MessageDelete all Alarm MessagesGET Alarm MessagesUpdate MessageDelete Alarm MessagesSubscribe to NotificationsTest notificationsUnsubscribe from NotificationsList SubscriptionsGet Subscription
POST
GET
GET
PUT
DEL
GET
GET
GET
GET
GET
DEL
GET
POST
DEL
GET
PUT
DEL
POST
POST
POST
GET
GET
Create Configuration
Creates a new configuration.
POST
/api/v1/alarms/config
Access
This endpoint requires create
permission for the resource alarm.config
.
Query Parameter
Name | Description |
---|---|
forceboolean optional | Old and new alarms will be checked on similarity. When an existing alarm is similar it will not be added. It is possible to overwrite this behaviour by using the force query parameter. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
Request Body
Name | Description |
---|---|
severityinteger | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
expression | An expression that defines the alarm. The expression will be used to calculate whenever an alarm event is considered active or not. If the expression evaluates to true, an alarm is considered active. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Alternative 3LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 4AccumulateExpression | The accumulate operation can be used to check if a certain boolean value is true for a given duration. |
notificationoptional | |
Alternative 1object | An optional object that contains further information for push notifications. |
notification.titlestring | A short description title that will be shown to the user as the push notification. |
notification.bodystring | A more elaborative text that will provide additional information to the user. |
Alternative 2object | |
notification.__i18nSupportboolean optional | A required key for easier parsing when actually using translations. Default: true |
notification.translationsdictionary | |
notification.translations. #.title string | A short description title that will be shown to the user as the push notification. |
notification.translations. #.body string | A more elaborative text that will provide additional information to the user. |
datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
whitelistarray string optional | Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
blacklistarray string optional | Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
serviceIdentifierstring optional | The service identifier that will be used for the devices. This value is now deprecated and the service identifier should be added to the property itself. This field is here for backwards compatibility. |
References
ComputeExpressionName | Description |
---|---|
typestring enum | Possible values: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULO, BITWISE_AND, BITWISE_OR, BITWISE_XOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: GREATER, EQUAL_GREATER, LESSER, EQUAL_LESSER, EQUAL, UNEQUAL |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: AND, NAND, OR, NOR, XOR, NXOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Name | Description |
---|---|
typestring constant | Constant value: DURATION |
operatorA | The operator that has to evaluate to true for the given amount of milliseconds in the second operator. |
Alternative 1LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorBinteger | The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement. |
Response
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
List Configuration
Returns a list of all currently set up configurations.
GET
/api/v1/alarms/config
Access
This endpoint requires read
permission for the resource alarm.config
.
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
untranslatedboolean optional | Whenever to return the config as is or translate specific fields |
Response
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
settingsobject optional | The configuration for the watcher. Returned when the `depth` query parameter is set high enough. |
settings.severityinteger | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
settings.expression | An expression that defines the alarm. The expression will be used to calculate whenever an alarm event is considered active or not. If the expression evaluates to true, an alarm is considered active. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Alternative 3LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 4AccumulateExpression | The accumulate operation can be used to check if a certain boolean value is true for a given duration. |
settings.notificationoptional | |
Alternative 1object | An optional object that contains further information for push notifications. |
settings.notification.titlestring | A short description title that will be shown to the user as the push notification. |
settings.notification.bodystring | A more elaborative text that will provide additional information to the user. |
Alternative 2object | |
settings.notification.__i18nSupportboolean optional | A required key for easier parsing when actually using translations. Default: true |
settings.notification.translationsdictionary | |
settings.notification.translations. #.title string | A short description title that will be shown to the user as the push notification. |
settings.notification.translations. #.body string | A more elaborative text that will provide additional information to the user. |
settings.datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
settings.whitelistarray string optional | Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
settings.blacklistarray string optional | Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
settings.serviceIdentifierstring optional | The service identifier that will be used for the devices. This value is now deprecated and the service identifier should be added to the property itself. This field is here for backwards compatibility. |
References
ComputeExpressionName | Description |
---|---|
typestring enum | Possible values: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULO, BITWISE_AND, BITWISE_OR, BITWISE_XOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: GREATER, EQUAL_GREATER, LESSER, EQUAL_LESSER, EQUAL, UNEQUAL |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: AND, NAND, OR, NOR, XOR, NXOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Name | Description |
---|---|
typestring constant | Constant value: DURATION |
operatorA | The operator that has to evaluate to true for the given amount of milliseconds in the second operator. |
Alternative 1LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorBinteger | The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement. |
Get Configuration
Returns a specific configuration based on the given identifier.
GET
/api/v1/alarms/config/:watcherIdentifier
Access
This endpoint requires read
permission for the resource alarm.config
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
untranslatedboolean optional | Whenever to return the config as is or translate specific fields |
Response
Name | Description |
---|---|
severityinteger | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
expression | An expression that defines the alarm. The expression will be used to calculate whenever an alarm event is considered active or not. If the expression evaluates to true, an alarm is considered active. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Alternative 3LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 4AccumulateExpression | The accumulate operation can be used to check if a certain boolean value is true for a given duration. |
notificationoptional | |
Alternative 1object | An optional object that contains further information for push notifications. |
notification.titlestring | A short description title that will be shown to the user as the push notification. |
notification.bodystring | A more elaborative text that will provide additional information to the user. |
Alternative 2object | |
notification.__i18nSupportboolean optional | A required key for easier parsing when actually using translations. Default: true |
notification.translationsdictionary | |
notification.translations. #.title string | A short description title that will be shown to the user as the push notification. |
notification.translations. #.body string | A more elaborative text that will provide additional information to the user. |
datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
whitelistarray string optional | Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
blacklistarray string optional | Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
serviceIdentifierstring optional | The service identifier that will be used for the devices. This value is now deprecated and the service identifier should be added to the property itself. This field is here for backwards compatibility. |
References
ComputeExpressionName | Description |
---|---|
typestring enum | Possible values: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULO, BITWISE_AND, BITWISE_OR, BITWISE_XOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: GREATER, EQUAL_GREATER, LESSER, EQUAL_LESSER, EQUAL, UNEQUAL |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: AND, NAND, OR, NOR, XOR, NXOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Name | Description |
---|---|
typestring constant | Constant value: DURATION |
operatorA | The operator that has to evaluate to true for the given amount of milliseconds in the second operator. |
Alternative 1LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorBinteger | The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement. |
Update Configuration
Allows to update a single configuration.
PUT
/api/v1/alarms/config/:watcherIdentifier
Access
This endpoint requires read
permission for the resource alarm.config
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
Request Body
Name | Description |
---|---|
severityinteger optional | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
expressionoptional | An expression that defines the alarm. The expression will be used to calculate whenever an alarm event is considered active or not. If the expression evaluates to true, an alarm is considered active. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Alternative 3LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 4AccumulateExpression | The accumulate operation can be used to check if a certain boolean value is true for a given duration. |
notificationoptional | |
Alternative 1object | An optional object that contains further information for push notifications. |
notification.titlestring | A short description title that will be shown to the user as the push notification. |
notification.bodystring | A more elaborative text that will provide additional information to the user. |
Alternative 2object | |
notification.__i18nSupportboolean optional | A required key for easier parsing when actually using translations. Default: true |
notification.translationsdictionary | |
notification.translations. #.title string | A short description title that will be shown to the user as the push notification. |
notification.translations. #.body string | A more elaborative text that will provide additional information to the user. |
datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
whitelistarray string optional | Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
blacklistarray string optional | Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time. |
serviceIdentifierstring optional | The service identifier that will be used for the devices. This value is now deprecated and the service identifier should be added to the property itself. This field is here for backwards compatibility. |
References
ComputeExpressionName | Description |
---|---|
typestring enum | Possible values: ADD, SUBTRACT, MULTIPLY, DIVIDE, MODULO, BITWISE_AND, BITWISE_OR, BITWISE_XOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 4number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 5boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: GREATER, EQUAL_GREATER, LESSER, EQUAL_LESSER, EQUAL, UNEQUAL |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1ComputeExpression | To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two. |
Alternative 2PropertyWrapper | Object that wraps property information. |
Alternative 3SpecialWrapper | A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp! |
Alternative 4MetaWrapper | |
Alternative 5string | A simple string value you want to use for comparison or computation in the given expression. |
Alternative 6number | A simple number value you want to use for comparison or computation in the given expression. |
Alternative 7boolean | A simple boolean value you want to use for comparison or computation in the given expression. |
Name | Description |
---|---|
typestring enum | Possible values: AND, NAND, OR, NOR, XOR, NXOR |
operatorA | The first operator that will be used on the left side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorB | The second operator that will be used on the right side of the operand. |
Alternative 1 | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
Name | Description |
---|---|
typestring constant | Constant value: DURATION |
operatorA | The operator that has to evaluate to true for the given amount of milliseconds in the second operator. |
Alternative 1LogicExpression | An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen. |
Alternative 2CompareExpression | The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality |
operatorBinteger | The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
Delete Configuration
Will delete a configuration based on the identifier. Be aware that this delete cascades to every other resource, such as the subscriptions, the status of the alarms and the messages for the given configuration.
DELETE
/api/v1/alarms/config/:watcherIdentifier
Access
This endpoint requires delete
permission for the resource alarm.config
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
List Alarm Status
List all known alarm status.
WARNING
There is a typo in the API endpoint response. The key watchers in the response should be named devices. However, to not break existing APIs who use this endpoint, the correct name for the key (devices rather than watchers) is hidden behind the query parameter.
GET
/api/v1/alarms/status
Access
This endpoint requires read
permission for the resource alarm.status
.
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
fixTypoboolean optional | This API endpoint contains a typo. In order to allow all services to switch over to the correct key name this query parameter has been added. The query parameter will be removed in version five at the latest. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
untranslatedboolean optional | Whenever to return the config as is or translate specific fields |
removeTextboolean optional | Removes the human readable text from the response in order to use the translations provided by the config endpoint. This should be used if you want to switch languages. The config endpoint returns much less data than the alarm endpoint. |
removeStateboolean optional | Setting this query parameter to true will remove the property status for the device at the time of the alarm from the response which will greatly reduce payload size. |
fromnumber optional | UTC timestamp in milliseconds. Only alarm status changes that happened after this timestamp will be included in the response. |
tonumber optional | UTC timestamp in milliseconds. Only alarm status changes that happened before this timestamp will be included in the response. |
Response
Name | Description |
---|---|
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
devicesarray optional | List of all devices, only returned when the query parameter `fixTypo` is set to true and a `depth` greater than one is used. |
devices.[ ].deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
devices.[ ].watchersarray optional | List of all watchers. While an alarm configuration can be for multiple devices, the watcher at hand can be seen as the configuration for the given device. |
devices.[ ].watchers.[ ].watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
devices.[ ].watchers.[ ].stateobject optional | A state change for a given alarm. |
devices.[ ].watchers.[ ].state.sinceinteger | The timestamp when the state changed occurred. |
devices.[ ].watchers.[ ].state.idinteger | The identifier of the alarm state change. |
devices.[ ].watchers.[ ].state.alarmActiveboolean | Whenever the alarm is active or not. |
devices.[ ].watchers.[ ].state.messagesarray optional | The messages for that given alarm entry. |
devices.[ ].watchers.[ ].state.messages.[ ].timestampinteger | Timestamp of the message. |
devices.[ ].watchers.[ ].state.messages.[ ].idinteger | Unique identifier for the message. |
devices.[ ].watchers.[ ].state.messages.[ ].authorstring | The author of the message. |
devices.[ ].watchers.[ ].state.messages.[ ].messagestring | The content of the message. |
devices.[ ].watchers.[ ].state.statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
devices.[ ].watchers.[ ].state.state. #.propId integer | The identifier of the property |
devices.[ ].watchers.[ ].state.state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
devices.[ ].watchers.[ ].state.state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
devices.[ ].watchers.[ ].state.state. #.value optional | The value of the property |
devices.[ ].watchers.[ ].severityinteger optional | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
devices.[ ].watchers.[ ].notificationobject optional | An optional object that contains further information for push notifications. |
devices.[ ].watchers.[ ].notification.titlestring | A short description title that will be shown to the user as the push notification. |
devices.[ ].watchers.[ ].notification.bodystring | A more elaborative text that will provide additional information to the user. |
devices.[ ].watchers.[ ].datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
devices.[ ].watchers.[ ].historyarray optional | The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored. |
devices.[ ].watchers.[ ].history.[ ].sinceinteger | The timestamp when the state changed occurred. |
devices.[ ].watchers.[ ].history.[ ].idinteger | The identifier of the alarm state change. |
devices.[ ].watchers.[ ].history.[ ].alarmActiveboolean | Whenever the alarm is active or not. |
devices.[ ].watchers.[ ].history.[ ].messagesarray optional | The messages for that given alarm entry. |
devices.[ ].watchers.[ ].history.[ ].messages.[ ].timestampinteger | Timestamp of the message. |
devices.[ ].watchers.[ ].history.[ ].messages.[ ].idinteger | Unique identifier for the message. |
devices.[ ].watchers.[ ].history.[ ].messages.[ ].authorstring | The author of the message. |
devices.[ ].watchers.[ ].history.[ ].messages.[ ].messagestring | The content of the message. |
devices.[ ].watchers.[ ].history.[ ].statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
devices.[ ].watchers.[ ].history.[ ].state. #.propId integer | The identifier of the property |
devices.[ ].watchers.[ ].history.[ ].state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
devices.[ ].watchers.[ ].history.[ ].state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
devices.[ ].watchers.[ ].history.[ ].state. #.value optional | The value of the property |
watchersarray optional | List of all devices. However, the key used here is wrong but will not be changed due to backwards compatible reasons for now. Only returned if `fixTypo` is set to false and a `depth` greater than one is used. |
watchers.[ ].deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
watchers.[ ].watchersarray optional | List of all watchers. While an alarm configuration can be for multiple devices, the watcher at hand can be seen as the configuration for the given device. |
watchers.[ ].watchers.[ ].watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
watchers.[ ].watchers.[ ].stateobject optional | A state change for a given alarm. |
watchers.[ ].watchers.[ ].state.sinceinteger | The timestamp when the state changed occurred. |
watchers.[ ].watchers.[ ].state.idinteger | The identifier of the alarm state change. |
watchers.[ ].watchers.[ ].state.alarmActiveboolean | Whenever the alarm is active or not. |
watchers.[ ].watchers.[ ].state.messagesarray optional | The messages for that given alarm entry. |
watchers.[ ].watchers.[ ].state.messages.[ ].timestampinteger | Timestamp of the message. |
watchers.[ ].watchers.[ ].state.messages.[ ].idinteger | Unique identifier for the message. |
watchers.[ ].watchers.[ ].state.messages.[ ].authorstring | The author of the message. |
watchers.[ ].watchers.[ ].state.messages.[ ].messagestring | The content of the message. |
watchers.[ ].watchers.[ ].state.statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
watchers.[ ].watchers.[ ].state.state. #.propId integer | The identifier of the property |
watchers.[ ].watchers.[ ].state.state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
watchers.[ ].watchers.[ ].state.state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
watchers.[ ].watchers.[ ].state.state. #.value optional | The value of the property |
watchers.[ ].watchers.[ ].severityinteger optional | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
watchers.[ ].watchers.[ ].notificationobject optional | An optional object that contains further information for push notifications. |
watchers.[ ].watchers.[ ].notification.titlestring | A short description title that will be shown to the user as the push notification. |
watchers.[ ].watchers.[ ].notification.bodystring | A more elaborative text that will provide additional information to the user. |
watchers.[ ].watchers.[ ].datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
watchers.[ ].watchers.[ ].historyarray optional | The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored. |
watchers.[ ].watchers.[ ].history.[ ].sinceinteger | The timestamp when the state changed occurred. |
watchers.[ ].watchers.[ ].history.[ ].idinteger | The identifier of the alarm state change. |
watchers.[ ].watchers.[ ].history.[ ].alarmActiveboolean | Whenever the alarm is active or not. |
watchers.[ ].watchers.[ ].history.[ ].messagesarray optional | The messages for that given alarm entry. |
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].timestampinteger | Timestamp of the message. |
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].idinteger | Unique identifier for the message. |
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].authorstring | The author of the message. |
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].messagestring | The content of the message. |
watchers.[ ].watchers.[ ].history.[ ].statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
watchers.[ ].watchers.[ ].history.[ ].state. #.propId integer | The identifier of the property |
watchers.[ ].watchers.[ ].history.[ ].state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
watchers.[ ].watchers.[ ].history.[ ].state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
watchers.[ ].watchers.[ ].history.[ ].state. #.value optional | The value of the property |
List Alarm Status for Service Identifier
List all known alarm status for a given service identifier.
GET
/api/v1/alarms/status/:serviceIdentifier
Access
This endpoint requires read
permission for the resource alarm.status
.
URL Parameter
Name | Description |
---|---|
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
untranslatedboolean optional | Whenever to return the config as is or translate specific fields |
Response
Name | Description |
---|---|
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
watchersarray optional | List of all watchers. While an alarm configuration can be for multiple devices, the watcher at hand can be seen as the configuration for the given device. |
watchers.[ ].watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
watchers.[ ].stateobject optional | A state change for a given alarm. |
watchers.[ ].state.sinceinteger | The timestamp when the state changed occurred. |
watchers.[ ].state.idinteger | The identifier of the alarm state change. |
watchers.[ ].state.alarmActiveboolean | Whenever the alarm is active or not. |
watchers.[ ].state.messagesarray optional | The messages for that given alarm entry. |
watchers.[ ].state.messages.[ ].timestampinteger | Timestamp of the message. |
watchers.[ ].state.messages.[ ].idinteger | Unique identifier for the message. |
watchers.[ ].state.messages.[ ].authorstring | The author of the message. |
watchers.[ ].state.messages.[ ].messagestring | The content of the message. |
watchers.[ ].state.statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
watchers.[ ].state.state. #.propId integer | The identifier of the property |
watchers.[ ].state.state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
watchers.[ ].state.state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
watchers.[ ].state.state. #.value optional | The value of the property |
watchers.[ ].severityinteger optional | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
watchers.[ ].notificationobject optional | An optional object that contains further information for push notifications. |
watchers.[ ].notification.titlestring | A short description title that will be shown to the user as the push notification. |
watchers.[ ].notification.bodystring | A more elaborative text that will provide additional information to the user. |
watchers.[ ].datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
watchers.[ ].historyarray optional | The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored. |
watchers.[ ].history.[ ].sinceinteger | The timestamp when the state changed occurred. |
watchers.[ ].history.[ ].idinteger | The identifier of the alarm state change. |
watchers.[ ].history.[ ].alarmActiveboolean | Whenever the alarm is active or not. |
watchers.[ ].history.[ ].messagesarray optional | The messages for that given alarm entry. |
watchers.[ ].history.[ ].messages.[ ].timestampinteger | Timestamp of the message. |
watchers.[ ].history.[ ].messages.[ ].idinteger | Unique identifier for the message. |
watchers.[ ].history.[ ].messages.[ ].authorstring | The author of the message. |
watchers.[ ].history.[ ].messages.[ ].messagestring | The content of the message. |
watchers.[ ].history.[ ].statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
watchers.[ ].history.[ ].state. #.propId integer | The identifier of the property |
watchers.[ ].history.[ ].state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
watchers.[ ].history.[ ].state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
watchers.[ ].history.[ ].state. #.value optional | The value of the property |
List Alarm Status for Device Identifier
List all known alarm status for a given service identifier and device identifier.
GET
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier
Access
This endpoint requires read
permission for the resource alarm.status
.
URL Parameter
Name | Description |
---|---|
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
untranslatedboolean optional | Whenever to return the config as is or translate specific fields |
removeStateboolean optional | Setting this query parameter to true will remove the property status for the device at the time of the alarm from the response which will greatly reduce payload size. |
Response
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
stateobject optional | A state change for a given alarm. |
state.sinceinteger | The timestamp when the state changed occurred. |
state.idinteger | The identifier of the alarm state change. |
state.alarmActiveboolean | Whenever the alarm is active or not. |
state.messagesarray optional | The messages for that given alarm entry. |
state.messages.[ ].timestampinteger | Timestamp of the message. |
state.messages.[ ].idinteger | Unique identifier for the message. |
state.messages.[ ].authorstring | The author of the message. |
state.messages.[ ].messagestring | The content of the message. |
state.statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
state.state. #.propId integer | The identifier of the property |
state.state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
state.state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
state.state. #.value optional | The value of the property |
severityinteger optional | The severity of the alarm. The subscribe API can use this value to, for example, only subscribe to events with a severity less than two. A lower number means more severe, while a higher number means a minor incident. However, there is no fixed scale. |
notificationobject optional | An optional object that contains further information for push notifications. |
notification.titlestring | A short description title that will be shown to the user as the push notification. |
notification.bodystring | A more elaborative text that will provide additional information to the user. |
datadictionary optional | An object that allows key-value storage. The keys are strings while the values can be of any type. If present, this object will be returned in GET requests for the specific alarm configuration and can be used to store additional properties. |
historyarray optional | The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored. |
history.[ ].sinceinteger | The timestamp when the state changed occurred. |
history.[ ].idinteger | The identifier of the alarm state change. |
history.[ ].alarmActiveboolean | Whenever the alarm is active or not. |
history.[ ].messagesarray optional | The messages for that given alarm entry. |
history.[ ].messages.[ ].timestampinteger | Timestamp of the message. |
history.[ ].messages.[ ].idinteger | Unique identifier for the message. |
history.[ ].messages.[ ].authorstring | The author of the message. |
history.[ ].messages.[ ].messagestring | The content of the message. |
history.[ ].statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
history.[ ].state. #.propId integer | The identifier of the property |
history.[ ].state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
history.[ ].state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
history.[ ].state. #.value optional | The value of the property |
Get Alarm Status
Returns the status for a given triple of information regarding the service identifier, device identifier and the watcher identifier.
GET
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier
Access
This endpoint requires read
permission for the resource alarm.status
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
Query Parameter
Name | Description |
---|---|
depthinteger optional | Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for. |
Response
Name | Description |
---|---|
sinceinteger | The timestamp when the state changed occurred. |
idinteger | The identifier of the alarm state change. |
alarmActiveboolean | Whenever the alarm is active or not. |
messagesarray optional | The messages for that given alarm entry. |
messages.[ ].timestampinteger | Timestamp of the message. |
messages.[ ].idinteger | Unique identifier for the message. |
messages.[ ].authorstring | The author of the message. |
messages.[ ].messagestring | The content of the message. |
statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
state. #.propId integer | The identifier of the property |
state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
state. #.value optional | The value of the property |
Get Alarm Status
Returns the status for a given triple of information regarding the service identifier, device identifier and the watcher identifier.
GET
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/history
Access
This endpoint requires read
permission for the resource alarm.status
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
Response
Name | Description |
---|---|
sinceinteger | The timestamp when the state changed occurred. |
idinteger | The identifier of the alarm state change. |
alarmActiveboolean | Whenever the alarm is active or not. |
messagesarray optional | The messages for that given alarm entry. |
messages.[ ].timestampinteger | Timestamp of the message. |
messages.[ ].idinteger | Unique identifier for the message. |
messages.[ ].authorstring | The author of the message. |
messages.[ ].messagestring | The content of the message. |
statedictionary optional | The state when the change occurred. Only present when the config parameter storeState is set to true. |
state. #.propId integer | The identifier of the property |
state. #.tag string constant | A tag to differentiate between value and error properties Constant value: value |
state. #.type | The type of the property. |
Alternative 1string | The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM |
Alternative 2string | The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY |
state. #.value optional | The value of the property |
Delete Device Alarm Status
Deletes all known alarm status information for the given device.
DELETE
/api/v1/alarms/status/:deviceIdentifier
Access
This endpoint requires delete
permission for the resource alarm.status
.
URL Parameter
Name | Description |
---|---|
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
List Alarm Messages
Returns all alarm messages for a given alarm occurrence.
GET
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages
Access
This endpoint requires read
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
Response
Name | Description |
---|---|
timestampinteger | Timestamp of the message. |
idinteger | Unique identifier for the message. |
authorstring | The author of the message. |
messagestring | The content of the message. |
Create Alarm Message
Adds a new message to the given alarm occurrence.
POST
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages
Access
This endpoint requires create
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
Request Body
Name | Description |
---|---|
authorstring | The author of the message. |
messagestring | The content of the message. |
Response
Name | Description |
---|---|
messageIdentifierinteger | Unique identifier for the message. |
Delete all Alarm Messages
Deletes all messages for the given alarm occurrence.
DELETE
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages
Access
This endpoint requires delete
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
GET Alarm Messages
Returns a single alarm messages for a given alarm occurrence.
GET
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages/:messageIdentifier
Access
This endpoint requires read
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
messageIdentifierinteger | Unique identifier for the message. |
Response
Name | Description |
---|---|
timestampinteger | Timestamp of the message. |
idinteger | Unique identifier for the message. |
authorstring | The author of the message. |
messagestring | The content of the message. |
Update Message
Updates a given message. Both the author and the message can be updated.
PUT
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages/:messageIdentifier
Access
This endpoint requires update
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
messageIdentifierinteger | Unique identifier for the message. |
Request Body
Name | Description |
---|---|
authorstring optional | The author of the message. |
messagestring optional | The content of the message. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
Delete Alarm Messages
Deletes a single message identified by the message id.
DELETE
/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/:occurrenceIdentifier/messages/:messageIdentifier
Access
This endpoint requires delete
permission for the resource alarm.status.messages
.
URL Parameter
Name | Description |
---|---|
watcherIdentifierstring | The watcher identifier that identifies the alarm configuration. |
serviceIdentifierstring | The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties. |
deviceIdentifierstring | The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. |
occurrenceIdentifierinteger | A unique identifier for each instance of an active or inactive alarm. |
messageIdentifierinteger | Unique identifier for the message. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
Subscribe to Notifications
Subscribe to notifications based on certain filters.
POST
/api/v1/alarms/subscribe
Access
This endpoint requires update
permission for the resource alarm.subscribe
.
Query Parameter
Name | Description |
---|---|
langstring optional | A string as language code in the format xx or xx-XX where x can be any letter describing an actual language. |
Request Body
Name | Description |
---|---|
infostring | The main information required for the push notification to work. This can also be referred to as push token or something similar. |
consumerstring enum | The consumer of the info or token sent. Either `android` or `ios`. Possible values: android, ios |
minSeverityinteger optional | The minimum severity you want to receive notifications for. |
maxSeverityinteger optional | The maximum severity you want to receive notifications for. |
channelstring optional | When using multiple push services for either android or ios you can subscribe to a specific channel. |
deviceIdentifierarray string optional | Only send a notification when one of these devices encounters an alarm. |
serviceIdentifierarray string optional | Only send a notification when one of these services encounters an alarm. |
developerboolean optional | Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered. |
userstring optional | The user that belongs to the token. Only available up from version 4.10.5 |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
Test notifications
Triggers notifications for all subscriptions that are marked as developer.
POST
/api/v1/alarms/subscribe/test
Access
This endpoint requires create
permission for the resource alarm.subscribe
.
Query Parameter
Name | Description |
---|---|
severityinteger optional | The severity that will be used for the test notification. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
Unsubscribe from Notifications
Remove a currently registered notification pairing.
POST
/api/v1/alarms/unsubscribe
Access
This endpoint requires delete
permission for the resource alarm.subscribe
.
Request Body
Name | Description |
---|---|
infostring | The main information required for the push notification to work. This can also be referred to as push token or something similar. |
Response
This endpoint simply returns Status 204
to indicate a successful operation and to save bandwidth.
List Subscriptions
Returns a list of all known subscriptions.
GET
/api/v1/alarms/subscribe
Access
This endpoint requires read
permission for the resource alarm.subscribe
.
Response
Name | Description |
---|---|
infostring | The main information required for the push notification to work. This can also be referred to as push token or something similar. |
consumerstring enum | The consumer of the info or token sent. Either `android` or `ios`. Possible values: android, ios |
minSeverityinteger optional | The minimum severity you want to receive notifications for. |
maxSeverityinteger optional | The maximum severity you want to receive notifications for. |
channelstring optional | When using multiple push services for either android or ios you can subscribe to a specific channel. |
deviceIdentifierarray string optional | Only send a notification when one of these devices encounters an alarm. |
serviceIdentifierarray string optional | Only send a notification when one of these services encounters an alarm. |
developerboolean optional | Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered. |
userstring optional | The user that belongs to the token. Only available up from version 4.10.5 |
langarray optional | Object that contains language information for the given user Default: [] |
lang.[ ].codestring | |
lang.[ ].regionstring optional | |
lang.[ ].qualitynumber |
Get Subscription
Returns a single subscription based on the token.
GET
/api/v1/alarms/subscribe/:info
Access
This endpoint requires read
permission for the resource alarm.subscribe
.
URL Parameter
Name | Description |
---|---|
infostring | The main information required for the push notification to work. This can also be referred to as push token or something similar. |
Response
Name | Description |
---|---|
infostring | The main information required for the push notification to work. This can also be referred to as push token or something similar. |
consumerstring enum | The consumer of the info or token sent. Either `android` or `ios`. Possible values: android, ios |
minSeverityinteger optional | The minimum severity you want to receive notifications for. |
maxSeverityinteger optional | The maximum severity you want to receive notifications for. |
channelstring optional | When using multiple push services for either android or ios you can subscribe to a specific channel. |
deviceIdentifierarray string optional | Only send a notification when one of these devices encounters an alarm. |
serviceIdentifierarray string optional | Only send a notification when one of these services encounters an alarm. |
developerboolean optional | Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered. |
userstring optional | The user that belongs to the token. Only available up from version 4.10.5 |
langarray optional | Object that contains language information for the given user Default: [] |
lang.[ ].codestring | |
lang.[ ].regionstring optional | |
lang.[ ].qualitynumber |