Alerting

Tutorial for creating and managing alert rules on time series and meta-data.

Overview¶

In this article, you will learn how to set up alert rules on time series and meta-data on the aedifion.io platform. Currently, the aedifion.io platform supports three types of alert rules:

• Threshold — on the observations for a datapoint
• Throughput — on the observations received per time interval, for a datapoint or a whole project
• Discrete — fires while a datapoint's value is one of a configured set of values

You will specify one of each and configure it to send out alert notifications via email or Microsoft Teams.

This article uses three terms precisely:

Severity levels appear under two spellings: the API field names are info, warn and crit, and this article calls them info, warning and critical in prose. They are the same three levels throughout.

Preliminaries¶

The examples provided in this article partly build on each other. For the sake of brevity, boiler plate code such as imports or variable definitions is only shown once and left out in subsequent examples.

To execute the examples provided in this tutorial, the following is needed:

• A valid login (username and password) to the aedifion.io platform. If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!
• A project with live data ingress.
• Optionally, a working installation of Python or Curl.

Types of alert rules¶

The aedifion.io platform supports three versatile types of alert rules:

• Threshold alert rules are defined on single datapoints and raise an alert event whenever the measured values for that datapoint exceed (or fall below) a certain threshold. Up to three severity levels are supported: info, warning, and critical. You configure only the levels you actually need — a single critical threshold is a perfectly valid alert rule and is often all you want. Each configured level can optionally have a separate reset threshold to implement hysteresis and prevent flapping. A typical use case for threshold alert rules is notifying about unwanted system conditions such as high CO2 concentration in offices.
• Throughput alert rules are defined on single datapoints or whole projects and raise an alert event whenever the measured throughput for that datapoint or project crosses certain thresholds. Throughput is measured as the number of values received per period, where period is a configurable time window (e.g., the number of values received every 10 minutes). Up to three severity levels (info, warning, critical) indicate the severity of abnormal throughput. A typical use case for throughput alert rules is fault detection by monitoring of the operational health of the building automation systems, e.g., alerting about the unscheduled shut-down of a critical component or notifying when a sensor is dead.
• Discrete alert rules are defined on single datapoints and fire while the datapoint's value is one of a configured set of values (or, when negated, while it is not). Use them for enumerated signals — status words, operating modes, or fault codes — where the interesting values are not a contiguous range and therefore cannot be expressed as thresholds. A single value is the binary/equality case, e.g., alerting while a fault flag reads 1. Discrete alert rules fire at exactly one severity level and have no reset value: membership is exact, so the alert event clears as soon as the value leaves the set.

Comparing the alert rule types¶

The three types share most of their configuration and differ mainly in what defines the alert condition.

All three additionally accept name, description, timezone, disabled, notification and attributes, which behave identically across types. repeat is accepted by all three too, but its default differs per type — see the row above.

Further types of alert rules will be added in future. If you have a special request, please contact us.

Adding alert rules¶

Each alert rule type is created through its own endpoint. The parameters that specify the alert rule must be encoded as a JSON object and sent in the body of the request.

Adding a threshold alert rule¶

A new threshold alert rule is created through the POST /v2/alert/threshold endpoint. The project_id is passed as a query parameter.

Threshold alert rules are defined through the following parameters.

* At least one of thresholds.info, thresholds.warn, and thresholds.crit must be provided. Levels you omit are not evaluated and never notify — see single-threshold alert rules below. † Required exactly when a single level is configured.

Threshold order decides in which direction the alert gets more critical:

• asc — the rule fires when values rise to or above a level. With three levels, that means info < warn < crit.
• desc — the rule fires when values fall to or below a level. With three levels, that means info > warn > crit.

asc and desc refer to the order of the configured threshold values, and therefore to the direction in which the alert becomes more critical.

When you configure two or more levels, the order is inferred from the values and you may omit thresholds.order. Supplying it anyway is allowed, but it is rejected with HTTP 400 if it contradicts the values. Configured levels must be strictly monotonic in the order info, warn, crit — a set that is neither consistently rising nor consistently falling is rejected with HTTP 400. The same check runs on every PATCH, against the merged result: a patch that lifts crit below warn is rejected with HTTP 400 and nothing is changed.

Reset thresholds implement hysteresis. For example, with an ascending rule, a critical alert event is raised when observations reach or exceed thresholds.crit and resets only when they fall below thresholds.crit_reset. This prevents the rule from rapidly toggling on and off when values hover around a threshold. If you do not need hysteresis, simply omit the reset values — they will default to the trigger values.

