For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/alarms/instances

• Request: GET /v1/users/{user}/alarms/instances
• Operation: ListAlarmInstances
• Operation ID: Alarm_ListInstances
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/users/{user}/alarms/instances

• Request: POST /v1/users/{user}/alarms/instances
• Operation: CreateAlarmInstance
• Operation ID: Alarm_CreateInstance
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
alarm	object	yes
alarm.rule	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
annotation	string	no	Maximum length: 512
asset_group	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
asset_type	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
evaluation	object	yes
evaluation.last_completed	number	no
evaluation.last_values	object	no
evaluation.total_duration	number	no
instance	string	yes	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
name	string	yes	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
origin	object	yes
origin.id	string	yes	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
origin.name	string	yes	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
origin.source	string	yes	One of: device, user
reactivation	object	no
reactivation.timespan	object	no
reactivation.timespan.magnitude	string	no	One of: second, minute, hour, day, week, month, year
reactivation.timespan.value	number	no	Minimum: 0
reactivation.type	string	no	One of: none, timespan
severity	number	yes	Range: 0 to 4
state	number	yes	Range: 0 to 4

Example request (skeleton generated from the schema: required fields only, neutral values)

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "instance": "",
  "alarm": {},
  "name": "",
  "state": 0,
  "severity": 0,
  "origin": {
    "source": "device",
    "id": "",
    "name": ""
  },
  "evaluation": {}
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/users/{user}/alarms/instances/stats

• Request: GET /v1/users/{user}/alarms/instances/stats
• Operation: ReadAlarmInstanceStats
• Operation ID: Alarm_ReadInstanceStats
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/users/{user}/alarms/instances/{instance}

• Request: GET /v1/users/{user}/alarms/instances/
• Operation: ReadAlarmInstanceConfig
• Operation ID: Alarm_ReadInstanceConfig
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
instance	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances/YOUR_INSTANCE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

PUT /v1/users/{user}/alarms/instances/{instance}

• Request: PUT /v1/users/{user}/alarms/instances/
• Operation: UpdateAlarmInstance
• Operation ID: Alarm_UpdateInstance
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
instance	path	string	yes

Request body (application/json, required)

Mostly used to change the state of an alarm instance: 0 none, 1 activated, 2 acknowledged, 3 latched, 4 shelved, 5 cleared (final). 'reactivation' sets when an acknowledged, shelved or latched alarm becomes active again if the condition persists.

Field	Type	Required	Constraints	Description
annotation	string	no	Maximum length: 512
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
reactivation	object	no
reactivation.timespan	object	no
reactivation.timespan.magnitude	string	no	One of: second, minute, hour, day, week, month, year
reactivation.timespan.value	number	no	Minimum: 0
reactivation.type	string	no	One of: none, timespan
state	number	no	Range: 0 to 6

Example request: Acknowledge

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances/YOUR_INSTANCE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "annotation": "Technician on the way",
  "state": 2
}'

Example body: Clear

{
  "annotation": "Fan replaced",
  "state": 5
}

Example body: Shelve for 4 hours

{
  "annotation": "Planned maintenance",
  "reactivation": {
    "timespan": {
      "magnitude": "hour",
      "value": 4
    },
    "type": "timespan"
  },
  "state": 4
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

DELETE /v1/users/{user}/alarms/instances/{instance}

• Request: DELETE /v1/users/{user}/alarms/instances/
• Operation: DeleteAlarmInstance
• Operation ID: Alarm_DeleteInstance
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
instance	path	string	yes

Example request

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances/YOUR_INSTANCE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

PUT /v1/users/{user}/alarms/instances/{instance}/projects

• Request: PUT /v1/users/{user}/alarms/instances/{instance}/projects
• Operation: UpdateAlarmInstanceProjects
• Operation ID: Alarm_UpdateInstanceProjects
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
instance	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
(body)	array of string	no		Projects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/instances/YOUR_INSTANCE/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/users/{user}/alarms/rules

• Request: GET /v1/users/{user}/alarms/rules
• Operation: ListAlarmRules
• Operation ID: Alarm_ListRules
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200)

