Pivot alerts API
You can use the Pivot alerts API to create, read, and modify alerts.
Pivot must be running in native users mode.
Get all alerts
Returns a list of all alerts.
URL
GET /api/v1/alerts
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample request
curl -X GET 'http://PIVOT_URL/api/v1/alerts' \
--header 'x-imply-api-token:<token>'
Sample response
Show sample response
{
"alerts": [
{
"name": "9e1e",
"owner": "admin@example.com",
"title": "Wikipedia hourly alert",
"dataCube": "wikipedia",
"checkFrequency": "PT1H",
"timeFrame": "PT1M",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"conditions": [
{
"type": "percent-delta",
"measure": "count",
"condition": "lessThan",
"value": 121
}
],
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "specific",
"roles": [
"super-admin"
]
},
"admins": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"webhooks": [],
"compare": {
"type": "relative",
"duration": "PT1M"
}
},
{
"name": "0adb",
"owner": "admin@example.com",
"title": "Wikipedia monthly alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"type": "within-split",
"timeFrame": "P1M",
"filter": {},
"splits": [
{
"dimension": "isAnonymous",
"sortType": "measure",
"direction": "descending"
}
],
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
],
"severity": "warning",
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "all"
},
"webhooks": [
{
"type": "slack",
"url": "https://hooks.slack.com/services/T000/B000",
"payload": "{\n \"attachments\": [\n {\n \"fallback\": \"%title%\",\n \"color\": \"%color%\",\n \"title\": \"%title%\",\n \"title_link\": \"%link%\",\n \"text\": \"%summary%\",\n \"summaryData\": %summaryData%,\n \"ts\": %triggerDate%,\n \"footer\": \"%footer%\",\n \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n }\n ]\n}"
}
],
"compare": {
"type": "relative",
"duration": "P30D"
}
}
]
}
Get an alert
Returns an alert with a specified name.
URL
GET /api/v1/alerts/{name}
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "This alert does not exist." |
Sample request
curl -X GET 'http://PIVOT_URL/api/v1/alerts/0adb' \
--header 'x-imply-api-token:<token>'
Sample response
Show sample response
{
"alert": {
"name": "0adb",
"owner": "admin@example.com",
"title": "Wikipedia monthly alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"type": "within-split",
"timeFrame": "P1M",
"filter": {},
"splits": [
{
"dimension": "isAnonymous",
"sortType": "measure",
"direction": "descending"
}
],
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
],
"severity": "warning",
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "all"
},
"webhooks": [
{
"type": "slack",
"url": "https://hooks.slack.com/services/T000/B000",
"payload": "{\n \"attachments\": [\n {\n \"fallback\": \"%title%\",\n \"color\": \"%color%\",\n \"title\": \"%title%\",\n \"title_link\": \"%link%\",\n \"text\": \"%summary%\",\n \"summaryData\": %summaryData%,\n \"ts\": %triggerDate%,\n \"footer\": \"%footer%\",\n \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n }\n ]\n}"
}
],
"compare": {
"type": "relative",
"duration": "P30D"
}
}
}
Create an alert
Creates an alert with a specified name.
URL
POST /api/v1/alerts
Sample request
Show sample request
curl -X POST 'http://PIVOT_URL/api/v1/alerts' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"alert": {
"name": "Wikipedia monthly alert",
"owner": "admin@example.com",
"title": "Wikipedia monthly alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"type": "within-split",
"timeFrame": "P1M",
"filter": {},
"splits": [
{
"dimension": "isAnonymous",
"sortType": "measure",
"direction": "descending"
}
],
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
],
"severity": "warning",
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "all"
},
"webhooks": [
{
"type": "slack",
"url": "https://hooks.slack.com/services/T000/B000",
"payload": "{\n \"attachments\": [\n {\n \"fallback\": \"%title%\",\n \"color\": \"%color%\",\n \"title\": \"%title%\",\n \"title_link\": \"%link%\",\n \"text\": \"%summary%\",\n \"summaryData\": %summaryData%,\n \"ts\": %triggerDate%,\n \"footer\": \"%footer%\",\n \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n }\n ]\n}"
}
],
"compare": {
"type": "relative",
"duration": "P30D"
}
}
}'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
400 Bad Request | "error": "name must be defined" |
Sample response
Show sample response
{
"status": "ok",
"message": "Created successfully",
"alert": {
"name": "Wikipedia monthly alert",
"owner": "admin@example.com",
"title": "Wikipedia monthly alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"type": "within-split",
"timeFrame": "P1M",
"filter": {},
"splits": [
{
"dimension": "isAnonymous",
"sortType": "measure",
"direction": "descending"
}
],
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
],
"severity": "warning",
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "all"
},
"webhooks": [
{
"type": "slack",
"url": "https://hooks.slack.com/services/T000/B000",
"payload": "{\n \"attachments\": [\n {\n \"fallback\": \"%title%\",\n \"color\": \"%color%\",\n \"title\": \"%title%\",\n \"title_link\": \"%link%\",\n \"text\": \"%summary%\",\n \"summaryData\": %summaryData%,\n \"ts\": %triggerDate%,\n \"footer\": \"%footer%\",\n \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n }\n ]\n}"
}
],
"compare": {
"type": "relative",
"duration": "P30D"
}
}
}
Update an alert
Updates the details of an alert with a specified name.
URL
POST /api/v1/alerts/{name}
Sample request
The following example request updates the owner
and title
properties of the Wikipedia monthly alert
alert object. The name
in the request body must match the {name}
in the URL. You can't update the name
field.
At a minimum, you must provide dataCube
, checkFrequency
, and conditions
in the alert
body. You must provide all alert properties you want to retain in the alert, even if you don't want to update them. Pivot recreates the alert with the details you specify in the request.
curl -X POST 'http://PIVOT_URL/api/v1/alerts/Wikipedia monthly alert' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"alert": {
"name": "Wikipedia monthly alert",
"owner": "admin@example.com",
"title": "Wikipedia monthly admin alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
]
}'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
400 Bad Request | "error": "the name you entered does not match" |
Sample response
{
"status": "ok",
"message": "Updated successfully",
"alert": {
"name": "Wikipedia monthly alert",
"owner": "admin@example.com",
"title": "Wikipedia monthly admin alert",
"dataCube": "wikipedia",
"checkFrequency": "P1M",
"conditions": [
{
"type": "percent-delta",
"measure": "sum_added",
"condition": "lessThan",
"value": 121
}
]
}
}
Delete an alert
Deletes an alert with a specified name.
URL
DELETE /api/v1/alerts/{name}
Sample request
curl -X DELETE 'http://PIVOT_URL/api/v1/alerts/Wikipedia%20monthly%20alert' \
--header 'x-imply-api-token:<token>'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "This alert does not exist. Please check the name again." |
Sample response
{
"status": "ok",
"message": "Deleted successfully"
}