The reset value always sits on the less critical side of its trigger: below it for asc, above it for desc. The descending throughput example further down follows this rule — it triggers critical at 0 values per period and resets at 2. A reset on the wrong side of its trigger is rejected with HTTP 400 rather than silently misbehaving.

Delay suppresses short-lived excursions. With "delay": "5m", a sensor that briefly spikes over the threshold and recovers within five minutes never produces a notification — the condition has to hold continuously for the whole duration first. This is the tool of choice for noisy or flapping signals; reset thresholds handle the opposite problem of values hovering right at the boundary.

Let's add a threshold alert rule on CO2 concentration and see what happens.

from requests import post, get, patch, delete

project_id = 4
api_url = 'https://<your-api-host>'
auth_john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
newalert = {
    "name": "CO2_Office100",
    "description": "Alert on indoor CO2 level with three severity levels.",
    "dataPointID": "bacnet100-4120-CO2",
    "thresholds": {
        "info": 600,
        "info_reset": 500,
        "warn": 1000,
        "warn_reset": 900,
        "crit": 2500,
        "crit_reset": 2000
    },
    "repeat": "2h",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        },
        "ms_teams": {
            "webhook_urls": ["https://example.webhook.office.com/webhookb2/..."]
        },
        "dashboard": {
            "enabled": False
        }
    },
    "attributes": {
        "category": "comfort",
        "team": "Operations"
    }
}

r = post(f"{api_url}/v2/alert/threshold",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/threshold?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "CO2_Office100",
          "description": "Alert on indoor CO2 level with three severity levels.",
          "dataPointID": "bacnet100-4120-CO2",
          "thresholds": {
              "info": 600,
              "info_reset": 500,
              "warn": 1000,
              "warn_reset": 900,
              "crit": 2500,
              "crit_reset": 2000
          },
          "repeat": "2h",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              },
              "ms_teams": {
                  "webhook_urls": ["https://example.webhook.office.com/webhookb2/..."]
              },
              "dashboard": {
                  "enabled": false
              }
          },
          "attributes": {
              "category": "comfort",
              "team": "Operations"
          }
        }'

The JSON-formatted response (HTTP 201) confirms that the alert rule was successfully created and returns its details:

{
  "id": 6,
  "name": "CO2_Office100",
  "description": "Alert on indoor CO2 level with three severity levels.",
  "alert_type": "threshold",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T10:30:00.000000Z",
  "updated": "2024-01-15T10:30:00.000000Z",
  "dataPointID": "bacnet100-4120-CO2",
  "threshold_info": 600,
  "threshold_info_reset": 500,
  "threshold_warn": 1000,
  "threshold_warn_reset": 900,
  "threshold_crit": 2500,
  "threshold_crit_reset": 2000,
  "threshold_order": "asc",
  "repeat": "2h",
  "timezone": "Europe/Berlin",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "",
  "teams_webhook": "https://example.webhook.office.com/webhookb2/...",
  "alarm_dashboard": false,
  "attributes": {"category": "comfort", "team": "Operations"}
}

Note that the alert rule has received a unique numeric id (6) and has been enabled immediately. The repeat value you provided during creation is returned in the repeat field. Threshold alert rules have no measurement period — that field is only present on throughput rules. The timezone is always returned, even when you did not set it, so you can see which timezone the notification timestamps are rendered in.

You may already receive alert notifications or try to provoke some by gathering a few people in your office or by directly breathing into the CO2 sensor. But first, we will look at simpler single-threshold alert rules and then add a rule of the second type, i.e., throughput. Later, we will also look at how to test your alert rules by deliberately setting low thresholds.

Single-threshold alert rules¶

You rarely need all three severity levels. If you only care about one condition, configure just that level — the rule then sends a single notification per alert event instead of up to three.

Because a single value cannot tell the platform whether the rule should fire above or below it, you must state the direction explicitly via thresholds.order:

newalert = {
    "name": "CO2_Office100_critical_only",
    "description": "Notify once when indoor CO2 becomes critical.",
    "dataPointID": "bacnet100-4120-CO2",
    "thresholds": {
        "crit": 2500,
        "crit_reset": 2000,
        "order": "asc"
    },
    "delay": "5m",
    "repeat": "never",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        }
    }
}

