Alert Rules

Alert Rule represents a condition that will trigger an alert.

Endpoints

The Alert Rule object

  • idinteger

    The unique identifier for the alert rule

  • projectIdinteger

    The unique identifier for the project the alert rule belongs to

  • namestring

    The name of the alert rule

  • descriptionstring

    The description of the alert rule

  • enabledboolean

    Whether the alert rule is enabled

  • conditionobject

    The condition that triggers the alert rule

  • messageTemplateobject

    The message template to use when the alert rule is triggered

  • actionsarray

    The actions to take when the alert rule is triggered

  • creationTimestring

    The time the alert rule was created

  • updateTimestring

    The time the alert rule was last updated

Get alert rules

Endpoint
get /alertRules
Description

Get a list of alert rules.

Query Parameters

  • projectId

    integer

    required

    Return alert rules of the specified project.

  • skip

    integer

    Number of alert rules to skip over.

  • limit

    integer

    Maximum number of alert rules to return.

    Default value is 25

    Minimum value is 1

  • conditionType

    string

    Return alert rules of the specified condition type.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read alert rules or a project API key.

Response
  • 200Successfully retrieved the alertRules.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create an alert rule

Endpoint
post /alertRules
Description

Create an alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to create alert rules or a project API key with the admin operation permission.

Request Body

  • name

    string

    required

    The name of the alert rule

  • description

    string

    The description of the alert rule

  • enabled

    boolean

    Whether the alert rule is enabled

  • disableAutoRecovery

    boolean

    Whether alert based on this rule recover automatically

  • condition

    object

    required

    The condition that triggers the alert rule

  • messageTemplate

    object

    The message template to use when the alert rule is triggered

  • actions

    array

    The actions to take when the alert rule is triggered

Response
  • 201Successfully created a new alertRule.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "name": "The room high temperature monitor",
  "description": "The room temperature should be below 35 degrees",
  "enabled": true,
  "disableAutoRecovery": false,
  "condition": {
    "conditionType": "metricsThreshold",
    "delay": "1min",
    "duration": "1min",
    "frequency": "1min",
    "targetMetrics": [
      {
        "entityClass": "room",
        "metricsDefinitionId": "ambient",
        "metricName": "temperature"
      }
    ],
    "aggregation": "avg",
    "thresholds": [
      {
        "operator": "greaterThan",
        "operands": [30],
        "severity": 1
      },
      {
        "operator": "greaterThan",
        "operands": [25],
        "severity": 2
      },
      {
        "operator": "greaterThan",
        "operands": [20],
        "severity": 3
      }
    ]
  },
  "messageTemplate": {
    "title": "The room temperature of {{entityName}} is too high",
    "recoveryTitle": "The room temperature of {{entityName}} is back to normal"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        }
      ]
    }
  ]
}

Get an alert rule

Endpoint
get /alertRules/{alertRuleId}
Description

Return the alert rule with the specified ID.

Path Parameters

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read alert rules or a project API key.

Response
  • 200Successfully retrieved the alertRule with specified ID.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested alertRule does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": 951,
  "name": "The room high temperature monitor",
  "description": "The room temperature should be below 35 degrees",
  "enabled": true,
  "disableAutoRecovery": false,
  "condition": {
    "conditionType": "metricsThreshold",
    "delay": "1min",
    "duration": "1min",
    "frequency": "1min",
    "targetMetrics": [
      {
        "entityClass": "room",
        "metricsDefinitionId": "ambient",
        "metricName": "temperature"
      }
    ],
    "aggregation": "avg",
    "thresholds": [
      {
        "operator": "greaterThan",
        "operands": [30],
        "severity": 1
      },
      {
        "operator": "greaterThan",
        "operands": [25],
        "severity": 2
      },
      {
          "operator": "greaterThan",
          "operands": [20],
          "severity": 3
      }
    ]
  },
  "messageTemplate": {
    "title": "The room temperature of {{entityName}} is too high",
    "recoveryTitle": "The room temperature of {{entityName}} is back to normal"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        }
      ]
    }
  ],
  "creationTime": "2023-01-03T00:05:00.000Z",
  "updateTime": "2023-01-04T00:10:00.000Z"
}

Update an alert rule

Endpoint
patch /alertRules/{alertRuleId}
Description

Update the alert rule with the specified ID. Note if you change the any sub fields of the "condition" field, all the active alerts state will become obsolete state.

Path Parameters

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to update alert rules or a project API key with the admin operation permission.

Request Body

  • name

    string

    The name of the alert rule

  • description

    string

    The description of the alert rule

  • enabled

    boolean

    Whether the alert rule is enabled

  • disableAutoRecovery

    boolean

    Whether alert based on this rule recover automatically

  • condition

    object

    The condition that triggers the alert rule

  • messageTemplate

    object

    The message template to use when the alert rule is triggered

  • actions

    array

    The actions to take when the alert rule is triggered

Response
  • 204Successfully updated alertRule with specified ID. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested alertRule does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Delete an alert rule

Endpoint
delete /alertRules/{alertRuleId}
Description

Delete the alert rule with the specified ID.

Path Parameters

  • alertRuleId

    integer

    required

    The unique ID for a specified alert rule.

Request Headers What's this?

  • Authorization

    required

    Must contain either a key of a user with permissions for alert rule deletion or a project API key with admin operation privileges. Note that you cannot delete an alert rule if any entity has active 'suspendAlertRuleEvaluationConditions' referencing it. You must first remove all 'suspendAlertRuleEvaluationConditions' associated with entities that reference the alert rule before deletion can proceed if you want to delete the alert rule.

Response
  • 201Successfully deleted alertRule with the specified ID. There is no return body.
  • 204The alertRule has been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required alertRule does not exist or is not accessible.
  • 409The alertRule cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.