Skip to content

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.

NameDescription
type
stringconstant
Constant value: ALARM_CONFIG_ADD
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
severity
integer
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 1ComputeExpressionTo 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 2CompareExpressionThe 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 3LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpressionThe accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification
optional
Alternative 1objectAn optional object that contains further information for push notifications.
notification.title
string
A short description title that will be shown to the user as the push notification.
notification.body
string
A more elaborative text that will provide additional information to the user.
Alternative 2object
notification.__i18nSupport
booleanoptional
A required key for easier parsing when actually using translations.
Default: true
notification.translations
dictionary
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.
data
dictionaryoptional
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.
whitelist
arraystringoptional
Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
blacklist
arraystringoptional
Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
serviceIdentifier
stringoptional
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

ComputeExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA simple boolean value you want to use for comparison or computation in the given expression.
CompareExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA simple boolean value you want to use for comparison or computation in the given expression.
LogicExpression
NameDescription
type
stringenum
Possible values: AND, NAND, OR, NOR, XOR, NXOR
operatorA
The first operator that will be used on the left side of the operand.
Alternative 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
AccumulateExpression
NameDescription
type
stringconstant
Constant value: DURATION
operatorA
The operator that has to evaluate to true for the given amount of milliseconds in the second operator.
Alternative 1LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
integer
The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement.

API

Create Configuration

Creates a new configuration.

POST
/api/v1/alarms/config

Access

This endpoint requires create permission for the resource alarm.config.

Query Parameter

NameDescription
force
booleanoptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.

Request Body

NameDescription
severity
integer
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 1ComputeExpressionTo 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 2CompareExpressionThe 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 3LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpressionThe accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification
optional
Alternative 1objectAn optional object that contains further information for push notifications.
notification.title
string
A short description title that will be shown to the user as the push notification.
notification.body
string
A more elaborative text that will provide additional information to the user.
Alternative 2object
notification.__i18nSupport
booleanoptional
A required key for easier parsing when actually using translations.
Default: true
notification.translations
dictionary
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.
data
dictionaryoptional
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.
whitelist
arraystringoptional
Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
blacklist
arraystringoptional
Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
serviceIdentifier
stringoptional
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

ComputeExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA simple boolean value you want to use for comparison or computation in the given expression.
CompareExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA simple boolean value you want to use for comparison or computation in the given expression.
LogicExpression
NameDescription
type
stringenum
Possible values: AND, NAND, OR, NOR, XOR, NXOR
operatorA
The first operator that will be used on the left side of the operand.
Alternative 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
AccumulateExpression
NameDescription
type
stringconstant
Constant value: DURATION
operatorA
The operator that has to evaluate to true for the given amount of milliseconds in the second operator.
Alternative 1LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
integer
The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement.

Response

NameDescription
watcherIdentifier
string
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

NameDescription
depth
integeroptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated
booleanoptional
Whenever to return the config as is or translate specific fields

Response

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
settings
objectoptional
The configuration for the watcher. Returned when the `depth` query parameter is set high enough.
settings.severity
integer
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 1ComputeExpressionTo 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 2CompareExpressionThe 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 3LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpressionThe accumulate operation can be used to check if a certain boolean value is true for a given duration.
settings.notification
optional
Alternative 1objectAn optional object that contains further information for push notifications.
settings.notification.title
string
A short description title that will be shown to the user as the push notification.
settings.notification.body
string
A more elaborative text that will provide additional information to the user.
Alternative 2object
settings.notification.__i18nSupport
booleanoptional
A required key for easier parsing when actually using translations.
Default: true
settings.notification.translations
dictionary
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.data
dictionaryoptional
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.whitelist
arraystringoptional
Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
settings.blacklist
arraystringoptional
Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
settings.serviceIdentifier
stringoptional
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

ComputeExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA simple boolean value you want to use for comparison or computation in the given expression.
CompareExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA simple boolean value you want to use for comparison or computation in the given expression.
LogicExpression
NameDescription
type
stringenum
Possible values: AND, NAND, OR, NOR, XOR, NXOR
operatorA
The first operator that will be used on the left side of the operand.
Alternative 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
AccumulateExpression
NameDescription
type
stringconstant
Constant value: DURATION
operatorA
The operator that has to evaluate to true for the given amount of milliseconds in the second operator.
Alternative 1LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
integer
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.

Query Parameter