r = post(f"{api_url}/v2/alert/threshold",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/threshold?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "CO2_Office100_critical_only",
          "description": "Notify once when indoor CO2 becomes critical.",
          "dataPointID": "bacnet100-4120-CO2",
          "thresholds": {
              "crit": 2500,
              "crit_reset": 2000,
              "order": "asc"
          },
          "delay": "5m",
          "repeat": "never",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              }
          }
        }'

This rule fires only once CO2 has stayed at or above 2500 ppm for five uninterrupted minutes, notifies a single time, and stays quiet until the level actually changes again — because "repeat": "never" disables re-notification. It clears when CO2 falls below 2000 ppm.

The response contains only the configured level; threshold_info, threshold_warn and their resets are absent:

{
  "id": 8,
  "name": "CO2_Office100_critical_only",
  "description": "Notify once when indoor CO2 becomes critical.",
  "alert_type": "threshold",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T10:40:00.000000Z",
  "updated": "2024-01-15T10:40:00.000000Z",
  "dataPointID": "bacnet100-4120-CO2",
  "threshold_crit": 2500,
  "threshold_crit_reset": 2000,
  "threshold_order": "asc",
  "repeat": "never",
  "delay": "5m",
  "timezone": "Europe/Berlin",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "",
  "teams_webhook": "",
  "alarm_dashboard": false,
  "attributes": ""
}

A descending threshold rule¶

The examples so far all alert on a value getting too high. The opposite case — a value falling too low — is just as common in building operation: a flow temperature that drops away from its setpoint, or a pressure that decays.

Set "order": "desc" and let the thresholds fall as severity rises. Note that each reset sits above its trigger, the mirror image of the ascending case:

newalert = {
    "name": "Heating_flow_temperature_low",
    "description": "Flow temperature of the heating circuit dropping away from setpoint.",
    "dataPointID": "bacnet100-4120-HeatingCircuit-FlowTemp",
    "thresholds": {
        "info": 60,
        "info_reset": 62,
        "warn": 55,
        "warn_reset": 57,
        "crit": 50,
        "crit_reset": 52,
        "order": "desc"
    },
    "delay": "10m",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        }
    }
}

r = post(f"{api_url}/v2/alert/threshold",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/threshold?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "Heating_flow_temperature_low",
          "description": "Flow temperature of the heating circuit dropping away from setpoint.",
          "dataPointID": "bacnet100-4120-HeatingCircuit-FlowTemp",
          "thresholds": {
              "info": 60,
              "info_reset": 62,
              "warn": 55,
              "warn_reset": 57,
              "crit": 50,
              "crit_reset": 52,
              "order": "desc"
          },
          "delay": "10m",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              }
          }
        }'

The rule escalates as the temperature falls — info at 60 °C, warning at 55 °C, critical at 50 °C — and each level clears only once the temperature has recovered two degrees past its trigger. The ten-minute delay keeps a brief dip during a setpoint change from notifying anyone.

Creating a paused alert rule¶

Set "disabled": true on any of the create endpoints to create an alert rule in a paused state. It is stored with all its settings but never fires until you enable it.

newalert = {
    "name": "CO2_Office100_draft",
    "dataPointID": "bacnet100-4120-CO2",
    "thresholds": {"crit": 2500, "order": "asc"},
    "disabled": True,
    "notification": {"email": {"recipients": ["john.doe@aedifion.com"]}}
}

r = post(f"{api_url}/v2/alert/threshold",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/threshold?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "CO2_Office100_draft",
          "dataPointID": "bacnet100-4120-CO2",
          "thresholds": {"crit": 2500, "order": "asc"},
          "disabled": true,
          "notification": {"email": {"recipients": ["john.doe@aedifion.com"]}}
        }'

The alert rule is returned with "status": "Disabled". This is the recommended way to set up an alert rule whose recipients or thresholds you still want to verify — unlike creating it and disabling it afterwards, the rule never runs in between.

Adding a throughput alert rule¶

A new throughput alert rule is created through the POST /v2/alert/throughput endpoint. The project_id is passed as a query parameter.

Throughput alert rules are defined through the following parameters.

* At least one of thresholds.info, thresholds.warn, and thresholds.crit must be provided. † Required exactly when a single level is configured.

As with threshold alert rules, the threshold order is inferred as soon as two or more levels are configured:

