Skip to main content

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

CodeDescription
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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample body
404 Not Found"error": "This alert does not exist. Please check the name again."

Sample response

{
"status": "ok",
"message": "Deleted successfully"
}