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
• Status
• Push Notifications

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.

{
  "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.

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

{
  "type": "DURATION",
  "operatorA": {
    "type": "EQUAL",
    "operatorA": {
      "property": "maintenance"
    },
    "operatorB": 1
  },
  "operatorB": 30000
}

will check if the expression

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:

{
  "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.

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.

ALARM_CONFIG_ADD

ALARM_CONFIG_UPDATE

ALARM_CONFIG_DELETE

ALARM_STATUS_ACTIVE

ALARM_STATUS_INACTIVE

ALARM_STATUS_DELETE_DEVICE

An event that is sent over the websocket when a config has been added. This event requires read access to the resource alarm.config.

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
Alternative 3LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpression	The accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification optional
Alternative 1object	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.
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.

CompareExpression

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.

LogicExpression

Name	Description
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 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality

AccumulateExpression

Name	Description
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 1LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB integer	The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement.

API

Endpoints

POST

Create Configuration

GET

List Configuration

GET

Get Configuration

PUT

Update Configuration

DEL

Delete Configuration

GET

List Alarm Status

GET

List Alarm Status for Service Identifier

GET

List Alarm Status for Device Identifier

GET

Get Alarm Status

GET

Get Alarm Status

DEL

Delete Device Alarm Status

GET

List Alarm Messages

POST

Create Alarm Message

DEL

Delete all Alarm Messages

GET

GET Alarm Messages

PUT

Update Message

DEL

Delete Alarm Messages

POST

Subscribe to Notifications

POST

Test notifications

POST

Unsubscribe from Notifications

GET

List Subscriptions

GET

Get Subscription

Create Configuration

Creates a new configuration.

POST

/api/v1/alarms/config

Access

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

Query Parameter

Name	Description
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
Alternative 3LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpression	The accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification optional
Alternative 1object	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.
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.

CompareExpression

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.

LogicExpression

Name	Description
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 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality

AccumulateExpression

Name	Description
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 1LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB integer	The duration in ms where the `operatorA` has to equal true in order to result in a true duration statement.

Response

Name	Description
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

Name	Description
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
Alternative 3LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpression	The accumulate operation can be used to check if a certain boolean value is true for a given duration.
settings.notification optional
Alternative 1object	An 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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.

CompareExpression

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.

LogicExpression

Name	Description
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 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality

AccumulateExpression

Name	Description
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 1LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
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

Name	Description
watcherIdentifier string	The watcher identifier that identifies the alarm configuration.

Query Parameter

Name	Description
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
Alternative 3LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpression	The accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification optional
Alternative 1object	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.
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.

CompareExpression

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.

LogicExpression

Name	Description
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 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality

AccumulateExpression

Name	Description
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 1LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
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

Name	Description
watcherIdentifier string	The watcher identifier that identifies the alarm configuration.

Request Body

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
Alternative 3LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 4AccumulateExpression	The accumulate operation can be used to check if a certain boolean value is true for a given duration.
notification optional
Alternative 1object	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.
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

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 4number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 5boolean	A simple boolean value you want to use for comparison or computation in the given expression.

CompareExpression

Name	Description
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 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1ComputeExpression	To combine values, use the compute expression. This value takes two values as input and generates a new value depending on the compute operation chosen. This will be most useful to update numbers. All javascript type casting rules apply. For example, adding two boolean values will result in either zero, one or two.
Alternative 2PropertyWrapper	Object that wraps property information.
Alternative 3SpecialWrapper	A special operator which will result in dynamic but simple value. For example the day of the week will result to one if current day is a monday. Time values are referenced against the UTC timestamp!
Alternative 4MetaWrapper
Alternative 5string	A simple string value you want to use for comparison or computation in the given expression.
Alternative 6number	A simple number value you want to use for comparison or computation in the given expression.
Alternative 7boolean	A simple boolean value you want to use for comparison or computation in the given expression.

LogicExpression

Name	Description
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 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
operatorB	The second operator that will be used on the right side of the operand.
Alternative 1	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality

AccumulateExpression

Name	Description
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 1LogicExpression	An expression that compares to boolean values and returns a single boolean datum based on the operators and the compare operation chosen.
Alternative 2CompareExpression	The compare operation can be used to compare two values and return a boolean datum. It does not use the strict equality check. For more info on equality please check out the MDN documentation here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
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

Name	Description
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

Name	Description
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

Name	Description
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
devices.[ ].watchers.[ ].state.state. #.value optional	The value of the property
devices.[ ].watchers.[ ].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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
devices.[ ].watchers.[ ].history.[ ].state. #.value optional	The value of the property
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
watchers.[ ].watchers.[ ].state.state. #.value optional	The value of the property
watchers.[ ].watchers.[ ].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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
watchers.[ ].watchers.[ ].history.[ ].state. #.value optional	The value of the property

List Alarm Status for Service Identifier

List all known alarm status for a given service identifier.

GET

/api/v1/alarms/status/:serviceIdentifier

Access

This endpoint requires read permission for the resource alarm.status.

URL Parameter

Name	Description
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

Name	Description
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

Name	Description
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
watchers.[ ].state.state. #.value optional	The value of the property
watchers.[ ].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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
watchers.[ ].history.[ ].state. #.value optional	The value of the property

List Alarm Status for Device Identifier

List all known alarm status for a given service identifier and device identifier.

GET

/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier

Access

This endpoint requires read permission for the resource alarm.status.

URL Parameter

Name	Description
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

Name	Description
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

Name	Description
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
state.state. #.value optional	The value of the property
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
history.[ ].state. #.value optional	The value of the property

Get Alarm Status

Returns the status for a given triple of information regarding the service identifier, device identifier and the watcher identifier.

GET

/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier

Access

This endpoint requires read permission for the resource alarm.status.

URL Parameter

Name	Description
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

Name	Description
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

Name	Description
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
state. #.value optional	The value of the property

Get Alarm Status

Returns the status for a given triple of information regarding the service identifier, device identifier and the watcher identifier.

GET

/api/v1/alarms/status/:serviceIdentifier/:deviceIdentifier/:watcherIdentifier/history

Access

This endpoint requires read permission for the resource alarm.status.

URL Parameter

Name	Description
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

Name	Description
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 1string	The type of the property. Possible values: INT64, INT32, INT16, INT8, UINT64, UINT32, UINT16, UINT8, FLOAT, FLOAT64, DATETIME, STRING, BOOL, UUID, BIN, BIN_STREAM, STRING_STREAM
Alternative 2string	The type of the property, specifically arrays Possible values: INT64_ARRAY, INT32_ARRAY, INT16_ARRAY, INT8_ARRAY, UINT64_ARRAY, UINT32_ARRAY, UINT16_ARRAY, UINT8_ARRAY, BOOL_ARRAY, UUID_ARRAY, FLOAT64_ARRAY, FLOAT_ARRAY, DATETIME_ARRAY, BIN_ARRAY, STRING_ARRAY
state. #.value optional	The value of the property

Delete Device Alarm Status

Deletes all known alarm status information for the given device.

DELETE

/api/v1/alarms/status/:deviceIdentifier

Access

This endpoint requires delete permission for the resource alarm.status.

URL Parameter

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
author string	The author of the message.
message string	The content of the message.

Response

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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

Name	Description
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