• If info < warn < crit, the rule gets more critical as throughput grows (ascending).
• If info > warn > crit, the rule gets more critical as throughput drops (descending).

A single-level throughput alert rule — for example "notify me when this project stops delivering data at all" — needs thresholds.order set explicitly, exactly as for threshold alert rules.

How period behaves, since it decides both what is measured and how quickly you hear about it:

• It is the measurement window and the evaluation interval at once. Values are counted per window, and the rule is evaluated once per window — not continuously.
• Windows are consecutive and aligned, not rolling. A window is assessed only when it ends, so detecting a datapoint that has gone quiet takes up to one full period.
• The first window after creating the rule is partial, because it starts mid-window. If the partial count falls under a threshold, that alone can raise an alert event which clears at the end of the next full window. Patching period restarts the windows and has the same effect.

newalert = {
    "name": "EON_ERC_Throughput",
    "description": "Alert on project data ingress throughput.",
    "thresholds": {
        "info": 50,
        "info_reset": 60,
        "warn": 20,
        "warn_reset": 25,
        "crit": 0,
        "crit_reset": 2
    },
    "period": "10m",
    "repeat": "1d",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        },
        "ms_teams": {
            "webhook_urls": ["https://example.webhook.office.com/webhookb2/..."]
        }
    }
}

r = post(f"{api_url}/v2/alert/throughput",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/throughput?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "EON_ERC_Throughput",
          "description": "Alert on project data ingress throughput.",
          "thresholds": {
              "info": 50,
              "info_reset": 60,
              "warn": 20,
              "warn_reset": 25,
              "crit": 0,
              "crit_reset": 2
          },
          "period": "10m",
          "repeat": "1d",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              },
              "ms_teams": {
                  "webhook_urls": ["https://example.webhook.office.com/webhookb2/..."]
              }
          }
        }'

The response (HTTP 201) confirms the creation:

{
  "id": 7,
  "name": "EON_ERC_Throughput",
  "description": "Alert on project data ingress throughput.",
  "alert_type": "throughput",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T11:00:00.000000Z",
  "updated": "2024-01-15T11:00:00.000000Z",
  "dataPointID": "",
  "threshold_info": 50,
  "threshold_info_reset": 60,
  "threshold_warn": 20,
  "threshold_warn_reset": 25,
  "threshold_crit": 0,
  "threshold_crit_reset": 2,
  "threshold_order": "desc",
  "period": "10m",
  "repeat": "1d",
  "timezone": "Europe/Berlin",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "",
  "teams_webhook": "https://example.webhook.office.com/webhookb2/...",
  "alarm_dashboard": false,
  "attributes": ""
}

Since no dataPointID was provided, the throughput of the whole project is measured. Throughput alert rules are the only type that returns a period — it is the measurement window, and it is distinct from repeat, which controls how often an unchanged alert re-notifies.

Adding a discrete alert rule¶

A new discrete alert rule is created through the POST /v2/alert/discrete endpoint. The project_id is passed as a query parameter.

Discrete alert rules are defined through the following parameters.

Discrete alert rules have no thresholds, no order, and no reset values. Membership in values is exact, so the alert event clears as soon as the value leaves the set.

Let's alert on a chiller that reports the fault codes 2, 5 and 7, while ignoring the informational codes 3, 4 and 6 — a condition that cannot be expressed with thresholds because the interesting values are not a contiguous range.

newalert = {
    "name": "Chiller_01_fault",
    "description": "Alert while the chiller reports one of the fault codes 2, 5 or 7.",
    "dataPointID": "bacnet100-4120-Chiller01-Status",
    "values": [2, 5, 7],
    "level": "crit",
    "negate": False,
    "delay": "5m",
    "notification": {
        "email": {
            "recipients": ["john.doe@aedifion.com"]
        }
    }
}

r = post(f"{api_url}/v2/alert/discrete",
         auth=auth_john,
         params={"project_id": project_id},
         json=newalert)

print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/discrete?project_id=4"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "name": "Chiller_01_fault",
          "description": "Alert while the chiller reports one of the fault codes 2, 5 or 7.",
          "dataPointID": "bacnet100-4120-Chiller01-Status",
          "values": [2, 5, 7],
          "level": "crit",
          "negate": false,
          "delay": "5m",
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com"]
              }
          }
        }'

The response (HTTP 201) confirms the creation:

{
  "id": 9,
  "name": "Chiller_01_fault",
  "description": "Alert while the chiller reports one of the fault codes 2, 5 or 7.",
  "alert_type": "discrete",
  "project_id": 4,
  "status": "Enabled",
  "created": "2024-01-15T11:30:00.000000Z",
  "updated": "2024-01-15T11:30:00.000000Z",
  "dataPointID": "bacnet100-4120-Chiller01-Status",
  "values": [2, 5, 7],
  "level": "crit",
  "negate": false,
  "repeat": "1h",
  "delay": "5m",
  "timezone": "Europe/Berlin",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "",
  "teams_webhook": "",
  "alarm_dashboard": false,
  "attributes": ""
}

Set "negate": true to invert the condition — for example to alert while a pump status is anything other than the expected "running" code:

{
  "name": "Pump_01_not_running",
  "dataPointID": "bacnet100-4120-Pump01-Status",
  "values": [1],
  "negate": true,
  "level": "warn",
  "notification": {
    "email": {
      "recipients": ["john.doe@aedifion.com"]
    }
  }
}

Testing your alert rules¶

The CO2 alert rule we created first might have been set too defensively and not trigger unless there is a small party going on in your office. To provoke a threshold alert event and verify the rule works, you can create a rule with deliberately low thresholds that will trigger immediately — e.g. "thresholds": {"crit": 200, "order": "asc"} for a CO2 sensor that normally reads above 400 ppm. Remember that a single configured level needs an explicit order, otherwise the request is rejected with HTTP 400. You may also try to provoke some alert events by gathering a few people in your office or by directly breathing into the CO2 sensor. Alert notifications will soon arrive on the channels you configured.

Similarly, you can provoke a throughput alert event by setting very high thresholds, e.g., "crit": 20000, "warn": 50000 and "info": 100000.

Controlling alert notifications¶

Every alert rule notifies whenever its severity level changes. Two settings control what happens in between, and both apply to all three alert rule types.

You are told when a condition clears¶

A notification is sent when the condition clears, not only when it starts. Each notification states which of these happened:

So an operator does not have to poll to find out whether a fault went away. repeat: "never" suppresses only the unchanged reminders — the level-change notifications, including the resolving one, are always delivered.

How often an alert repeats¶

repeat is the minimum interval after which an alert that has not changed level is notified again.

Use "repeat": "never" for one-shot alert rules — conditions you want to know about once, where a repeated reminder would only add noise.

What a notification looks like¶

An email notification carries the alert level, what triggered it, and where. For the CO2 rule created above, the critical notification reads:

Subject: Alert CO2_Office100 is CRITICAL

  CRITICAL
  Alert "CO2_Office100" fired on level CRITICAL.
  Alert on indoor CO2 level with three severity levels.

  Details
  Type             threshold
  Time             2024-01-15 14:32:05 (Europe/Berlin)
  Project          Office Building Munich
  Datapoint        bacnet100-4120-CO2
  Value            2571
  Condition        value >= 2500
  Delay            5m
  Level            CRITICAL
  Trend            Fired
  Previous level   WARNING
  category         comfort
  team             Operations

The Trend line is the one to read first — it distinguishes a new problem from an escalation, a de-escalation, a periodic reminder, or a resolved condition. When the condition clears you receive the same layout with Alert "CO2_Office100" is back to level OK.

Delay appears only when the rule sets one, Datapoint only when the rule watches a specific datapoint, and each attributes entry becomes its own line — which is what makes them useful for routing and triage by eye. Microsoft Teams and Telegram carry the same fields in their own formatting.

Which timezone timestamps use¶

Alert notifications render their timestamps in the alert rule's timezone. If you do not set it, the rule uses the project's building timezone and falls back to UTC when that is not configured. The effective value is always returned in the alert rule object, so you can verify which timezone a given rule reports in.

Set it explicitly with an IANA timezone name:

{"timezone": "Europe/Berlin"}

Retrieving a single alert rule¶

To read one alert rule by its id, call GET /v2/alert/{alert_id}. It returns the same alert rule object as the create, update, enable and disable endpoints — useful for resolving a deep link without paging through the whole list.

alert_id = 6
r = get(f"{api_url}/v2/alert/{alert_id}",
        auth=auth_john)
print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/6"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response (HTTP 200) is the alert rule object; an unknown id returns HTTP 404.

Listing alert rules¶

You can list all alert rules using the GET /v2/project/{project_id}/alerts endpoint. The response is paginated and supports filtering, searching, and sorting.

