Alert
An Alert
is a object representation of complex logic to be executed by it's parent object Schedule
. Alerts
enable users to add logical expressions in conjunction with several backend alerting services to run after a given scheduled task. An Alert
is comprised of 2 major components:
Component | Description |
---|---|
expressions | a list of expression objects containing the various parts of a logical expression. |
actions | a list of action objects containing the necessary data to execute the action type. |
Alerts
will accept over 30 different data_types
to include all Lighthouse and Yellow lab metrics. For a complete list and description of each available data_type
please see Data Types
Tips
Alerts are intended for single Schedule
use. i.e. one Alert
services one Schedule
.
Alert object
{
"id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994", // uuid specific to Alert
"expressions":[ // an array of expression objects denoting a logical expression
{
"joiner":"", // should be one of: "", "and", "or" (first expression joiner is always "")
"data_type":"test_score", // the type of data being evaluated (one of: "test_score", "current_average", "seo_delta", "best_practices_delta", "performance_delta", "images_score", "logs", "health")
"operator":"<=", // operator used to evaluate expression. One of: ">=", "<="
"value":"80" // the value that "data_type" is being compared to
},
{
"joiner":"or",
"data_type":"current_average",
"operator":"<=",
"value":"75"
}
],
"actions":[ // an array of action objects denoting what automated actions to complete when the expressions are evaluated
{
"action_type":"slack", // one of: "slack", "phone", "email"
"email":"", // if using email: the email address to send an alert
"phone":"" // if using phone: the number to send a text to e.g +13335558888
},
],
"user":"example@gmail.com", // user denoted by email
"schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33", // uuid specific to associated Schedule
"time_created":"2021-11-22T20:48:36.153402Z", // timestamp of Alert creation
"name":"My Scan Alert" // non-unique/non-binding string to help the user remember the alert
}
Create or Update Alert
There are two use cases for this endpoint, Creating and Updating Alerts
.
POST - /alert
# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')
# setup configs
url = f'{CURSION_API_BASE_URL}/alert'
headers = {
"content-type": "application/json",
"Authorization" : CURSION_API_TOKEN
}
data = {
actions: [
{
action_type: "slack",
email: "",
phone: ""
},
]
alert_id: "" # Insert <alert:id> if updating alert
expressions: [
{
joiner: "",
data_type: "test_score",
operator: "<=",
value: "80"
},
{
joiner: "or",
data_type: "current_average",
operator: "<=",
value: "75"
}
]
name: "My Scan Alert"
schedule_id: "5dd6cc87-5f90-471f-84bd-a1b4c759ea33"
site_id: "46053956-761b-4ca6-8cec-3be796695d12"
}
# send the request
res = requests.post(
url=url,
headers=headers,
data=json.dumps(data)
)
# retrieve response data
json_response = res.json()
print(json_response)
View Full Output
{
"id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
"expressions":[
{
"joiner":"",
"data_type":"test_score",
"operator":"<=",
"value":"80"
},
{
"joiner":"or",
"data_type":"current_average",
"operator":"<=",
"value":"75"
}
],
"actions":[
{
"action_type":"slack",
"email":"",
"phone":""
},
],
"user":"example@gmail.com",
"schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
"time_created":"2021-11-22T20:48:36.153402Z",
"name":"My Scan Alert"
}
Retrieve an Alert
This endpoint returns a single Alert
object and is useful as a simple "detailed view" of the alert.
GET - /alert/<alert:id>
import requests, os
# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')
# setup configs
url = f'{BASE_URL}/alert/<alert:id>'
headers = {
"content-type": "application/json",
"Authorization" : CURSION_API_TOKEN
}
# send the request
res = requests.get(
url=url,
headers=headers,
)
# retrieve response data
json_response = res.json()
print(json_response)
View Full Output
{
"id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
"expressions":[
{
"joiner":"",
"data_type":"test_score",
"operator":"<=",
"value":"80"
},
{
"joiner":"or",
"data_type":"current_average",
"operator":"<=",
"value":"75"
}
],
"actions":[
{
"action_type":"slack",
"email":"",
"phone":""
},
],
"user":"example@gmail.com",
"schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
"time_created":"2021-11-22T20:48:36.153402Z",
"name":"My Scan Alert"
}
Retrieve many Alerts
This endpoint returns a paginated response with all Alert
objects filtered by your account and ordered by time_created
. This endpoint is useful when needing to displaying your sites in a table view for example.
The limit
parameter specifies the total number of objects you want returned per "group" (we recommend keeping this under 10 for best performance). The offset
parameter specfies which "group" to return. For example, limit=10&offset=10
in a total dataset of 30 objects would return 10 alerts in range alert #10 - alert #20.
GET - /alert?limit=10&offset=0
import requests, os
# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')
# setup configs
url = f'{BASE_URL}/alert?limit=10&offset=0'
headers = {
"content-type": "application/json",
"Authorization" : CURSION_API_TOKEN
}
# send the request
res = requests.get(
url=url,
headers=headers,
)
# retrieve response data
json_response = res.json()
print(json_response)
View Full Output
{
"count":30,
"next":"https://api.cursion.dev/v1/ops/alert?limit=10&offset=20",
"previous":"https://api.cursion.dev/v1/ops/alert?limit=10&offset=10",
"results":[
{
"id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
"expressions":[
{
"joiner":"",
"data_type":"test_score",
"operator":"<=",
"value":"80"
},
{
"joiner":"or",
"data_type":"current_average",
"operator":"<=",
"value":"75"
}
],
"actions":[
{
"action_type":"slack",
"email":"",
"phone":""
},
],
"user":"example@gmail.com",
"schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
"time_created":"2021-11-22T20:48:36.153402Z",
"name":"My Scan Alert"
},
{
"id":"f31d8c42-54c9-4e94-9495-2cc1eae4c994",
"expressions":[
{
"joiner":"",
"data_type":"test_score",
"operator":"<=",
"value":"80"
},
{
"joiner":"or",
"data_type":"current_average",
"operator":"<=",
"value":"75"
}
],
"actions":[
{
"action_type":"phone",
"email":"",
"phone":"+13335558888"
},
],
"user":"example@gmail.com",
"schedule":"5dd6cc87-5f90-471f-84bd-a1b4c759ea33",
"time_created":"2021-11-22T20:48:36.153402Z",
"name":"My Other Scan Alert"
}
### SHORTENED FOR DISPLAY PURPOSES ###
]
}
Delete an Alert
Caution
Please use caution with this endpoint as it is irreversible.
DELETE - /alert/<alert:id>
import requests, os
# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')
# setup configs
url = f'{BASE_URL}/alert/<alert:id>'
headers = {
"content-type": "application/json",
"Authorization" : CURSION_API_TOKEN
}
# send the request
res = requests.delete(
url=url,
headers=headers,
)
# retrieve response data
json_response = res.json()
print(json_response)
View Full Output
{
"message": "Alert has been deleted"
}