NameDescription
depth
integeroptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated
booleanoptional
Whenever to return the config as is or translate specific fields

Response

NameDescription
severity
integer
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 1ComputeExpressionTo 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 2CompareExpressionThe 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 3LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpressionThe accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification
optional
Alternative 1objectAn optional object that contains further information for push notifications.
notification.title
string
A short description title that will be shown to the user as the push notification.
notification.body
string
A more elaborative text that will provide additional information to the user.
Alternative 2object
notification.__i18nSupport
booleanoptional
A required key for easier parsing when actually using translations.
Default: true
notification.translations
dictionary
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.
data
dictionaryoptional
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.
whitelist
arraystringoptional
Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
blacklist
arraystringoptional
Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
serviceIdentifier
stringoptional
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

ComputeExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA simple boolean value you want to use for comparison or computation in the given expression.
CompareExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA simple boolean value you want to use for comparison or computation in the given expression.
LogicExpression
NameDescription
type
stringenum
Possible values: AND, NAND, OR, NOR, XOR, NXOR
operatorA
The first operator that will be used on the left side of the operand.
Alternative 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
AccumulateExpression
NameDescription
type
stringconstant
Constant value: DURATION
operatorA
The operator that has to evaluate to true for the given amount of milliseconds in the second operator.
Alternative 1LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
integer
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.

Request Body

NameDescription
severity
integeroptional
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
optional
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 1ComputeExpressionTo 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 2CompareExpressionThe 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 3LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpressionThe accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification
optional
Alternative 1objectAn optional object that contains further information for push notifications.
notification.title
string
A short description title that will be shown to the user as the push notification.
notification.body
string
A more elaborative text that will provide additional information to the user.
Alternative 2object
notification.__i18nSupport
booleanoptional
A required key for easier parsing when actually using translations.
Default: true
notification.translations
dictionary
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.
data
dictionaryoptional
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.
whitelist
arraystringoptional
Devices to apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
blacklist
arraystringoptional
Devices to not apply the alarm configuration to. Only the `blacklist` or the `whitelist` can be present at a time.
serviceIdentifier
stringoptional
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

ComputeExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 4numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 5booleanA simple boolean value you want to use for comparison or computation in the given expression.
CompareExpression
NameDescription
type
stringenum
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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA 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 1ComputeExpressionTo 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 2PropertyWrapperObject that wraps property information.
Alternative 3SpecialWrapperA 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 5stringA simple string value you want to use for comparison or computation in the given expression.
Alternative 6numberA simple number value you want to use for comparison or computation in the given expression.
Alternative 7booleanA simple boolean value you want to use for comparison or computation in the given expression.
LogicExpression
NameDescription
type
stringenum
Possible values: AND, NAND, OR, NOR, XOR, NXOR
operatorA
The first operator that will be used on the left side of the operand.
Alternative 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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 1An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
AccumulateExpression
NameDescription
type
stringconstant
Constant value: DURATION
operatorA
The operator that has to evaluate to true for the given amount of milliseconds in the second operator.
Alternative 1LogicExpressionAn expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpressionThe 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
integer
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

NameDescription
watcherIdentifier
string
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

NameDescription
depth
integeroptional
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.
fixTypo
booleanoptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated
booleanoptional
Whenever to return the config as is or translate specific fields
removeText
booleanoptional
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.
removeState
booleanoptional
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.
from
numberoptional
UTC timestamp in milliseconds. Only alarm status changes that happened after this timestamp will be included in the response.
to
numberoptional
UTC timestamp in milliseconds. Only alarm status changes that happened before this timestamp will be included in the response.

Response