[
  {
    "created": 1792263090787,
    "description": "Mean temperature above 30 for 3 checks in a row, per device",
    "enabled": true,
    "modified": 1792263090787,
    "name": "Greenhouse too hot",
    "rule": "greenhouse_hot"
  },
  {
    "created": 1792263090787,
    "description": "Any device of the smart_meter product disconnected",
    "enabled": true,
    "modified": 1792263090787,
    "name": "Meter offline",
    "rule": "meter_offline"
  },
  {
    "created": 1792263090787,
    "description": "Hourly max depth of each well above its own limit: the 'limits' property of the device, or of its asset type, asset group or product when the device has none",
    "enabled": true,
    "modified": 1792263090787,
    "name": "Water table too deep",
    "rule": "well_too_deep"
  },
  {
    "created": 1792263090787,
    "description": "Battery level reported in the 'battery' property below 15%, devices of the 'field_sensors' group",
    "enabled": true,
    "modified": 1792263090787,
    "name": "Low battery",
    "rule": "low_battery"
  }
]

POST /v1/users/{user}/alarms/rules

• Request: POST /v1/users/{user}/alarms/rules
• Operation: CreateAlarmRule
• Operation ID: Alarm_CreateRule
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes

Request body (application/json, required)

An alarm rule checks its data sources every check_interval and raises one alarm instance per device that meets the activation conditions. Sources: 'bucket' (bucket data, optionally aggregated and grouped by device), 'device_property' (a device property, resolved with type / group / product inheritance) and 'device_status' (connection.active, connection.ts). Sources can be narrowed with project, product, asset_type, asset_group or device. Conditions read '<source name>.<field>' and compare it with above, below, equal, not_equal (value), inside, outside (min, max), present or absent; a comparison on a field the device does not have is false (a bucket source with several mapping fields keeps a device that only has some of them), so 'a above 5 or b above 5' works on devices without b, and a device is skipped only when it has none of the fields the conditions read or misses a whole source (unless present / absent are used); values are strings, and can be expressions over other sources of the same device (e.g. 'limits.value.max_depth_m', a per-device threshold from a device_property source). device_property fields are paths in the property document: 'value.<field>'. Confirmation: immediate, sequence (N detections in a row) or timespan. Notifications call endpoints.

Field	Type	Required	Constraints	Description
config	object	no
config.activation	object	no
config.check_interval	object	no
config.check_interval.magnitude	string	no	One of: second, minute, hour, day, week, month, year
config.check_interval.value	number	no	Minimum: 0
config.data	object	no
config.description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
config.name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
config.normalization	object	no
config.reminder	object	no
config.rule	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
config.severity	number	no	Range: 0 to 4
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
enabled	boolean	yes
name	string	yes	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
rule	string	yes	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Bucket threshold

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "30"
        }
      ],
      "confirmation": {
        "mode": "sequence",
        "sequence": {
          "value": 3
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 5
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "5m",
              "type": "mean"
            },
            "group_by": [
              "device"
            ],
            "id": "greenhouse_climate",
            "mapping": [
              "temperature"
            ]
          },
          "name": "climate",
          "source": "bucket"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "28"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 15
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "reminder": {
      "interval": {
        "magnitude": "day",
        "value": 1
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ],
      "type": "interval"
    },
    "severity": 3
  },
  "description": "Mean temperature above 30 for 3 checks in a row, per device",
  "enabled": true,
  "name": "Greenhouse too hot",
  "rule": "greenhouse_hot"
}'

Example body: Device offline

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "0"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 10
        }
      },
      "notifications": [
        {
          "id": "support_webhook",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_status": {
            "fields": [
              "connection.active",
              "connection.ts"
            ],
            "product": "smart_meter"
          },
          "name": "status",
          "source": "device_status"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "1"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "description": "Any device of the smart_meter product disconnected",
  "enabled": true,
  "name": "Meter offline",
  "rule": "meter_offline"
}

Example body: Per-device threshold

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 15
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "1h",
              "type": "max"
            },
            "group_by": [
              "device"
            ],
            "id": "well_levels",
            "mapping": [
              "depth_m"
            ]
          },
          "name": "well",
          "source": "bucket"
        },
        {
          "device_property": {
            "fields": [
              "value.max_depth_m"
            ],
            "product": "piezometer",
            "property": "limits"
          },
          "name": "limits",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m * 0.9"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "description": "Hourly max depth of each well above its own limit: the 'limits' property of the device, or of its asset type, asset group or product when the device has none",
  "enabled": true,
  "name": "Water table too deep",
  "rule": "well_too_deep"
}

