/
Working with triggered alerts using the API
Document toolboxDocument toolbox

Working with triggered alerts using the API

Owned by Former user (Deleted)
Last updated: May 27, 2025 by Laszlo FrazerVersion comment
[ 1 Overview ] [ 2 Endpoints and methods ]

Overview

Check the list of available endpoints and methods to work with triggered alerts using the Alerts API:

Endpoints and methods

Description

Endpoints and methods

Description

GET/alerts/get see below

Get information about a triggered alert by ID.

GET /alerts/listsee below

Get a list of triggered alerts in your domain.

GET /alerts/statisticssee below

Get statistics from a set of alerts.

GET /alerts/listStatussee below

Get the status of a set of alerts.

PUT /alerts/updateStatussee below

Update alert status by ID.

PUT /alerts/updateStatusListsee below

Update alert status in bulk.

PUT /alerts/{alertID}/prioritysee below

Update the priority of a given alert.

Endpoints and methods

GET/alerts/get

Get information about a triggered alert by ID.

To perform this request, your Devo user must have at least the Alerts (view) permission assigned. Learn more about roles and permissions in this article.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

id required

string

Enter the ID of the alert.

How can I get the ID of a triggered alert?

Triggered alert IDs are displayed in the Alerts area of the Devo platform. You can find them in the Alerts history table at the bottom of the Alerts dashboard tab. Learn more about this in Managing triggered alerts.

You will also get the IDs of the triggered alerts in a domain using GET/v1/alerts/list

tags

boolean

Add this parameter and set it to true to include all the alert tags in the response. The default value is true.

Authorizing requests using the tags parameter

Note that if you use the tags parameter in this request, you must authorize it using a Query API token. The Alert API token is not valid for this request.

Learn more about this in Authorizing Alerts API requests.

annotations

boolean

Add this parameter and set it to true to include all the alert annotations in the response. The default value is true.

Example

Find below a request example in cURL language. This request will show details of the triggered alert with ID 123456 defined in the domain that corresponds to the given token. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/alerts/v1/alerts/get?id=123456"

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. The response includes details about the triggered alert.

{ "id": 123456, "domain": "myDomain", "priority": 4, "context": "my.alert.demo.AWSConsoleLoginFailure", "category": "my.context", "srcPort": null, "srcIp": null, "srcHost": null, "dstIp": null, "dstPort": null, "dstHost": null, "protocol": null, "username": "user@devo.com", "application": null, "engine": "pilot-8-pro-cloud-custom-aws-us-east-1", "extraData": "{\"userIdentity_principalId\":\"AIDA3Y41I57DEUQSSBD1ZE\",\"mfaUsed\":\"No\",\"loginResponse\":\"Failure\",\"userIdentity_type\":\"IAMUser\",\"count\":\"1\",\"userName\":\"jason.green\",\"eventdate\":\"2023-04-03+13%3A39%3A00.0\"}", "alertDate": null, "status": 0, "ack_status_date": null, "createDate": 1680529252000, "updateDate": null, "scaled": false, "digest": "5ad6c04d1f29125dfae0de480584f9c39362f4f3", "uniquedigest": "f8ca95e3ed3c853b7f39dd39c099b8547c9e2f7b", "postAlertAction": null, "contextLabel": null, "contextSubscription": null, "shouldSend": false, "alertOwner": null, "fullExtraData": null, "alertType": null, "alertMitreTactics": null, "alertMitreTechniques": null, "alertPriority": null, "alertDefinition": null, "allExtraDataFields": null, "tags": null, "entities": null, "commentsList": [], "integrations": null, "contexto": null }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

GET/v1/alerts/list

Get a list of triggered alerts in your domain.

To perform this request, your Devo user must have at least the Alerts (view) permission assigned. Learn more about roles and permissions in this article.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&).

Limits:

Parameter

Type

Definition

Parameter

Type

Definition

limit required

integer

Maximum number of elements returned in the response.

offset required

integer

Position of the first element in the returned list. You will retrieve a subset of records starting with the offset value. Enter 0 if you don't want to specify a subset.

from required

string

Filters all alerts triggered after this date. This must by an epoch time in milliseconds.

to required

string

Filters all alerts triggered before this date. This must by an epoch time in milliseconds.

orderby

string

Order the alerts by a specific field. Must be one of the following:

  • id

  • domain

  • priority

  • context

  • category

  • srcPort

  • srcIp

  • srcHost

  • dstIp

  • dstPort

  • dstHost

  • protocol

  • username

  • application

  • engine

  • extraData

  • status

  • ack_status_date

  • createDate

  • updateDate

orderasc

boolean