NameDescription
serviceIdentifier
string
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.
devices
arrayoptional
List of all devices, only returned when the query parameter `fixTypo` is set to true and a `depth` greater than one is used.
devices.[ ].deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
devices.[ ].watchers
arrayoptional
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.[ ].watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
devices.[ ].watchers.[ ].state
objectoptional
A state change for a given alarm.
devices.[ ].watchers.[ ].state.since
integer
The timestamp when the state changed occurred.
devices.[ ].watchers.[ ].state.id
integer
The identifier of the alarm state change.
devices.[ ].watchers.[ ].state.alarmActive
boolean
Whenever the alarm is active or not.
devices.[ ].watchers.[ ].state.messages
arrayoptional
The messages for that given alarm entry.
devices.[ ].watchers.[ ].state.messages.[ ].timestamp
integer
Timestamp of the message.
devices.[ ].watchers.[ ].state.messages.[ ].id
integer
Unique identifier for the message.
devices.[ ].watchers.[ ].state.messages.[ ].author
string
The author of the message.
devices.[ ].watchers.[ ].state.messages.[ ].message
string
The content of the message.
devices.[ ].watchers.[ ].state.state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
devices.[ ].watchers.[ ].state.state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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.[ ].severity
integeroptional
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.[ ].notification
objectoptional
An optional object that contains further information for push notifications.
devices.[ ].watchers.[ ].notification.title
string
A short description title that will be shown to the user as the push notification.
devices.[ ].watchers.[ ].notification.body
string
A more elaborative text that will provide additional information to the user.
devices.[ ].watchers.[ ].data
dictionaryoptional
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.[ ].history
arrayoptional
The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored.
devices.[ ].watchers.[ ].history.[ ].since
integer
The timestamp when the state changed occurred.
devices.[ ].watchers.[ ].history.[ ].id
integer
The identifier of the alarm state change.
devices.[ ].watchers.[ ].history.[ ].alarmActive
boolean
Whenever the alarm is active or not.
devices.[ ].watchers.[ ].history.[ ].messages
arrayoptional
The messages for that given alarm entry.
devices.[ ].watchers.[ ].history.[ ].messages.[ ].timestamp
integer
Timestamp of the message.
devices.[ ].watchers.[ ].history.[ ].messages.[ ].id
integer
Unique identifier for the message.
devices.[ ].watchers.[ ].history.[ ].messages.[ ].author
string
The author of the message.
devices.[ ].watchers.[ ].history.[ ].messages.[ ].message
string
The content of the message.
devices.[ ].watchers.[ ].history.[ ].state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
devices.[ ].watchers.[ ].history.[ ].state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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
watchers
arrayoptional
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.[ ].deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
watchers.[ ].watchers
arrayoptional
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.[ ].watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
watchers.[ ].watchers.[ ].state
objectoptional
A state change for a given alarm.
watchers.[ ].watchers.[ ].state.since
integer
The timestamp when the state changed occurred.
watchers.[ ].watchers.[ ].state.id
integer
The identifier of the alarm state change.
watchers.[ ].watchers.[ ].state.alarmActive
boolean
Whenever the alarm is active or not.
watchers.[ ].watchers.[ ].state.messages
arrayoptional
The messages for that given alarm entry.
watchers.[ ].watchers.[ ].state.messages.[ ].timestamp
integer
Timestamp of the message.
watchers.[ ].watchers.[ ].state.messages.[ ].id
integer
Unique identifier for the message.
watchers.[ ].watchers.[ ].state.messages.[ ].author
string
The author of the message.
watchers.[ ].watchers.[ ].state.messages.[ ].message
string
The content of the message.
watchers.[ ].watchers.[ ].state.state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
watchers.[ ].watchers.[ ].state.state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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.[ ].severity
integeroptional
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.[ ].notification
objectoptional
An optional object that contains further information for push notifications.
watchers.[ ].watchers.[ ].notification.title
string
A short description title that will be shown to the user as the push notification.
watchers.[ ].watchers.[ ].notification.body
string
A more elaborative text that will provide additional information to the user.
watchers.[ ].watchers.[ ].data
dictionaryoptional
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.[ ].history
arrayoptional
The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored.
watchers.[ ].watchers.[ ].history.[ ].since
integer
The timestamp when the state changed occurred.
watchers.[ ].watchers.[ ].history.[ ].id
integer
The identifier of the alarm state change.
watchers.[ ].watchers.[ ].history.[ ].alarmActive
boolean
Whenever the alarm is active or not.
watchers.[ ].watchers.[ ].history.[ ].messages
arrayoptional
The messages for that given alarm entry.
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].timestamp
integer
Timestamp of the message.
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].id
integer
Unique identifier for the message.
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].author
string
The author of the message.
watchers.[ ].watchers.[ ].history.[ ].messages.[ ].message
string
The content of the message.
watchers.[ ].watchers.[ ].history.[ ].state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
watchers.[ ].watchers.[ ].history.[ ].state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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

NameDescription
serviceIdentifier
string
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

NameDescription
depth
integeroptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated
booleanoptional
Whenever to return the config as is or translate specific fields

Response