r = get(f"{api_url}/v2/project/{project_id}/alerts",
        auth=auth_john,
        params={"per_page": 50})
print(r.status_code, r.text)

curl "https://<your-api-host>/v2/project/4/alerts?per_page=50"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response is a paginated object containing a list of alert rules and pagination metadata. Among them, we find the alert rules we defined previously. Note that the previously disabled rule has "status": "Disabled" because we paused it earlier.

{
  "items": [
    {
      "id": 6,
      "name": "CO2_Office100",
      "description": "Alert on indoor CO2 level with three severity levels.",
      "alert_type": "threshold",
      "project_id": 4,
      "status": "Disabled",
      "created": "2024-01-15T10:30:00.000000Z",
      "updated": "2024-01-15T10:35:00.000000Z",
      "dataPointID": "bacnet100-4120-CO2",
      "threshold_info": 600,
      "threshold_info_reset": 500,
      "threshold_warn": 1000,
      "threshold_warn_reset": 900,
      "threshold_crit": 2500,
      "threshold_crit_reset": 2000,
      "threshold_order": "asc",
      "repeat": "2h",
      "timezone": "Europe/Berlin",
      "email": "john.doe@aedifion.com",
      "telegram_chatid": "",
      "teams_webhook": "https://example.webhook.office.com/webhookb2/...",
      "alarm_dashboard": false,
      "attributes": {"category": "comfort", "team": "Operations"}
    },
    {
      "id": 7,
      "name": "EON_ERC_Throughput",
      "description": "Alert on project data ingress throughput.",
      "alert_type": "throughput",
      "project_id": 4,
      "status": "Enabled",
      "created": "2024-01-15T11:00:00.000000Z",
      "updated": "2024-01-15T11:00:00.000000Z",
      "dataPointID": "",
      "threshold_info": 50,
      "threshold_info_reset": 60,
      "threshold_warn": 20,
      "threshold_warn_reset": 25,
      "threshold_crit": 0,
      "threshold_crit_reset": 2,
      "threshold_order": "desc",
      "period": "10m",
      "repeat": "1d",
      "timezone": "Europe/Berlin",
      "email": "john.doe@aedifion.com",
      "telegram_chatid": "",
      "teams_webhook": "https://example.webhook.office.com/webhookb2/...",
      "alarm_dashboard": false,
      "attributes": ""
    }
  ],
  "meta": {
    "total_items": 2,
    "items_per_page": 50,
    "current_page": 1,
    "total_pages": 1
  }
}

You can also filter results, for example to show only threshold alert rules:

r = get(f"{api_url}/v2/project/{project_id}/alerts",
        auth=auth_john,
        params={"filter": "alert_type=threshold"})
print(r.text)

curl "https://<your-api-host>/v2/project/4/alerts?filter=alert_type%3Dthreshold"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Filters on different keys are combined with AND, so this lists all currently paused throughput alert rules, most recently updated first:

r = get(f"{api_url}/v2/project/{project_id}/alerts",
        auth=auth_john,
        params={"filter": "alert_type=throughput;status=disabled",
                "sort_by": "updated",
                "sort_order": "desc"})
print(r.text)

curl "https://<your-api-host>/v2/project/4/alerts?filter=alert_type%3Dthroughput%3Bstatus%3Ddisabled&sort_by=updated&sort_order=desc"
    -X GET
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Modifying alert rules¶

Use PATCH /v2/alert/{alert_id} to change an existing alert rule in place. The rule keeps its id and its notification state — no delete-and-recreate needed.

Only the fields you send are changed; everything you omit keeps its current value. An empty payload is a no-op and returns the alert rule unchanged.

The following can be changed: name, description, thresholds (individual levels and resets), repeat, delay, timezone, notification, attributes, a throughput rule's period, and a discrete rule's values, level and negate.

Let's raise the critical threshold of our CO2 alert rule and add a recipient:

alert_id = 6
r = patch(f"{api_url}/v2/alert/{alert_id}",
          auth=auth_john,
          json={
              "thresholds": {"crit": 3000, "crit_reset": 2400},
              "notification": {
                  "email": {
                      "recipients": ["john.doe@aedifion.com", "jane.doe@aedifion.com"]
                  }
              }
          })