Example body: Property condition

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "below",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "15"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "hour",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_property": {
            "asset_group": "field_sensors",
            "fields": [
              "value.level"
            ],
            "property": "battery"
          },
          "name": "battery",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "above",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "50"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 1
  },
  "description": "Battery level reported in the 'battery' property below 15%, devices of the 'field_sensors' group",
  "enabled": true,
  "name": "Low battery",
  "rule": "low_battery"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/users/{user}/alarms/rules/{rule}

• Request: GET /v1/users/{user}/alarms/rules/
• Operation: ReadAlarmRuleConfig
• Operation ID: Alarm_ReadRuleConfig
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

Response example (200, Bucket threshold)

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "30"
        }
      ],
      "confirmation": {
        "mode": "sequence",
        "sequence": {
          "value": 3
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 5
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "5m",
              "type": "mean"
            },
            "group_by": [
              "device"
            ],
            "id": "greenhouse_climate",
            "mapping": [
              "temperature"
            ]
          },
          "name": "climate",
          "source": "bucket"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "28"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 15
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "reminder": {
      "interval": {
        "magnitude": "day",
        "value": 1
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ],
      "type": "interval"
    },
    "severity": 3
  },
  "created": 1792263090787,
  "description": "Mean temperature above 30 for 3 checks in a row, per device",
  "enabled": true,
  "modified": 1792263090787,
  "name": "Greenhouse too hot",
  "rule": "greenhouse_hot"
}

Response example (200, Device offline)

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "0"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 10
        }
      },
      "notifications": [
        {
          "id": "support_webhook",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_status": {
            "fields": [
              "connection.active",
              "connection.ts"
            ],
            "product": "smart_meter"
          },
          "name": "status",
          "source": "device_status"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "1"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "created": 1792263090787,
  "description": "Any device of the smart_meter product disconnected",
  "enabled": true,
  "modified": 1792263090787,
  "name": "Meter offline",
  "rule": "meter_offline"
}

Response example (200, Per-device threshold)

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 15
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "1h",
              "type": "max"
            },
            "group_by": [
              "device"
            ],
            "id": "well_levels",
            "mapping": [
              "depth_m"
            ]
          },
          "name": "well",
          "source": "bucket"
        },
        {
          "device_property": {
            "fields": [
              "value.max_depth_m"
            ],
            "product": "piezometer",
            "property": "limits"
          },
          "name": "limits",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m * 0.9"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "created": 1792263090787,
  "description": "Hourly max depth of each well above its own limit: the 'limits' property of the device, or of its asset type, asset group or product when the device has none",
  "enabled": true,
  "modified": 1792263090787,
  "name": "Water table too deep",
  "rule": "well_too_deep"
}

Response example (200, Property condition)

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "below",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "15"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "hour",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_property": {
            "asset_group": "field_sensors",
            "fields": [
              "value.level"
            ],
            "property": "battery"
          },
          "name": "battery",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "above",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "50"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 1
  },
  "created": 1792263090787,
  "description": "Battery level reported in the 'battery' property below 15%, devices of the 'field_sensors' group",
  "enabled": true,
  "modified": 1792263090787,
  "name": "Low battery",
  "rule": "low_battery"
}

PUT /v1/users/{user}/alarms/rules/{rule}

• Request: PUT /v1/users/{user}/alarms/rules/
• Operation: UpdateAlarmRule
• Operation ID: Alarm_UpdateRule
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

Fields sent replace the stored ones; config replaces the whole rule configuration (read it first to change part of it).

Field	Type	Required	Constraints	Description
config	object	no
config.activation	object	no
config.check_interval	object	no
config.check_interval.magnitude	string	no	One of: second, minute, hour, day, week, month, year
config.check_interval.value	number	no	Minimum: 0
config.data	object	no
config.description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
config.name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
config.normalization	object	no
config.reminder	object	no
config.rule	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
config.severity	number	no	Range: 0 to 4
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
enabled	boolean	no
name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.

Example request: Disable the rule

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

Example body: Rename