NameDescription
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
watchers
arrayoptional
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.[ ].watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
watchers.[ ].state
objectoptional
A state change for a given alarm.
watchers.[ ].state.since
integer
The timestamp when the state changed occurred.
watchers.[ ].state.id
integer
The identifier of the alarm state change.
watchers.[ ].state.alarmActive
boolean
Whenever the alarm is active or not.
watchers.[ ].state.messages
arrayoptional
The messages for that given alarm entry.
watchers.[ ].state.messages.[ ].timestamp
integer
Timestamp of the message.
watchers.[ ].state.messages.[ ].id
integer
Unique identifier for the message.
watchers.[ ].state.messages.[ ].author
string
The author of the message.
watchers.[ ].state.messages.[ ].message
string
The content of the message.
watchers.[ ].state.state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
watchers.[ ].state.state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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.[ ].severity
integeroptional
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.[ ].notification
objectoptional
An optional object that contains further information for push notifications.
watchers.[ ].notification.title
string
A short description title that will be shown to the user as the push notification.
watchers.[ ].notification.body
string
A more elaborative text that will provide additional information to the user.
watchers.[ ].data
dictionaryoptional
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.[ ].history
arrayoptional
The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored.
watchers.[ ].history.[ ].since
integer
The timestamp when the state changed occurred.
watchers.[ ].history.[ ].id
integer
The identifier of the alarm state change.
watchers.[ ].history.[ ].alarmActive
boolean
Whenever the alarm is active or not.
watchers.[ ].history.[ ].messages
arrayoptional
The messages for that given alarm entry.
watchers.[ ].history.[ ].messages.[ ].timestamp
integer
Timestamp of the message.
watchers.[ ].history.[ ].messages.[ ].id
integer
Unique identifier for the message.
watchers.[ ].history.[ ].messages.[ ].author
string
The author of the message.
watchers.[ ].history.[ ].messages.[ ].message
string
The content of the message.
watchers.[ ].history.[ ].state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
watchers.[ ].history.[ ].state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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

NameDescription
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Query Parameter

NameDescription
depth
integeroptional
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.
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.
untranslated
booleanoptional
Whenever to return the config as is or translate specific fields
removeState
booleanoptional
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
state
objectoptional
A state change for a given alarm.
state.since
integer
The timestamp when the state changed occurred.
state.id
integer
The identifier of the alarm state change.
state.alarmActive
boolean
Whenever the alarm is active or not.
state.messages
arrayoptional
The messages for that given alarm entry.
state.messages.[ ].timestamp
integer
Timestamp of the message.
state.messages.[ ].id
integer
Unique identifier for the message.
state.messages.[ ].author
string
The author of the message.
state.messages.[ ].message
string
The content of the message.
state.state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
state.state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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
severity
integeroptional
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.
notification
objectoptional
An optional object that contains further information for push notifications.
notification.title
string
A short description title that will be shown to the user as the push notification.
notification.body
string
A more elaborative text that will provide additional information to the user.
data
dictionaryoptional
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.
history
arrayoptional
The history of all known occurrences for this specific alarm. A maximum of one hundred entries will be stored.
history.[ ].since
integer
The timestamp when the state changed occurred.
history.[ ].id
integer
The identifier of the alarm state change.
history.[ ].alarmActive
boolean
Whenever the alarm is active or not.
history.[ ].messages
arrayoptional
The messages for that given alarm entry.
history.[ ].messages.[ ].timestamp
integer
Timestamp of the message.
history.[ ].messages.[ ].id
integer
Unique identifier for the message.
history.[ ].messages.[ ].author
string
The author of the message.
history.[ ].messages.[ ].message
string
The content of the message.
history.[ ].state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
history.[ ].state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Query Parameter

NameDescription
depth
integeroptional
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

NameDescription
since
integer
The timestamp when the state changed occurred.
id
integer
The identifier of the alarm state change.
alarmActive
boolean
Whenever the alarm is active or not.
messages
arrayoptional
The messages for that given alarm entry.
messages.[ ].timestamp
integer
Timestamp of the message.
messages.[ ].id
integer
Unique identifier for the message.
messages.[ ].author
string
The author of the message.
messages.[ ].message
string
The content of the message.
state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

NameDescription
since
integer
The timestamp when the state changed occurred.
id
integer
The identifier of the alarm state change.
alarmActive
boolean
Whenever the alarm is active or not.
messages
arrayoptional
The messages for that given alarm entry.
messages.[ ].timestamp
integer
Timestamp of the message.
messages.[ ].id
integer
Unique identifier for the message.
messages.[ ].author
string
The author of the message.
messages.[ ].message
string
The content of the message.
state
dictionaryoptional
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
stringconstant
A tag to differentiate between value and error properties
Constant value: value
state.
#.type
The type of the property.
Alternative 1stringThe 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 2stringThe 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