Set this parameter to true to retrieve the alert list in ascending order.

showAll

boolean

Set this parameter to true to retrieve all the triggered alerts, including the ones with false positive and closed status. The default value is false.

Example

Find below a request example in cURL language. This request will show details of the alerts triggered in the time range indicated in the domain that corresponds to the given token. We want a maximum of 3 alerts to be returned. Learn how to authorize your request in this article.

curl -H 'standAloneToken:YOUR_TOKEN' -X GET "https://api-us.devo.com/alerts/v1/alerts/list?limit=3&offset=0&from=1654008600000&to=1654008900000"

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. The response includes the list of alerts triggered in the period indicated.

[ { "id": 0, "domain": "string", "priority": 0, "context": "string", "category": "string", "srcPort": 0, "srcIp": "string", "srcHost": "string", "dstIp": "string", "dstPort": 0, "dstHost": "string", "protocol": "string", "username": "string", "application": "string", "engine": "string", "extraData": "string", "alertDate": "2022-07-19T09:00:49.052Z", "status": 0, "ack_status_date": "2022-07-19T09:00:49.052Z", "createDate": "2022-07-19T09:00:49.052Z", "updateDate": "2022-07-19T09:00:49.052Z", "scaled": true, "digest": "string", "uniquedigest": "string", "contexto": { "id": 0, "pilotContextId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "category": { "id": 0, "name": "string", "owner": "string", "subCategories": [ { "id": 0, "name": "string", "hasContext": true, "alert_category_id": 0, "contextList": [ "string" ] } ] }, "subCategory": { "id": 0, "name": "string", "hasContext": true, "alert_category_id": 0, "contextList": [ "string" ] }, "application_id": 0, "defaultParams": "string", "includefields": "string", "excludefields": "string" }, "postAlertAction": "string", "contextLabel": "string", "contextSubscription": 0, "shouldSend": true, "alertOwner": "string", "fullExtraData": "string", "alertType": "string", "alertMitreTactics": "string", "alertMitreTechniques": "string", "alertPriority": "string", "alertDefinition": { "id": "string", "creationDate": "2022-07-19T09:00:49.052Z", "name": "string", "message": "string", "description": "string", "categoryId": "string", "subcategory": "string", "subcategoryId": "string", "isActive": true, "isFavorite": true, "isAlertChain": true, "alertCorrelationContext": { "id": "string", "nameId": "string", "ownerEmail": "string", "querySourceCode": "string", "priority": 0, "correlationTrigger": { "kind": "string" } }, "actionPolicyId": [ "string" ] }, "allExtraDataFields": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "tags": [ "string" ], "entities": [ { "id": "string", "hostname": "string", "url": "string", "ip": "string", "mac": "string", "name": "string", "location": { "locationCountry": "string", "locationCity": "string", "locationState": "string", "locationLat": 0, "locationLon": 0 }, "email": "string", "windowsDomain": "string", "account": "string", "hash": "string", "impact": "string", "creationDate": 0, "modificationDate": 0, "json": "string", "domain": "string", "extraDataMaps": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "entityType": "SOURCEIP", "entitySuperTypes": [ "DOMAIN" ], "entityFamily": "SYSTEM", "direction": "NONE", "internalEntity": true } ], "commentsList": [ { "id": 0, "author": { "id": 0, "user": { "id": "string", "email": "string", "username": "string", "telephone": "string", "pwd": "string", "status": 0, "validation_token": "string", "defaultDomain": "string", "updateDate": "2022-07-19T09:00:49.052Z", "creationDate": "2022-07-19T09:00:49.052Z", "otpSecret": "string", "loginAttempts": 0, "recoveryAttempts": 0 }, "domain": { "id": "string", "name": "string", "status": 0, "type": 0, "updateDate": "2022-07-19T09:00:49.052Z", "creationDate": "2022-07-19T09:00:49.052Z", "subscribed": 0, "daysLeft": 0, "showLanding": true, "reseller": { "id": 0, "name": "string", "preferences": "string", "contactInformation": "string", "pricePlans": "string", "updateDate": "2022-07-19T09:00:49.052Z", "creationDate": "2022-07-19T09:00:49.052Z", "permPolicy": "string", "menuView": "string", "limits": "string", "groupId": 0, "webPreferences": "string" }, "groupId": 0, "alertsLastReseted": "2022-07-19T09:00:49.052Z" }, "lastTimeLogged": "2022-07-19T09:00:49.052Z", "status": 0, "creationDate": "2022-07-19T09:00:49.052Z", "updateDate": "2022-07-19T09:00:49.052Z", "pwd": "string", "validationToken": "string", "roleCustom": 0, "rolesCustom": [ 0 ], "externalId": "string", "owner": true, "alertsLastVisited": "2022-07-19T09:00:49.052Z" }, "msg": "string", "ack": "string", "creationDate": "2022-07-19T09:00:49.052Z", "updateDate": "2022-07-19T09:00:49.052Z", "elementType": "string", "elementId": "string", "domain": { "id": "string", "name": "string", "status": 0, "type": 0, "updateDate": "2022-07-19T09:00:49.052Z", "creationDate": "2022-07-19T09:00:49.052Z", "subscribed": 0, "daysLeft": 0, "showLanding": true, "reseller": { "id": 0, "name": "string", "preferences": "string", "contactInformation": "string", "pricePlans": "string", "updateDate": "2022-07-19T09:00:49.052Z", "creationDate": "2022-07-19T09:00:49.052Z", "permPolicy": "string", "menuView": "string", "limits": "string", "groupId": 0, "webPreferences": "string" }, "groupId": 0, "alertsLastReseted": "2022-07-19T09:00:49.052Z" }, "title": "string", "status": "string", "task": true } ], "alertLabel": "string" } ]

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

GET/v1/alerts/statistics

Get statistics from a set of alerts.

To perform this request, your Devo user must have at least the Alerts (view) permission assigned. Learn more about roles and permissions in this article.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

hours

integer

Indicate the number of hours back you want to analyze.

from

integer

Filters all alerts triggered after this date. This must by an epoch time in milliseconds.

type

string

Type of the results retrieved. Must be one of the following:

  • raw

  • funnel

  • list

The default value is raw.

filterName

string

Filter by alert name.

showAll

boolean

Set this parameter to true to retrieve all the triggered alerts, including the ones with false positive and closed status. The default value is false.

Example

Find below a request example in cURL language. This request will show statistics of the alerts triggered in the last 10 hours defined in the domain that corresponds to the given token. We are requesting the results to be shown as a funnel. Learn how to authorize your request in this article.

curl -H 'standAloneToken:YOUR_TOKEN' -X GET "https://api-us.devo.com/alerts/v1/alerts/statistics?hours=10&type=funnel"

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. Statistics for the matching alerts are shown.

{ "total": { "total": 2258, "enriched": 2258 }, "types": { "Model": { "total": 0, "enriched": 0 }, "Observation": { "total": 0, "enriched": 0 }, "Detection": { "total": 1185, "enriched": 1185 }, "Analytics": { "total": 1073, "enriched": 1073 } } }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

GET/v1/alerts/listStatus

To perform this request, your Devo user must have at least the Alerts (view) permission assigned. Learn more about roles and permissions in this article.

Get the status of a set of alerts.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

from

string

Filters all alerts triggered after this date. This must by an epoch time in milliseconds. The default value is 24 hours before the request.

Example

Find below a request example in cURL language. This request will show the statuses of the alerts triggered in the last 24 hours in the domain that corresponds to the given token. Learn how to authorize your request in this article.

curl -H 'standAloneToken:YOUR_TOKEN' -X GET "https://api-us.devo.com/alerts/v1/alerts/listStatus"

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. The list of statuses of the alerts within the indicated period is shown.

{ "87663927": 0, "87385381": 0, "87385380": 0, "87385383": 0, "87385382": 0, "87385377": 0, "87385376": 0, "87385379": 0, "87385378": 0, "87647513": 2, "87647512": 2, "87467282": 2, "87467283": 2, "87598352": 0, "87598353": 0, "87385375": 0, "87598354": 0, "87598355": 0, "87598356": 0, "87598357": 0, }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

PUT/v1/alerts/updateStatus

To perform this request, your Devo user must have at least the Alerts or Alerts_unread (manage) permission assigned. Learn more about roles and permissions in this article.

Update alert status by ID.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

id required

string

ID of the alert you want to update.

How can I get the ID of a triggered alert?

Triggered alert IDs are displayed in the Alerts area of the Devo platform. You can find them in the Alerts history table at the bottom of the Alerts dashboard tab. Learn more about this in Managing triggered alerts.

You will also get the IDs of the triggered alerts in a domain using GET/v1/alerts/list

status required

integer

New status of the alert. Must be one of the following (each number code corresponds to the status indicated next to it):

  • 0 (Unread)

  • 1 (Updated)

  • 2 (False Positive)

  • 100 (Watched)

  • 300 (Closed)

  • 800 (Suppressed)

Example

Find below a request example in cURL language. This request will change the status of the triggered alert with ID 123456 to Watched (100) in the domain that corresponds to the given token. Learn how to authorize your request in this article.

curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alerts/updateStatus?id=123456&status=100' --header 'standAloneToken:YOUR_TOKEN'

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. The status of the alert is updated.

{ "id": 123456, "domain": "demo", "priority": 5, "context": "my.alert.demo.SecIntSeveralDNS", "category": "my.context", "srcPort": null, "srcIp": null, "srcHost": null, "dstIp": null, "dstPort": null, "dstHost": null, "protocol": null, "username": "user@devo.com", "application": null, "engine": "pilot.my.alert.demo.SecIntSeveralDNS", "extraData": "{\"sourceIP\":\"%2F194.140.174.171\",\"totalservers\":\"71\",\"destinationCount\":\"71.00007511654165\",\"eventdate\":\"2023-04-05+07%3A00%3A00.0\"}", "alertDate": null, "status": 100, "ack_status_date": null, "createDate": 1680681772000, "updateDate": 1680683709802, "scaled": false, "digest": "c80cfdff6620d2a07f757690f8137ca17635479b", "uniquedigest": "a63d213133dd3f7756c265ea2c712fe8c0a4fc18", "postAlertAction": null, "contextLabel": null, "contextSubscription": null, "shouldSend": false, "alertOwner": null, "fullExtraData": null, "alertType": null, "alertMitreTactics": null, "alertMitreTechniques": null, "alertPriority": null, "alertDefinition": null, "allExtraDataFields": null, "tags": null, "entities": null, "commentsList": null, "integrations": null, "contexto": null }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

PUT/v1/alerts/updateStatusList

To perform this request, your Devo user must have at least the Alerts or Alerts_unread (manage) permission assigned. Learn more about roles and permissions in this article.

Update alert status in bulk.

 

Request

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

status required

integer

New status of the alerts. Must be one of the following (each number code corresponds to the status indicated next to it):

  • 0 (Unread)

  • 1 (Updated)

  • 2 (False Positive)

  • 100 (Watched)

  • 300 (Closed)

  • 800 (Suppressed)

Request body

The request JSON body must include the IDs of all the alerts you want to update, following this format:

["113451", "113452", "113453"]

Example

Find below a request example in cURL language. This request will change the status of the triggered alerts with IDs 123456 and 567890 to Watched (100) in the domain that corresponds to the given token. Learn how to authorize your request in this article.

curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alerts/updateStatusList?status=100' --header 'standAloneToken:YOUR_TOKEN' --data '["123456", "567890"]'

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. The status of the indicated alerts is updated.

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

PUT/v1/alerts/{alertID}/priority

To perform this request, your Devo user must have at least the Alerts or Alerts_unread (manage) permission assigned. Learn more about roles and permissions in this article.

Update the priority of a given alert.

 

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Definition

Parameter

Type

Definition

alertID required

integer

ID of the alert you want to update.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

Parameter

Type

Definition

priority required

number

Enter the new status of the alert. Values 1 to 10 are allowed, corresponding to the default values in the application:

  • Very low - 1

  • Low - 2, 3

  • Medium - 4, 5

  • High - 6, 7

  • Very high - 8, 9, 10

Example

Find below a request example in cURL language. This request will update the status of the alert with ID 123456 to High (6) in the domain that corresponds to the given token. Learn how to authorize your request in this article.

curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alerts/170480513/priority?priority=6' --header 'standAloneToken:YOUR_TOKEN'

 

Response

Check the list of available responses:

Code

Description

Code

Description

200

Successful response. Alert status updated.

{ "id": 123456, "domain": "myDomain", "priority": 6, "context": "my.alert.tutorials.myAlertEach.TcgKWDuG", "category": "my.context", "srcPort": null, "srcIp": null, "srcHost": null, "dstIp": null, "dstPort": null, "dstHost": null, "protocol": null, "username": "user@devo.com", "application": null, "engine": "pilot-4-pro-cloud-custom-aws-us-east-1", "extraData": "{...}", "alertDate": null, "status": 0, "ack_status_date": null, "createDate": 1679998567000, "updateDate": 1685437868049, "scaled": false, "digest": "c28250445d783ea79c3633f2e5d1b1e20f79e514", "uniquedigest": "0cba6b3dde174a41103edd6121911a1b7280bbb8", "postAlertAction": null, "contextLabel": null, "contextSubscription": null, "shouldSend": false, "alertOwner": null, "fullExtraData": null, "alertType": null, "alertMitreTactics": null, "alertMitreTechniques": null, "alertPriority": null, "alertDefinition": null, "allExtraDataFields": null, "tags": null, "entities": null, "commentsList": null, "integrations": null, "contexto": null }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.