{
  "description": "Zone A sensors only",
  "name": "Greenhouse too hot - zone A"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

DELETE /v1/users/{user}/alarms/rules/{rule}

• Request: DELETE /v1/users/{user}/alarms/rules/
• Operation: DeleteAlarmRule
• Operation ID: Alarm_DeleteRule
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Example request

curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

GET /v1/users/{user}/alarms/rules/{rule}/clone

• Request: GET /v1/users/{user}/alarms/rules/{rule}/clone
• Operation: CloneAlarmRuleConfig
• Operation ID: Alarm_CloneRuleConfig
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Example request

curl 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/users/{user}/alarms/rules/{rule}/clone

• Request: POST /v1/users/{user}/alarms/rules/{rule}/clone
• Operation: CloneAlarmRule
• Operation ID: Alarm_CloneRule
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
enabled	boolean	no
name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
rule	string	yes	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "rule": "copy_of_rule"
}'

Example body: Copy with name and description

{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "rule": "line_2_rule"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

PUT /v1/users/{user}/alarms/rules/{rule}/projects

• Request: PUT /v1/users/{user}/alarms/rules/{rule}/projects
• Operation: UpdateAlarmRuleProjects
• Operation ID: Alarm_UpdateRuleProjects
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

Field	Type	Required	Constraints	Description
(body)	array of string	no		Projects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/users/{user}/alarms/rules/{rule}/test-notification

• Request: POST /v1/users/{user}/alarms/rules/{rule}/test-notification
• Operation: TestRuleNotification
• Operation ID: Alarm_TestRuleNotificationTest-notification
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

Simulates an alarm event of a device and SENDS the notifications configured for that event type (config.<type>.notifications) to their endpoints, so real emails or webhooks go out. Returns the notifications and the alarm payload they carried. Nothing is stored.

Field	Type	Required	Constraints	Description
config	object	no
config.activation	object	no
config.check_interval	object	no
config.check_interval.magnitude	string	no	One of: second, minute, hour, day, week, month, year
config.check_interval.value	number	no	Minimum: 0
config.data	object	no
config.description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
config.name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
config.normalization	object	no
config.reminder	object	no
config.rule	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
config.severity	number	no	Range: 0 to 4
description	string or null	no
event	object	yes
event.origin	string or null	no		Device id.
event.type	string	yes	One of: activation, normalization, reminder
event.values	any	no		Source values that triggered the event, by source name.
name	string or null	no

Example request: Activation of a device

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/test-notification' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "activation": {
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "severity": 3
  },
  "description": "Mean temperature above 30",
  "event": {
    "origin": "greenhouse_01",
    "type": "activation",
    "values": {
      "climate": {
        "temperature": 31.2
      }
    }
  },
  "name": "Greenhouse too hot"
}'

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/users/{user}/alarms/rules/{rule}/test-rule

• Request: POST /v1/users/{user}/alarms/rules/{rule}/test-rule
• Operation: TestRule
• Operation ID: Alarm_TestRuleTest-rule
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

Fields sent replace the stored ones; config replaces the whole rule configuration (read it first to change part of it).

Field	Type	Required	Constraints	Description
config	object	no
config.activation	object	no
config.check_interval	object	no
config.check_interval.magnitude	string	no	One of: second, minute, hour, day, week, month, year
config.check_interval.value	number	no	Minimum: 0
config.data	object	no
config.description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
config.name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.
config.normalization	object	no
config.reminder	object	no
config.rule	string	no	Pattern: ^[a-zA-Z0-9_-]{1,32}$	A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
config.severity	number	no	Range: 0 to 4
description	string	no	Maximum length: 255	A brief description of the resource, providing context or additional information, limited to 255 characters.
enabled	boolean	no
name	string	no	Maximum length: 255	The name of the resource, limited to 255 characters. It can include any character.

Example request: Bucket threshold

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/test-rule' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "30"
        }
      ],
      "confirmation": {
        "mode": "sequence",
        "sequence": {
          "value": 3
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 5
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "5m",
              "type": "mean"
            },
            "group_by": [
              "device"
            ],
            "id": "greenhouse_climate",
            "mapping": [
              "temperature"
            ]
          },
          "name": "climate",
          "source": "bucket"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "climate.temperature",
          "operator": "and",
          "type": "value_check",
          "value": "28"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 15
        }
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "reminder": {
      "interval": {
        "magnitude": "day",
        "value": 1
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ],
      "type": "interval"
    },
    "severity": 3
  },
  "description": "Mean temperature above 30 for 3 checks in a row, per device",
  "enabled": true,
  "name": "Greenhouse too hot"
}'

