Use the following APIs to get, create, update, and delete alerts and alert definitions.

Create an Alert Definition

Required Permissions

You must have the Create Alert Definition permission to perform this operation.

Description

Create an alert definition. Send a JSON request that includes the AlertDefinition fields. You will receive a response with the alert definition ID.

Headers
Authorization: Bearer <JWT Token>
Accept: application/json;api-version=0.8
API
/api/alert-definitions
Method
POST
Required Parameters
Name Description
name

string

Name of the alert definition.

description

string

Alert definition description.

deviceTemplateIds

List of device template IDs.

properties Property value based on which the alert is triggered.
metrics

string

List of metrics the alert definition depends on.

triggerCount

integer

Number of times metric must exceed threshold to trigger.

recommendation

string

Recommended actions when alerts are triggered.

lambda

string

Threshold lambda function.

alertSeverity

string

Alert severity:
  • CRITICAL
  • WARNING
  • INFO
alertTemplate

string

Alert template:
  • THRESHOLD
notificationDefinitionId

string

Notification definition ID.
Input Example
{
"name": "Gateway OS Version Mismatch",
"description": "Gateway OS Version Mismatch",
"deviceTemplateIds":[ "76b94eac-1232-4ab9-8b8a-1f0ee8b37709"],
"properties": ["os-release"],
"triggerCount": 1,
"recommendation": "Kick off a Campaign",
"duration": 1,
"lambda": "\"os-release\" != '1.2.3'",
"alertSeverity": "CRITICAL",
"alertTemplate": "THRESHOLD",
"notificationDefinitionId": "76b94eac-1232-4ab9-8b8a-1f0ee8b37709"
}
Response Example
{
  "alertDefId": "0f70d96a-36b3-47c3-ab34-339bd3f697bd"
}

Get Details of an Alert Definition

Required Permissions

You must have the View Alert Definition permission to perform this operation.

Description

Get the details of an alert definition.

API
/api/alert-definitions/{alert_def_id}
Method
GET
Required Parameters
Name Description
alert_def_id

string

Alert definition ID created by the service.
Response
{
  "lastUpdatedTime": "string",
  "alertDef": {
    "name": "string",
    "lambda": "string",
    "triggerCount": 0,
    "alertSeverity": "UNKNOWN_SEVERITY",
    "metrics": [
      "string"
    ],
    "notificationId": "string",
    "recommendation": "string",
    "alertTemplate": "UNKNOWN_TEMPLATE",
    "deviceTemplateId": "string",
    "description": "string"
  },
  "lastUpdatedBy": "string",
  "updateVersion": 0,
  "createdBy": "string",
  "createdTime": "string",
  "alertDefId": "string"
}

Update an Alert Definition

Required Permissions

You must have the Edit Alert Definition permission to perform this operation.

Description

Update the fields of an alert definition. Send a JSON request that includes all the fields of AlertDefinition, including non-updated fields. Missing fields will overwrite the existing values with default values. You will get a response with the alert definition ID.

API
/api/alert-definitions/{alert_def_id}
Method
PUT
Required Parameters
Name Description
name

string

Name of the alert definition.

description

string

Alert definition description.

deviceTemplateId

Device template ID.

metrics

string

List of metrics the alert definition depends on.

triggerCount

integer

Number of times metric must exceed threshold to trigger.

recommendation

string

Recommended actions when alerts are triggered.

lambda

string

Threshold lambda function.

alertSeverity

string

Alert severity:
  • CRITICAL
  • WARNING
  • INFO
alertTemplate

string

Alert template:
  • THRESHOLD
  • OFFLINE
Input Example
{
  "name": "ABC Alert",
  "lambda": "\"CPU\" > 90",
  "triggerCount": 0,
  "alertSeverity": "INFO",
  "metrics": [
    "string"
  ],
  "notificationId": "12",
  "recommendation": "Offload some processes from this machine",
  "alertTemplate": "THRESHOLD",
  "deviceTemplateId": "string",
  "description": "High CPU Alert"
}
Response
{
  "alertDefId": "string"
}

Delete an Alert Definition

Required Permissions

You must have the Delete Alert Definition permission to perform this operation.

Description

Delete an alert definition. The system cancels all active alerts that use this definition.

API
/api/alert-definitions/{alert_def_id}
Method
DELETE
Required Parameters
Name Description
alert_def_id

string

Alert definition ID created by the service.

Response
{}

Get a List of Alert Definitions

Required Permissions

You must have the View Alert Definition permission to perform this operation.

Description

Get a list of alert definitions that satisfies the optional search parameters.

API
/api/alert-definitions
Method
GET
Optional Parameters
Name Description
name

string

