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 alert rules.
  • 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 alert rule.
  • 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",
    "increasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity increased",
    "decreasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity decreased",
    "message": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "recoveryMessage": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "increasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity increased to {{severity}}",
    "decreasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity decreased to {{severity}}"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        },
        {
          "recipientType": "slack",
          "assistantId": 1,
          "workspaceId": "ABCDEFGH",
          "channelId": "ABCDEFGH"
        }
      ]
    }
  ]
}

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 alert rule 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",
    "increasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity increased",
    "decreasedSeverityTitle": "[{{alertRuleName}}] {{entityName}} severity decreased",
    "message": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "recoveryMessage": "See the details in https://example.com/projects/{{projectId}}/view/alerts/{{alertId}}",
    "increasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity increased to {{severity}}",
    "decreasedSeverityMessage": "[{{alertRuleName}}] {{entityName}} severity decreased to {{severity}}"
  },
  "actions": [
    {
      "recipients": [
        {
          "recipientType": "email",
          "email": "recipient@example.com"
        },
        {
          "recipientType": "event",
          "eventType": "alert"
        },
        {
          "recipientType": "slack",
          "assistantId": 1,
          "workspaceId": "ABCDEFGH",
          "channelId": "ABCDEFGH"
        }
      ]
    }
  ],
  "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 the alert rule 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
  • 204Successfully deleted the alert rule with the specified ID. There is no return body.
  • 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.
  • 409Some entities have references to the alert rule.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.