Example body: Device offline

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "0"
        }
      ],
      "confirmation": {
        "mode": "timespan",
        "timespan": {
          "magnitude": "minute",
          "value": 10
        }
      },
      "notifications": [
        {
          "id": "support_webhook",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_status": {
            "fields": [
              "connection.active",
              "connection.ts"
            ],
            "product": "smart_meter"
          },
          "name": "status",
          "source": "device_status"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "equal",
          "field": "status.connection.active",
          "operator": "and",
          "type": "value_check",
          "value": "1"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "description": "Any device of the smart_meter product disconnected",
  "enabled": true,
  "name": "Meter offline"
}

Example body: Per-device threshold

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "above",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "minute",
      "value": 15
    },
    "data": {
      "sources": [
        {
          "bucket": {
            "aggregation": {
              "period": "1h",
              "type": "max"
            },
            "group_by": [
              "device"
            ],
            "id": "well_levels",
            "mapping": [
              "depth_m"
            ]
          },
          "name": "well",
          "source": "bucket"
        },
        {
          "device_property": {
            "fields": [
              "value.max_depth_m"
            ],
            "product": "piezometer",
            "property": "limits"
          },
          "name": "limits",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "below",
          "field": "well.depth_m",
          "operator": "and",
          "type": "value_check",
          "value": "limits.value.max_depth_m * 0.9"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 2
  },
  "description": "Hourly max depth of each well above its own limit: the 'limits' property of the device, or of its asset type, asset group or product when the device has none",
  "enabled": true,
  "name": "Water table too deep"
}

Example body: Property condition

{
  "config": {
    "activation": {
      "conditions": [
        {
          "comparison": "below",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "15"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": [
        {
          "id": "ops_email",
          "type": "endpoint"
        }
      ]
    },
    "check_interval": {
      "magnitude": "hour",
      "value": 1
    },
    "data": {
      "sources": [
        {
          "device_property": {
            "asset_group": "field_sensors",
            "fields": [
              "value.level"
            ],
            "property": "battery"
          },
          "name": "battery",
          "source": "device_property"
        }
      ]
    },
    "normalization": {
      "conditions": [
        {
          "comparison": "above",
          "field": "battery.value.level",
          "operator": "and",
          "type": "value_check",
          "value": "50"
        }
      ],
      "confirmation": {
        "mode": "immediate"
      },
      "notifications": []
    },
    "reminder": {
      "notifications": [],
      "type": "none"
    },
    "severity": 1
  },
  "description": "Battery level reported in the 'battery' property below 15%, devices of the 'field_sensors' group",
  "enabled": true,
  "name": "Low battery"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden

POST /v1/users/{user}/alarms/rules/{rule}/test-source

• Request: POST /v1/users/{user}/alarms/rules/{rule}/test-source
• Operation: TestRuleSource
• Operation ID: Alarm_TestRuleSourceTest-source
• Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

Name	In	Type	Required	Description
user	path	string	yes
rule	path	string	yes

Request body (application/json, required)

One data source, as in config.data.sources: returns the data it produces now, per device. The rule id in the path does not need to exist yet.

Field	Type	Required	Constraints	Description
bucket	object	no
check_interval	object	no		Window read by a bucket source without aggregation, as in config.check_interval (default: the rule's, or 1 minute). The rule does not need to exist.
device_property	object	no
device_status	object	no
name	string or null	no
source	string	yes	One of: bucket, device_property, device_status

Example request: Bucket source

curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/alarms/rules/YOUR_RULE/test-source' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "bucket": {
    "aggregation": {
      "period": "5m",
      "type": "mean"
    },
    "group_by": [
      "device"
    ],
    "id": "greenhouse_climate",
    "mapping": [
      "temperature"
    ]
  },
  "name": "climate",
  "source": "bucket"
}'

Example body: Device property source

{
  "device_property": {
    "asset_group": "field_sensors",
    "fields": [
      "value.level"
    ],
    "property": "battery"
  },
  "name": "battery",
  "source": "device_property"
}

Example body: Device status source

{
  "device_status": {
    "fields": [
      "connection.active",
      "connection.ts"
    ],
    "product": "smart_meter"
  },
  "name": "status",
  "source": "device_status"
}

Responses

Status	Description
200	ok
401	unauthorized
403	forbidden