print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/6"
    -X PATCH
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd
    -H 'Content-Type: application/json'
    -d '{
          "thresholds": {"crit": 3000, "crit_reset": 2400},
          "notification": {
              "email": {
                  "recipients": ["john.doe@aedifion.com", "jane.doe@aedifion.com"]
              }
          }
        }'

The response (HTTP 200) is the complete updated alert rule.

How the merge works¶

Both at the top level and inside the nested objects (thresholds, notification, attributes):

• A key you omit keeps its current value.
• A key you provide is added or overwritten.
• A key you set to null is removed.

Lists are replaced, never appended to. To add a recipient, send the complete list you want:

{"notification": {"email": {"recipients": ["john.doe@aedifion.com", "jane.doe@aedifion.com"]}}}

Sending only the new address would leave you with only that address.

Removing settings¶

Set a key to null to delete it. This works for notification channels, severity levels, attributes, and optional top-level fields such as description, repeat, delay and timezone:

{
  "notification": {"email": null},
  "thresholds": {"warn": null, "warn_reset": null},
  "attributes": {"team": null},
  "delay": null
}

Notes on removal:

• Removing a trigger also drops its paired reset automatically, so {"thresholds": {"warn": null}} is enough — warn_reset will not be left orphaned.
• At least one severity level must remain; a patch that removes them all is rejected with HTTP 400.
• Setting repeat or timezone to null resets them to their defaults rather than leaving them unset.
• An empty object ({}) is a no-op, not a clear — clearing requires an explicit null per key.

What cannot be changed via PATCH¶

Fields that belong to another alert rule type are rejected with HTTP 400 — period on a threshold rule, delay on a throughput rule, or values/level/negate on anything but a discrete rule.

Enabling and disabling alert rules¶

Since the rule might now be triggering notifications frequently, let's take a break and disable it. You can disable an alert rule to temporarily stop it from sending notifications, and enable it again later. There are two separate endpoints for this: POST /v2/alert/{alert_id}/disable and POST /v2/alert/{alert_id}/enable.

Disabling an alert rule¶

alert_id = 6
r = post(f"{api_url}/v2/alert/{alert_id}/disable",
         auth=auth_john)
print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/6/disable"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response (HTTP 200) returns the alert rule with its updated status:

{
  "id": 6,
  "name": "CO2_Office100",
  "description": "Alert on indoor CO2 level with three severity levels.",
  "alert_type": "threshold",
  "project_id": 4,
  "status": "Disabled",
  "created": "2024-01-15T10:30:00.000000Z",
  "updated": "2024-01-15T10:35:00.000000Z",
  "dataPointID": "bacnet100-4120-CO2",
  "threshold_info": 600,
  "threshold_info_reset": 500,
  "threshold_warn": 1000,
  "threshold_warn_reset": 900,
  "threshold_crit": 2500,
  "threshold_crit_reset": 2000,
  "threshold_order": "asc",
  "repeat": "2h",
  "timezone": "Europe/Berlin",
  "email": "john.doe@aedifion.com",
  "telegram_chatid": "",
  "teams_webhook": "https://example.webhook.office.com/webhookb2/...",
  "alarm_dashboard": false,
  "attributes": {"category": "comfort", "team": "Operations"}
}

Enabling an alert rule¶

To re-enable the rule, use the enable endpoint:

alert_id = 6
r = post(f"{api_url}/v2/alert/{alert_id}/enable",
         auth=auth_john)
print(r.status_code, r.text)

curl "https://<your-api-host>/v2/alert/6/enable"
    -X POST
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

The response (HTTP 200) returns the alert rule with "status": "Enabled".

Deleting alert rules¶

Deleting an alert rule is a simple matter of calling DELETE /v2/alert/{alert_id}. The response is HTTP 204 (No Content) with an empty body — per REST semantics, the 204 status itself is the confirmation that the alert rule was deleted. An unknown id returns HTTP 404.

Note that deleting is no longer necessary just to change an alert rule: use PATCH to update one in place, or disable it to stop notifications while keeping its configuration.

As an example, we now delete the threshold alert rule that we have previously created.

alert_id = 6
r = delete(f"{api_url}/v2/alert/{alert_id}",
           auth=auth_john)
print(r.status_code)

curl "https://<your-api-host>/v2/alert/6"
    -X DELETE
    -u john.doe@aedifion.com:mys3cr3tp4ssw0rd

Go ahead and also delete the throughput alert rule, then call GET /v2/project/{project_id}/alerts to verify that both rules are gone.