Name of the alert definition.

deviceTemplateId

string

Device template ID.

deviceId

string

Device ID.

alertSeverity

string

Alert severity:
  • CRITICAL
  • WARNING
  • INFO
alertTemplate

string

Alert template:
  • THRESHOLD
  • OFFLINE
page.number

int32

Page number.
page.size

int32

Page size.
Response
{
  "alertDefInfos": [
    {
      "lastUpdatedTime": "string",
      "alertDef": {
        "name": "string",
        "lambda": "string",
        "triggerCount": 0,
        "alertSeverity": "UNKNOWN_SEVERITY",
        "metrics": [
          "string"
        ],
        "notificationId": "string",
        "recommendation": "string",
        "alertTemplate": "UNKNOWN_TEMPLATE",
        "deviceTemplateId": "string",
        "description": "string"
      },
      "lastUpdatedBy": "string",
      "updateVersion": 0,
      "createdBy": "string",
      "createdTime": "string",
      "alertDefId": "string"
    }
  ],
  "page": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  }
}

Get Alert Details

Required Permissions

You must have the View Alert permission to perform this operation.

Description

Get details of an alert.

API
/api/alerts/{alert_id}
Method
GET
Required Parameters
Name Description
alert_id

string

Alert ID created by the service.

Response
{
  "lastUpdatedTime": "string",
  "alertId": "string",
  "triggers": [
    {
      "valueInt64": "0",
      "timeMs": "string",
      "metric": "string",
      "valueDouble": 0.0
    }
  ],
  "alertSeverity": "UNKNOWN_SEVERITY",
  "state": "UNKNOWN_ALERTSTATE",
  "lastUpdatedBy": "string",
  "updateVersion": 0,
  "createdBy": "string",
  "createdTime": "string",
  "userAcknowledged": "string",
  "alertDefId": "string",
  "alertDefName": "string"
}

Changing the Alert State

Required Permissions

You must have the Edit Alert permission to perform this operation.

Description
Update the alert state from Active to Acknowledged.
Note: You cannot revert an alert from Acknowledged state to Active state.
API
/api/alerts/{alert_id}
Method
PUT
Required Parameters
Name Description
alert_id

string

Alert ID created by the service.

state

string

The alert state:
  • ACTIVE
  • ACKNOWLEDGED
Input Example
{
  "state": "ACTIVE"
}
Response
{
  "alertId": "string"
}

Get a List of Alerts

Required Permissions

You must have the View Alert permission to perform this operation.

Description

Get a list of alerts that satisfy certain search parameters.

API
/api/alerts
Method
GET
Optional Parameters
Name Description
alert_def_id

string

Alert definition ID.

alert_def_name

string

Alert definition name.

last_updated_time_start_ms

int64

Last updated start time (UNIX Epoc time with millisecond precision).
last_updated_time_end_ms

int64

Last updated end time.
severity Alert severity.
  • CRITICAL
  • WARNING
  • INFO
state

string

The alert state:
  • ACTIVE
  • ACKNOWLEDGED
page.number

int32

Page number.
page.size

int32

Page size.
Response
{
  "page": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  },
  "alertInfos": [
    {
      "lastUpdatedTime": "string",
      "alertId": "string",
      "triggers": [
        {
          "valueInt64": "string",
          "timeMs": "string",
          "metric": "string",
          "valueBoolean": true,
          "valueString": "string",
          "valueDouble": 0
        }
      ],
      "alertSeverity": "UNKNOWN_SEVERITY",
      "state": "UNKNOWN_ALERTSTATE",
      "lastUpdatedBy": "string",
      "updateVersion": 0,
      "createdBy": "string",
      "createdTime": "string",
      "userAcknowledged": "string",
      "alertDefId": "string",
      "alertDefName": "string"
    }
  ]

Get Alert Trigger History

Required Permissions

You must have the View Alert permission to perform this operation.

Description

Get a list of alert trigger/cancel/acknowledge history of a device for an alert definition.

API
/api/alerts/{alert_id}/trigger-history
Method
GET
Required Parameters
Name Description
alert_id

string

Alert ID.

Response

message AlertTriggerHistory {
   // the detailed alert triggered/cancelled/acknowledged record
   repeated Trigger triggers = 1;
}
// trigger details
message Trigger {
   // metric name
   string metric = 1;
   // timestamp in milliseconds
   int64 time_ms = 2;
   // metric value (four data types) when the alert is triggered: string, int64, double or boolean
   oneof value {
      string value_string = 3;
      int64 value_int64 = 4;
      double value_double = 5;
      bool value_boolean = 6;
   }
  AlertState state = 7;   
   // the username who creates the trigger record
   string userName = 8;    
};