NameDescription
deviceIdentifier
string
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
A unique identifier for each instance of an active or inactive alarm.

Response

NameDescription
timestamp
integer
Timestamp of the message.
id
integer
Unique identifier for the message.
author
string
The author of the message.
message
string
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
A unique identifier for each instance of an active or inactive alarm.

Request Body

NameDescription
author
string
The author of the message.
message
string
The content of the message.

Response

NameDescription
messageIdentifier
integer
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
A unique identifier for each instance of an active or inactive alarm.
messageIdentifier
integer
Unique identifier for the message.

Response

NameDescription
timestamp
integer
Timestamp of the message.
id
integer
Unique identifier for the message.
author
string
The author of the message.
message
string
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
A unique identifier for each instance of an active or inactive alarm.
messageIdentifier
integer
Unique identifier for the message.

Request Body

NameDescription
author
stringoptional
The author of the message.
message
stringoptional
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

NameDescription
watcherIdentifier
string
The watcher identifier that identifies the alarm configuration.
serviceIdentifier
string
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.
deviceIdentifier
string
The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
occurrenceIdentifier
integer
A unique identifier for each instance of an active or inactive alarm.
messageIdentifier
integer
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

NameDescription
lang
stringoptional
A string as language code in the format xx or xx-XX where x can be any letter describing an actual language.

Request Body

NameDescription
info
string
The main information required for the push notification to work. This can also be referred to as push token or something similar.
consumer
stringenum
The consumer of the info or token sent. Either `android` or `ios`.
Possible values: android, ios
minSeverity
integeroptional
The minimum severity you want to receive notifications for.
maxSeverity
integeroptional
The maximum severity you want to receive notifications for.
channel
stringoptional
When using multiple push services for either android or ios you can subscribe to a specific channel.
deviceIdentifier
arraystringoptional
Only send a notification when one of these devices encounters an alarm.
serviceIdentifier
arraystringoptional
Only send a notification when one of these services encounters an alarm.
developer
booleanoptional
Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered.
user
stringoptional
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

NameDescription
severity
integeroptional
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

NameDescription
info
string
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

NameDescription
info
string
The main information required for the push notification to work. This can also be referred to as push token or something similar.
consumer
stringenum
The consumer of the info or token sent. Either `android` or `ios`.
Possible values: android, ios
minSeverity
integeroptional
The minimum severity you want to receive notifications for.
maxSeverity
integeroptional
The maximum severity you want to receive notifications for.
channel
stringoptional
When using multiple push services for either android or ios you can subscribe to a specific channel.
deviceIdentifier
arraystringoptional
Only send a notification when one of these devices encounters an alarm.
serviceIdentifier
arraystringoptional
Only send a notification when one of these services encounters an alarm.
developer
booleanoptional
Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered.
user
stringoptional
The user that belongs to the token. Only available up from version 4.10.5
lang
arrayoptional
Object that contains language information for the given user
Default: []
lang.[ ].code
string
lang.[ ].region
stringoptional
lang.[ ].quality
number

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

NameDescription
info
string
The main information required for the push notification to work. This can also be referred to as push token or something similar.

Response

NameDescription
info
string
The main information required for the push notification to work. This can also be referred to as push token or something similar.
consumer
stringenum
The consumer of the info or token sent. Either `android` or `ios`.
Possible values: android, ios
minSeverity
integeroptional
The minimum severity you want to receive notifications for.
maxSeverity
integeroptional
The maximum severity you want to receive notifications for.
channel
stringoptional
When using multiple push services for either android or ios you can subscribe to a specific channel.
deviceIdentifier
arraystringoptional
Only send a notification when one of these devices encounters an alarm.
serviceIdentifier
arraystringoptional
Only send a notification when one of these services encounters an alarm.
developer
booleanoptional
Whenever the token is associated with a developer. When set to true, this subscription will also receive test push notifications once they are triggered.
user
stringoptional
The user that belongs to the token. Only available up from version 4.10.5
lang
arrayoptional
Object that contains language information for the given user
Default: []
lang.[ ].code
string
lang.[ ].region
stringoptional
lang.[ ].quality
number