Alert Rules

Alert Rule represents a condition that will trigger an alert.

Endpoints

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

Request Headers What's this?

  • Authorization

    required

    Must contain 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 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

  • 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,
  "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 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,
  "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 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

  • 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 a project API key with the admin operation permission.

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.