Alert

Alerts are a way to notify you when something happens. For example, you can create an alert that notifies you when the temperature of a sensor is above 100 degrees. Or maybe you want to be notified when the energy consumption of a building is above 1000 kW. You can create alerts by creating/updating/deleting conditions that need to be met to trigger the alert. Then whenever the alert status changes you will be notified by email if you have the integration activated and you will also receive a notification in the platform.

---

Creating an Alert

To create an alert you need to specify the following parameters:

Field	Description	Required
name	The name of the alert.	Yes
description	A description of the alert (optional field).	No
severity	The severity of the alert.	Yes
type	The type of the alert. Could be cron or rate.	Yes
tags	Tags to be associated with the alert (optional field).	No
alert_items	The items that will be used to trigger the alert. Optional when creating the alert, but required when updating.	No*
stmt_thresholds	The thresholds that will be used to trigger the alert. Optional when creating the alert, but required when updating.	No*

* Optional when creating the alert, but required when updating.

Severity levels range from SEV1 to SEV8, with SEV1 being the most critical and SEV8 the least.

cURL

curl --request POST \
  --url https://api.splight.com/v3/engine/alert/alerts/ \
  --header 'authorization: Splight <access_id> <secret_key>' \
  --header 'content-type: application/json' \
  --data '{
    "name": "<name>",
    "description": "<description>",
    "severity": "<severity>",
    "type": "<type>",
    "tags": ["<tags>"],
    "alert_items": ["<alert_items>"],
    "stmt_thresholds": ["<stmt_thresholds>"]
}'

Python

import requests
import json
from requests.auth import HTTPBasicAuth

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = "https://api.splight.com/v3/engine/alert/alerts/"
payload = {
    "name": "<name>",
    "description": "<description>",
    "severity": "<severity>",
    "type": "<type>",
    "tags": ["<tags>"],
    "alert_items": ["<alert_items>"],
    "stmt_thresholds": ["<stmt_thresholds>"]
}

headers = {
    'authorization': f'Splight {ACCESS_ID} {SECRET_KEY}',
    'content-type': 'application/json'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
print(response.status_code)  # 201 indicates successful creation

---

Reading Alerts

The Splight API offers a robust set of endpoints for reading alert data. You can retrieve information about all alerts or filter them using specific criteria. The API supports various query parameters to help you refine your search.

Below are some examples of how to read alerts using the API, with code snippets in both curl and Python:

Listing all Alerts

cURL

curl --request GET \
    --url 'https://api.splight.com/v3/engine/alert/alerts/' \
    --header 'authorization: Splight <access_id> <secret_key>' \

Python

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = "https://api.splight.com/v3/engine/alert/alerts/"
headers = {
        'authorization': f'Splight {ACCESS_ID} {SECRET_KEY}',
}

response = requests.get(url, headers=headers)
print(response.json())
print(response.status_code)  # 200 indicates successful retrieval

Retrive a single Alert

To retrieve a single alert, you can use the alert ID in the URL. This will return detailed information about that specific alert.

cURL

curl --request GET \
    --url 'https://api.splight.com/v3/engine/alert/alerts/<alert_id>/' \
    --header 'authorization: Splight <access_id> <secret_key>' \

Python

import requests

ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key
ALERT_ID = "<alert_id>"  # Replace with your alert ID

url = f"https://api.splight.com/v3/engine/alert/alerts/{ALERT_ID}/"
headers = {
        'authorization': f'Splight {ACCESS_ID} {SECRET_KEY}',
}

response = requests.get(url, headers=headers)
print(response.json())
print(response.status_code)  # 200 indicates successful retrieval

---

Updating an Alert

To update an alert, you can use the alert ID in the URL and specify the fields you want to update in the request body. You can update any of the fields that were used to create the alert.

cURL

curl --request PATCH \
  --url https://api.splight.com/v3/engine/alert/alerts/<alert_id>/ \
  --header 'authorization: Splight <access_id> <secret_key>' \
  --header 'content-type: application/json' \
    --data '{
        "name": "<name>",
        "description": "<description>",
        "status": "<status>",
        "status_text": "<status_text>",
        "severity": "<severity>",
        "type": "<cron/rate>",
        "active": true/false,
        "stmt_time_window": "<stmt_time_window>",
        "stmt_target_variable": "<stmt_target_variable>",
        "stmt_operator": "<ge/le/eq/gt/lt/eq>",
        "stmt_aggregation": "<avg/sum/min/max/last>",
        "stmt_thresholds": [],
        "alert_items": [],
        "assets": [],
        "mute": true,
        "destinations_list": [],
        "notify_no_data": false/true,
        "notify_error": false/true,
        "notify_timeout": false/true,
        "tags": [],
        "rate_value": "<rate_value>",
        "rate_unit": "<minute/hour/day>",
        "cron_minutes": "*",
        "cron_hours": "*",
        "cron_dom": "*",
        "cron_month": "*",
        "cron_dow": "?",
        "cron_year": "*"
    }'

Python

import requests
import json
from requests.auth import HTTPBasicAuth

ALERT_ID = "<alert_id>"  # Replace with your alert ID
ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = f"https://api.splight.com/v3/engine/alert/alerts/{ALERT_ID}/"
payload = {
    "name": "<name>",
    "description": "<description>",
    "status": "<status>",
    "status_text": "<status_text>",
    "severity": "<severity>",
    "type": "<cron/rate>",
    "active": True/False,
    "stmt_time_window": "<stmt_time_window>",
    "stmt_target_variable": "<stmt_target_variable>",
    "stmt_operator": "<ge/le/eq/gt/lt/eq>",
    "stmt_aggregation": "<avg/sum/min/max/last>",
    "stmt_thresholds": [],
    "alert_items": [],
    "assets": [],
    "mute": True/False,
    "destinations_list": [],
    "notify_no_data": True/False,
    "notify_error": True/False,
    "notify_timeout": True/False,
    "tags": [],
    "rate_value": "<rate_value>",
    "rate_unit": "<minute/hour/day>",
    "cron_minutes": "*",
    "cron_hours": "*",
    "cron_dom": "*",
    "cron_month": "*",
    "cron_dow": "?",
    "cron_year": "*"
}
headers = {
    'authorization': f'Splight {ACCESS_ID} {SECRET_KEY}',
    'content-type': 'application/json'
}

response = requests.patch(url, headers=headers, data=json.dumps(payload))
print(response.text)
print(response.status_code)  # 200 indicates successful update

• All fields are optional when updating an alert, but at least one field must be specified. Fields that are not provided will remain unchanged.

• The rate and cron fields are mutually exclusive. If you specify one, the other will be ignored.

---

Deleting an Alert

To delete an alert, you can use the alert ID in the URL. This will remove the alert from the system.

cURL

curl --request DELETE \
  --url https://api.splight.com/v3/engine/alert/alerts/<alert_id>/ \
  --header 'authorization: Splight <access_id> <secret_key>' \
  --header 'content-type: application/json'

Python

import requests

ALERT_ID = "<alert_id>"  # Replace with your alert ID
ACCESS_ID = "<user_access_id>"  # Replace with your access ID
SECRET_KEY = "<user_secret_key>"  # Replace with your secret key

url = f"https://api.splight.com/v3/engine/alert/alerts/{ALERT_ID}/"
headers = {
    'authorization': f'Splight {ACCESS_ID} {SECRET_KEY}',
}

response = requests.delete(url, headers=headers)
print(response.status_code) # 204 indicates successful deletion