Versions Compared

Old Version 50

changes.mady.by.user Borja Moro Moreno

Saved on

compared with

New Version Current

changes.mady.by.user Borja Moro Moreno

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
typeflat

...

Check the list of available endpoints and methods to work with alert definitions using the Alerts API:

Endpoints and methods

Description

Status
colourYellow
titleGET
 /alertDefinitions see below

Get the list of all the alerts defined in a domain.

Status
colourGreen
titlePOST
 /alertDefinitions see below

Create a new alert definition.

Status
colourGreen
titlePOST
 /alertDefinitions/batch see below

Create a set of new alert definitions.

Status
colourBlue
titlePUT
/alertDefinitions see below

Update a specific alert definition.

Status
colourBlue
titlePUT
/alertDefinitions/batch see below

Update a set of alert definitions.

Status
colourBlue
titlePUT
/alertDefinitions/status{id}/deliveryPolicy see below

Update the status of several alert Assign a sending policy to a specific alert definition.

Status
colourBlue
titlePUT
/alertDefinitions/status see below

Update the status of several alert definitions in bulk.

Status
colourRed
titleDELETE
 /alertDefinitions see below

Delete alert definitions in bulk.

Endpoints and methods

Anchor
path1
path1
GET /alertDefinitions

Get the list of all the alerts defined in a given domain.

Rw ui expands macro
Rw expand
titleRequest

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

page

number

Use these parameters to group your list of alerts by a specific number (size) and get only one of the resulting groups (page). This comes in handy if you need to get only a specific set of alerts and have a long list.

Note that the count of both the selected page and groups defined starts at 0, so for example, if you enter page=2 and size=5 and have 22 alerts in your list, the API will divide the list into groups of 5 alerts (0-4, 5-9, 10-14, 15-19, and 20-22) and will return the group of alerts 10-14.

size

number

nameFilter

string

Use this parameter to filter alerts by their names. You will only get alerts that contain the terms specified in their names. The filter is case insensitive.

idFilter

number

Indicate an alert definition ID to get only that specific alert. 

Note

How can I get the ID of an alert definition?

Alert definition IDs are not displayed in the Devo platform, so you should get them using this request to list all the alerts in the domain. IDs are included in the response.

You will also get the ID of an alert definition after creating it using POST /alertDefinitions

Example

Find below a couple of examples in cURL language.

For example, this request will return the first group of up to 2 alerts of your list of alert definitions in your domain:

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=2"

And this one will filter only alerts that include the term security in their names:

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=2&nameFilter=security"

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Successful response. Alerts' information retrieved.

Code Block
[
  {
    "id": "214554",
    "creationDate": 1678293187000,
    "name": "AWSWAFRuleDeletion",
    "message": "WAF rule or rulegroup deletion",
    "description": "WAF rule or rulegroup deletion",
    "categoryId": "2432",
    "subcategory": "lib.my.tutorials.AWS",
    "subcategoryId": "4452",
    "isActive": false,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
      "id": "67741",
      "nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
      "ownerEmail": "john.smith@devo.com",
      "querySourceCode": "from cloud.aws.cloudtrail where eq(eventName,\"DeleteRule\") or eq(eventName,\"DeleteRuleGroup\") group every 1m select count() as count",
      "priority": 3,
      "correlationTrigger": {
        "kind": "each",
        "externalPeriod": null,
        "externalOffset": null,
        "internalPeriod": null,
        "internalOffset": null
      }
    },
    "actionPolicyId": []
  },
  {
    "id": "214555",
    "creationDate": 1678293190000,
    "name": "AWSRootAccessConsoleLogin",
    "message": "Root access via console",
    "description": "Root access via console",
    "categoryId": "2432",
    "subcategory": "lib.my.tutorials.threats",
    "subcategoryId": "4453",
    "isActive": false,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
      "id": "67742",
      "nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
      "ownerEmail": "john.smith@devo.com",
      "querySourceCode": "from cloud.aws.cloudtrail where eventSource=\"signin.amazonaws.com\" where eventName=\"ConsoleLogin\" select str(jqeval(jqcompile(\".ConsoleLogin\"), responseElements)) as loginResponse select str(jqeval(jqcompile(\".MFAUsed\"), additionalEventData)) as mfaUsed group every 1m by userName,userIdentity_principalId,userIdentity_type,mfaUsed,loginResponse where userIdentity_type=\"Root\" where loginResponse=\"Success\" select count() as count",
      "priority": 2,
      "correlationTrigger": {
        "kind": "each",
        "externalPeriod": null,
        "externalOffset": null,
        "internalPeriod": null,
        "internalOffset": null
      }
    },
    "actionPolicyId": []
  }
]

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path2
path2
POST /alertDefinitions

Create a new alert definition.

Successful response. Alert created.

{ "id": "70736", "creationDate": 1604567644173,

Gradient alert example

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters of the new alert definition in the request body:

Parameter

Type

Definition

name required

string

This should be a descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

message

string

A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

description

string

The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

subcategory required

string

This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

Alerts created by Devo users are always created under the My Alerts category. The value entered here is the subcategory you will use to group this alert.

isActive

boolean

Set this parameter to true if you want to activate the alert after creation. Set it to false if you want the new alert to be disabled.

The default value is true.

alertCorrelationContext required

object

This JSON object includes the following parameters:

  • withSelectAll - (boolean) Set this parameter to false if you want to show only specific columns of the alert source query. The default value is true, which means that all the columns will be shown if you don’t include this parameter or you set it to true.

  • querySourceCode required  - (string) Specify the LINQ query whose events will launch the type of alert defined.

  • priority required - (integer) Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:

    • Very low - 0, 1

    • Low - 2, 3

    • Normal - 4, 5

    • High - 6, 7

    • Very high - 8, 9, 10

Note

When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

  • correlationTrigger required - (object) This JSON contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

    • each

    • several

    • low

    • inactivity

    • rolling

    • deviation

    • gradient

Check the table below for the parameters you can include for each alert type.

  • timezone - (string) This field indicates a timezone to adapt the query used to monitor alert conditions. Default value is GMT

  • locale - (string) Choose your required locale. Required format is language code and region code separated by an underscore, following this: ([a-z]){2}_([A-Z]){2} Default value is en_US

Depending on the type of alert specified, you are allowed to include different parameters:

Alert type

Parameters

Description

each

Note

The parameters for the each type alerts are mandatory if the specified query includes subqueries.

However, not every query containing a subquery is allowed. Learn more about this in the section below.

Note

Note that if you use this method and include a subquery, the minimum grouping time is 1 minute, and the maximum is 100 days.

Note

When the External offset parameter the external period (time grouping in the main query or 1 minute when not specified) is less than 1 day, the ratio between internal period/external offset period must not exceed 120. A ratio above 120 will prevent the alert from being created and will return an error.

  • Valid ratio → external offset period 1m, internal period 2h(=120m) → 120/1 → 120

  • Valid ratio → external offset period 2h, internal period 5d(=120h) → 120/2 → 60

  • Invalid ratio → external offset period 1m, internal period 3h(=180m) → 180/1 → 180

externalOffset

It is used to move the main query time range backward in time. It must be expressed in milliseconds.

For example: if the main query time range is [now()-1h, now()] with an externalOffset of 2 days, the time range would be [now() -1h -2d, now() - 2d]

The maximum time range allowed is 8640000000 milliseconds (up to 100 days).

internalPeriod

It is used to set the subquery time range. It must be expressed in milliseconds.

For example: for an internalPeriod of 10 days, the subquery time range would be [now() - 10d, now()]

The minimum allowed temporal 60000, and the maximum is 8640000000 (from 1 min to 100 days).

internalOffset

It is used to move the subquery time range backward in time. It must be expressed in milliseconds.

For example: if the subquery time range is [now()-10d, now()] with an internalOffset of 2 days, the time range would be [now() -12d, now() - 2d]

The maximum time range allowed is 8640000000 milliseconds (up to 100 days).

several

period

Specify how frequently you want Determines the duration of the intervals used by the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a positive integer number.

keys

You must specify one or more fields to keep track of their unique values and check against the designated threshold to trigger the alert. You can choose from any column in the table, except the eventdate.

low

period

Specify how frequently you want Determines the duration of the intervals used by the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a non-negative positive integer number.

inactivity

period

Specifies the duration used by the system to determine the occurrence of inactivity.

It must be indicated in milliseconds. The minimal value is 5 minutes and the maximum value is 30 days.

keys

You must specify one or more fields to keep track of their unique values, which will be checked against the full series of values in the previous period to trigger the alert. You can choose from any column in the table, except the eventdate.

rolling

Note

When the period parameter is less than 1 day, the ratio between backPeriod/period must not exceed 120. A ratio above 120 will prevent the alert from being created and will return an error.

  • Valid ratio → period 1m, backPeriod 2h(=120m) → 120/1 → 120

  • Valid ratio → period 2h, backPeriod 5d(=120h) → 120/2 → 60

  • Invalid ratio → period 1m, backPeriod 3h(=180m) → 180/1 → 180

period

Specifies how frequently you want the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 60 seconds and the maximum value is 100 days.

backPeriod

Specifies how far in the past the search extends.

deviation

threshold

Specifies the proportions of the deviation from the median, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumn

Specify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.

gradient

threshold

Specifies the proportions of the deviation from the previous value, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumn

Specify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.

Learn more about each type of alert, their parameters, and how to set them in Alert trigger methods.

Defining alerts with queries that include subqueries

As specified in the required parameters for the each-type alert above, users can generate alerts based on queries that contain subqueries by adding some required extra parameters. However, not every query is allowed.

Take the following into account when defining your source query:

  • Queries must not include nested subqueries.

  • Queries must not include a fixed time range in the subquery.

  • Queries must not include a temporal grouping in the subquery.

  • Tables such as my.lookuplist tables cannot be used in subqueries. Learn more about lookups in Data enrichment(more about them here) can be used with some limitations :

    • Only inner queries can contain them.

    • The specified period cannot be less 24 hours.

See the following table to check examples of valid and not allowed query formats:

Query

Allowed?

Code Block
from T1

This query does not include any subquery, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2          
      where y in (              
        from T3          
      )  
  )

This query includes nested subqueries, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2      
    where 100 <= eventdate < 200  
  )

This query includes a fixed time range in its subquery, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2      
    group every 10m  
  )

This query includes a temporal grouping in its subquery, so it is not allowed.

Code Block
from T1    
  where x in (        
    from T2    
  )

This query has neither a group nor a time range in its subquery, so it is allowed.

Code Block
from T1    
  group by x every 10m    
  where x in (        
    from T2    
  )

This query has a temporal grouping, but it is not included in the subquery. Therefore, it is allowed.

Examples

Find below some examples of the request body for each type of alert in cURL language, including their specific parameters.

Learn how to authorize your request in this article.

Each alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertEach",
    "message": "Alert definition message created with alerting API",
    "description": "Alert definition description created with alerting API",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}'

Each alert example with subquery

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition with subquery",
    "message": "Alert definition with subquery",
    "description": "Alert definition with subquery",
    "subcategory": "Subcategory/Each",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/home\"), eq(type, \"request\") where username in (from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/m2search\"), eq(type, \"request\") select username) select username, userid, sessionid, locale, userAgent",
        "priority": 1,
        "correlationTrigger": {
            "kind": "each",
            "externalOffset": 0,
            "internalPeriod": 60000,
            "internalOffset": 1000
        }
    }
}'

Several alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertSeveral",
    "message": "Alert definition created with alerting API / Several",
    "description": "Alert definition long description / Several",
    "subcategory": "Subcategory/Several",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 3,
        "correlationTrigger": {
            "kind": "several",
            "period": 300000,
            "threshold": 10000
        }
    }
}'

Low alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertLow",
    "message": "Alert definition created with alerting API / Low",
    "description": "Alert definition long description / Low",
    "subcategory": "Subcategory/Low",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 3,
        "correlationTrigger": {
            "kind": "low",
            "period": 300000,
            "threshold": 1
        }
    }
}'

Rolling Inactivity alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / RollingInactivity",
    "message": "Alert definition created with alerting API / RollingInactivity",
    "description": "Alert definition long description / RollingInactivity",
    "subcategory": "Subcategory/RollingInactivity",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every -",
        "priority": 45,
        "correlationTrigger": {
            "kind": "rollinginactivity",
            "period": 3000001800000,
            "backPeriodkeys": 3600000["username"]
        }
    }
}'

Deviation Rolling alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / DeviationRolling",
    "message": "Alert definition created with alerting API / DeviationRolling",
    "description": "Alert definition long description / DeviationRolling",
    "subcategory": "Subcategory/DeviationRolling",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count-",
        "priority": 54,
        "correlationTrigger": {
            "kind": "deviationrolling",
            "thresholdperiod": 40300000,
            "absolutebackPeriod": true,
            "aggregationColumn": [ "count" ]3600000
          }
    }
}'

Gradient Deviation alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / GradientDeviation",
    "message": "Alert definition created with alerting API / GradientDeviation",
    "description": "Alert definition long description / GradientDeviation",
    "subcategory": "Subcategory/GradientDeviation",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
        "priority": 15,
        "correlationTrigger": {
            "kind": "gradientdeviation",
            "threshold": 40,
            "absolute": falsetrue,
            "aggregationColumn": [ "count" ]
        }
    }
}'
Rw expand
titleResponse

Code

Description

200

Code Block
Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert
_API_each
 definition / Gradient",
    "message": "
$eventdate
Alert
$username
definition
-
created
$count
with
-
alerting API / Gradient",
    "description": "Alert
created
definition
by
long
API",
description /
"categoryId": "7"
Gradient",
    "subcategory": "
lib.my.testfake.AlertAPI_v660
Subcategory/Gradient",
    "
subcategoryId
alertCorrelationContext":
"133",
{
"isActive": true,
    
"
isFavorite
querySourceCode":
false, "isAlertChain": false, "alertCorrelationContext": {
"from siem.logtrust.web.activity group every 5m by domain select count() as count",
        
"
id
priority":
"622"
1,
        "
nameId
correlationTrigger":
"my.alert.testfake.Alert_API_each_Staging_1604567643224",
{
"ownerEmail":
"john@xx.com",
"querySourceCode
"kind": "gradient"
from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count", "priority": 5,
,
            "threshold": 40,
            "
correlationTrigger
absolute":
{
false,
            "
kind
aggregationColumn": [ "
each
count" ]
        }
    }
,
"actionPolicyId": [] }

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

...

Create a set of new alert definitions.

Successful response. Set of alert definitions created.

[ { "context": { "headers": {}, "configuration": null, "entity": { "id": "226687",
Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters of the alerts to be created in the request body.

Check the parameters defined in POST /alertDefinitions to learn how to define your set of alert definitions. Add all the alerts you want to define in an array as in the example below.

Example

Find below a example in cURL language. This is a body example where we are defining 2 different alert definitions:

Code Block
curl --location --request POST 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {
        "name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
}'
Rw expand
titleResponse

Code

Description

200

Successful response. Alert created.

Code Block
{
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "$eventdate $username - $count - API",
    "description": "Alert created by API",
    "categoryId": "7",
    "subcategory": "lib.my.testfake.AlertAPI_v660",
    "subcategoryId": "133",
    "isActive": true,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "
description
id": "
Alert definition long description / Gradient
622",
        "
subcategory
nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "
alertCorrelationContext
ownerEmail":
{
"john@xx.com",
        
"querySourceCode": "from siem.logtrust.web.activity
",
 group every 1m by username, url every 1m select count() as
"priority": 1
count",
        
"
correlationTrigger
priority":
{
5,
"kind": "each" } } }, { "name": "myAlertEach3",
"correlationTrigger": {
            "
message
kind": "
Alert definition created with alerting API / Gradient",
each"
"description": "Alert definition long description / Gradient"
}
    },
    
"
subcategory
actionPolicyId":
"alert", "alertCorrelationContext": { "querySourceCode": "from siem.logtrust.web.activity", "priority": 1, "correlationTrigger": { "kind": "each" } } } ]'

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Code Block
[]
}

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path23
path23
POST /alertDefinitions/batch

Create a set of new alert definitions.

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters of the alerts to be created in the request body.

Check the parameters defined in POST /alertDefinitions to learn how to define your set of alert definitions. Add all the alerts you want to define in an array as in the example below.

Example

Find below a example in cURL language. This is a body example where we are defining 2 different alert definitions:

Code Block
curl --location --request POST 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {
        "
creationDate": 1685441802355, "
name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "
categoryId
subcategory": "
2432
alert",
        "
subcategory
alertCorrelationContext":
"lib.my.tutorials.alert",
 {
            "
subcategoryId
querySourceCode": "
4521
from siem.logtrust.web.activity",
            "
isActive
priority":
true
1,
            "
isFavorite
correlationTrigger":
false,
{
"isAlertChain":
false,
      "kind": "each"
"alertCorrelationContext":
{
          }
"id":
"78228",
       }
"nameId": "my.alert.tutorials.myAlertEach2"
 },
    {
        "
ownerEmail
name": "
user@devo.com
myAlertEach3",

        "
querySourceCode
message": "
from siem.logtrust.web.activity", "priority": 1
Alert definition created with alerting API / Gradient",
        
"
correlationTrigger
description":
{
"Alert definition long description / Gradient",
        "
kind
subcategory": "
each
alert",
        
"
externalPeriod
alertCorrelationContext":
null,
{
            "
externalOffset
querySourceCode":
null
"from siem.logtrust.web.activity",
            "
internalPeriod
priority":
null
1,
            "
internalOffset
correlationTrigger":
null
{
}
     "kind": "each"
},
"actionPolicyId": []
 }
},
  }
"entityType": "com.devo.config.api.model.AlertDefinition", 
}
]'

Learn how to authorize your request in this article.

Rw expand
titleResponse

...

Update a specific alert definition in your domain.

alertCorrelationContext

This JSON object includes the following parameters:

  • withSelectAll - (boolean) Set this parameter to false if you want to show only specific columns of the alert source query. The default value is true, which means that all the columns will be shown if you don't include this parameter or you set it to true.

    • querySourceCode - (string) Specify the LINQ query whose events will launch the type of alert defined.priority- (integer) Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:

    • Very low - 0, 1

    • Low - 2, 3

    • Normal - 4, 5

    • High - 6, 7

    • Very high - 8, 9, 10

    Rw ui expands macro
    Rw expand
    titleRequest

    Request body

    You must specify the parameters to be updated in the request body.

    Parameter

    Type

    Definition

    id required

    string

    Specify the ID of the alert definition that you want to update.

    Note

    How can I get the ID of an alert definition?

    Alert definition IDs are not displayed in the Devo platform, so you should get them using GET /alertDefinitions to list all the alerts in the domain. IDs are included in the response.

    You will also get the ID of an alert definition after creating it using POST /alertDefinitions

    name required

    string

    Descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

    Note

    Non-editable parameter

    Note that the name parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

    message

    string

    A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

    You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

    description

    string

    The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

    You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

    subcategory required

    string

    This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

    Alerts created by Devo users are always created under the My Alerts category.

    Note

    Non-editable parameter

    Note that the subcategory parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

    isActive

    boolean

    Set this parameter to true if you want to activate the alert after creation. Set it to false if you want the new alert to be disabled.

    The default value is true.

    object

    Note

    When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

    correlationTrigger- (object) This JSON contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

    • each

    • several

    • low

    • rolling

    • deviation

    • gradient

    Check the table below for the parameters you can include for each alert type.

    • timezone - (string) This field indicates a timezone to adapt the query used to monitor alert conditions. Default value is GMT

    • locale - (string) Choose your required locale. Required format is language code and region code separated by an underscore, following this: ([a-z]){2}_([A-Z]){2} Default value is en_US

    Example

    Find below a couple of examples in cURL language.

    This is a body example where we are modifying the message and description of an alert previously created:

    Code Blockcurl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '

    Code

    Description

    200

    Successful response. Set of alert definitions created.

    Code Block
    [
  {
    "entityAnnotationscontext": [],{
      "entityStreamheaders": {},
        "committedconfiguration": falsenull,
 
      "closedentity": false{
      },       "lengthLongid": -1"226687",
        "mediaTypecreationDate": null1685441802355,
        "responseCookiesname": {},"myAlertEach2",
        "committedmessage": false,"Alert definition created with alerting API / Gradient"requestCookies": {},,
        "stringHeadersdescription": {},"Alert definition long description /   "allowedMethods": [],Gradient",
        "entityTagcategoryId": null"2432",
        "acceptableMediaTypessubcategory": ["lib.my.tutorials.alert",
        {
 "subcategoryId": "4521",
        "typeisActive": "*"true,
 
        "subtypeisFavorite": "*"false,
          "parametersisAlertChain": {}false,
          "qualityalertCorrelationContext": 1000,{
          "wildcardTypeid": true"78228",
          "wildcardSubtypenameId": true"my.alert.tutorials.myAlertEach2",
        }  "ownerEmail": "user@devo.com",
   ],       "acceptableLanguagesquerySourceCode": [ "from siem.logtrust.web.activity",
          "*priority": 1,
     ],       "entityClasscorrelationTrigger": "com.devo.config.api.model.AlertDefinition",
 {
    "links": [],       "datekind": null"each",
      "lastModified": null,       "lengthexternalPeriod": -1null,
      "location": null,
      "languageexternalOffset": null,
    },        "statusinternalPeriod": 200null,
    "entity": {       "idinternalOffset": "226687",null
       "creationDate": 1685441802355,  }
    "name": "myAlertEach2",    },
        "messageactionPolicyId": "Alert[]
definition created with alerting API / Gradient"},
      "descriptionentityType": "Alert definition long description / Gradient""com.devo.config.api.model.AlertDefinition",
      "entityAnnotations": [],
      "categoryIdentityStream": "2432",{
        "subcategorycommitted": "lib.my.tutorials.alert"false,
        "subcategoryIdclosed": "4521",false
      "isActive": true},
      "isFavoritelengthLong": false-1,
      "isAlertChainmediaType": falsenull,
      "alertCorrelationContextresponseCookies": {
 },
      "idcommitted": "78228"false,
 
      "nameIdrequestCookies": "my.alert.tutorials.myAlertEach2"{},
        "ownerEmailstringHeaders": "user@devo.com",
 {},
      "querySourceCodeallowedMethods": [],
      "from siem.logtrust.web.activity",
 entityTag": null,
      "priorityacceptableMediaTypes": 1, [
        {
          "correlationTriggertype": {"*",
          "kindsubtype": "each*",
          "externalPeriodparameters": null{},
          "externalOffsetquality": null1000,
          "internalPeriodwildcardType": nulltrue,
          "internalOffsetwildcardSubtype": nulltrue
        }
      }],
      "actionPolicyIdacceptableLanguages": []

   },     "cookies": {}*"
      ],
      "statusInfoentityClass": "OKcom.devo.config.api.model.AlertDefinition",
      "metadatalinks": {}[],
      "mediaTypedate": null,
      "stringHeaderslastModified": {}null,
      "allowedMethodslength": []-1,
      "entityTaglocation": null,
     "links": [],
    "date": null,
    "lastModified": null,
    "length": -1,
    "location": null,
    " "language": null,
    "headers": {}
  },
  {     "context": {
      "headers": {},
 
    "configurationstatus": null200,
      "entity": {
 
      "id": "226688226687",
        "creationDate": 16854418065271685441802355,
        "name": "myAlertEach3myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "categoryId": "2432",
 
      "subcategory": "lib.my.tutorials.alert",
        "subcategoryId": "4521",
 
      "isActive": true,
 
      "isFavorite": false,
 
      "isAlertChain": false,
        ""alertCorrelationContext": {
          "id": "7822978228",
 
        "nameId": "my.alert.tutorials.myAlertEach3myAlertEach2",
          "ownerEmail": "user@devo.com",
          "querySourceCode": "from siem.logtrust.web.activity",
 
        "priority": 1,
          "correlationTrigger": {
            "kind": "each",
            "externalPeriod": null,
            "externalOffset": null,

           "internalPeriod": null,
            "internalOffset": null
 
        }
 
      },
 
      "actionPolicyId": []

     },
      "entityTypecookies": "com.devo.config.api.model.AlertDefinition"{},
      "entityAnnotationsstatusInfo": [],
 "OK",
    "entityStreammetadata": {},
        "committedmediaType": falsenull,

       "closedstringHeaders": false{},
      }"allowedMethods": [],
      "lengthLongentityTag": -1null,
 
    "mediaTypelinks": null[],
 
    "responseCookiesdate": {}null,
      "committedlastModified": falsenull,
      "requestCookieslength": {}-1,
      "stringHeaderslocation": {}null,
      "allowedMethodslanguage": []null,
 
    "entityTagheaders": null{}
  },
  {
    "acceptableMediaTypescontext": [{
      "headers":  {
   {},
      "typeconfiguration": "*",
   null,
      "subtypeentity": "*",
{
         "parametersid": {}"226688",

         "qualitycreationDate": 10001685441806527,
 
        "wildcardTypename": true"myAlertEach3",
          "wildcardSubtypemessage": true"Alert definition created with alerting API / Gradient",
 }       ],
      "acceptableLanguages": ["description": "Alert definition long description / Gradient",
        "categoryId": "*2432",
      ],       "entityClasssubcategory": "comlib.devomy.config.api.model.AlertDefinitiontutorials.alert",
        "linkssubcategoryId": [],"4521",
        "dateisActive": nulltrue,
        "lastModifiedisFavorite": nullfalse,
        "lengthisAlertChain": -1false,
        "locationalertCorrelationContext": {
   null,       "languageid": "78229",
null     },     "statusnameId": 200"my.alert.tutorials.myAlertEach3",
    "entity": {
      "idownerEmail": "226688user@devo.com",
          "creationDatequerySourceCode": 1685441806527 "from siem.logtrust.web.activity",
          "namepriority": "myAlertEach3",1,
          "messagecorrelationTrigger": "Alert{
definition created with alerting API / Gradient",       "descriptionkind": "each"Alert,
 definition long description / Gradient",       "categoryIdexternalPeriod": "2432"null,
      "subcategory": "lib.my.tutorials.alert",
       "subcategoryIdexternalOffset": "4521"null,
      "isActive": true,
      "isFavoriteinternalPeriod": falsenull,
      "isAlertChain": false,
      "alertCorrelationContextinternalOffset": {null
        "id": "78229", }
       "nameId": "my.alert.tutorials.myAlertEach3" },
        "ownerEmailactionPolicyId": "user@devo.com",
  []
      },
      "querySourceCodeentityType": "from siem.logtrust.web.activity",
 com.devo.config.api.model.AlertDefinition",
      "priorityentityAnnotations": 1[],
        "correlationTriggerentityStream": {

         "kindcommitted": "each"false,
          "externalPeriodclosed": null,false
      },
      "externalOffsetlengthLong": null-1,
      "mediaType": null,
      "internalPeriodresponseCookies": null{},
          "internalOffsetcommitted": nullfalse,
      "requestCookies": {},
}      "stringHeaders": {},
      "actionPolicyIdallowedMethods": [],
    },     "cookiesentityTag": {}null,
      "statusInfoacceptableMediaTypes": "OK",[
       "metadata": {},
          "mediaTypetype": null"*",
    "stringHeaders": {},     "allowedMethodssubtype": []"*",
    "entityTag": null,     "linksparameters": []{},
    "date": null,     "lastModifiedquality": null1000,
    "length": -1,     "locationwildcardType": nulltrue,
    "language": null,     "headerswildcardSubtype": true
{}   }
]

    400

    Error in request.

    401

    Unauthorized request.

    403

    Forbidden request.

    405

    Method not allowed.

    500

    Server error and Java exception.

    ...

         }
      ],
      "acceptableLanguages": [
        "*"
      ],
      "entityClass": "com.devo.config.api.model.AlertDefinition",
      "links": [],
      "date": null,
      "lastModified": null,
      "length": -1,
      "location": null,
      "language": null
    },
    "status": 200,
    "entity": {
      "id": "226688",
      "creationDate": 1685441806527,
      "name": "myAlertEach3",
      "message": "Alert definition created with alerting API / Gradient",
      "description": "Alert definition long description / Gradient",
      "categoryId": "2432",
      "subcategory": "lib.my.tutorials.alert",
      "subcategoryId": "4521",
      "isActive": true,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "78229",
        "nameId": "my.alert.tutorials.myAlertEach3",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 1,
        "correlationTrigger": {
          "kind": "each",
          "externalPeriod": null,
          "externalOffset": null,
          "internalPeriod": null,
          "internalOffset": null
        }
      },
      "actionPolicyId": []
    },
    "cookies": {},
    "statusInfo": "OK",
    "metadata": {},
    "mediaType": null,
    "stringHeaders": {},
    "allowedMethods": [],
    "entityTag": null,
    "links": [],
    "date": null,
    "lastModified": null,
    "length": -1,
    "location": null,
    "language": null,
    "headers": {}
  }
]

    400

    Error in request.

    401

    Unauthorized request.

    403

    Forbidden request.

    405

    Method not allowed.

    500

    Server error and Java exception.

    Anchor
    path3
    path3
    PUT /alertDefinitions

    Update a specific alert definition in your domain.

    curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    Rw ui expands macro
    Rw expand
    titleRequest

    Request body

    You must specify the parameters to be updated in the request body.

    Parameter

    Type

    Definition

    id required

    string

    Specify the ID of the alert definition that you want to update.

    Note

    How can I get the ID of an alert definition?

    Alert definition IDs are not displayed in the Devo platform, so you should get them using GET /alertDefinitions to list all the alerts in the domain. IDs are included in the response.

    You will also get the ID of an alert definition after creating it using POST /alertDefinitions

    name required

    string

    Descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

    Note

    Non-editable parameter

    Note that the name parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

    message

    string

    A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

    You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

    description

    string

    The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

    You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

    subcategory required

    string

    This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

    Alerts created by Devo users are always created under the My Alerts category.

    Note

    Non-editable parameter

    Note that the subcategory parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

    alertCorrelationContext

    object

    This JSON object includes the following parameters:

    • withSelectAll - (boolean) Set this parameter to false if you want to show only specific columns of the alert source query. The default value is true, which means that all the columns will be shown if you don't include this parameter or you set it to true.

    • querySourceCode - (string) Specify the LINQ query whose events will launch the type of alert defined.

    • priority- (integer) Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:

      • Very low - 0, 1

      • Low - 2, 3

      • Normal - 4, 5

      • High - 6, 7

      • Very high - 8, 9, 10

    Note

    When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

    • correlationTrigger- (object) This JSON contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

      • each

      • several

      • low

      • rolling

      • deviation

      • gradient

    Check the table below for the parameters you can include for each alert type.

    • timezone - (string) This field indicates a timezone to adapt the query used to monitor alert conditions. Default value is GMT

    • locale - (string) Choose your required locale. Required format is language code and region code separated by an underscore, following this: ([a-z]){2}_([A-Z]){2} Default value is en_US

    Example

    Find below a couple of examples in cURL language.

    This is a body example where we are modifying the message and description of an alert previously created:

    Code Block
    curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "id": "70736",
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}'

    And in this case, we are updating the same alert and transforming it into a Several type alert:

    Code Block
    curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "id": "70736"
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where username = "user@devo.com"",
        "priority": 3,
        "correlationTrigger": {
            "kind": "several",
            "period": 300000,
            "threshold": 10000
        }
    }
}'

    Learn how to authorize your request in this article.

    Rw expand
    titleResponse

    Code

    Description

    200

    Successful response. Alert updated.

    Code Block
    {
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "categoryId": "7",
    "subcategory": "
    alert
    lib.my.testfake.AlertAPI_v660",
    "
    alertCorrelationContext
    subcategoryId":
    {
    "133",
    "isActive": true,
    "
    querySourceCode
    isFavorite":
    "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
    false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "
    priority
    id":
    5
    "622",
        "
    correlationTrigger
    nameId":
    {
     "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "ownerEmail": "john@xx.com",
        "
    kind
    querySourceCode": "
    each" } } }'

    And in this case, we are updating the same alert and transforming it into a Several type alert:

    Code Block
    from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
        "priority": 5,
        "
    id
    correlationTrigger":
    "70736"
     {
            "
    name
    kind": "
    Alert_API_
    each"
    ,
    
        }
    "message":
    "New
    message"
    },
    "
    description
    actionPolicyId":
    "New description", "subcategory": "alert", "alertCorrelationContext": { "querySourceCode": "from siem.logtrust.web.activity where username = "user@devo.com"", "priority": 3, "correlationTrigger": { "kind": "several", "period": 300000, "threshold": 10000 } } }'

    Learn how to authorize your request in this article.

    Rw expand
    titleResponse

    Code

    Description

    200

    Successful response. Alert updated.

    Code Block
    {[]
}

    400

    Error in request.

    401

    Unauthorized request.

    403

    Forbidden request.

    405

    Method not allowed.

    500

    Server error and Java exception.

    Anchor
    path35
    path35
    PUT /alertDefinitions/batch

    Update a set of alert definitions in your domain.

    Rw ui expands macro
    Rw expand
    titleRequest

    Request body

    You must specify the parameters to be updated in the request body.

    Check the parameters defined in PUT /alertDefinitions to learn how to update your set of alert definitions. Add all the alerts you want to update in an array as in the example below.

    Example

    Find below a example in cURL language. This is a body example where we are updating 2 different alert definitions:

    Code Block
    curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {
        "id": "
    70736
    123456"
    ,
    "creationDate":
    1604567644173,
         "name": "
    Alert_API_each
    myAlertEach2",
        "message": "
    New message",
    Alert definition created with alerting API / Gradient",
        "description": "
    New
    Alert definition long description / Gradient",
        "
    categoryId
    subcategory": "
    7
    alert",
        "
    subcategory
    alertCorrelationContext":
    "lib.my.testfake.AlertAPI_v660",
     {
            "
    subcategoryId
    querySourceCode": "
    133",
    from siem.logtrust.web.activity",
    "isActive":
    true,
         "
    isFavorite
    priority":
    false
    1,
    "isAlertChain": false,
            "
    alertCorrelationContext
    correlationTrigger": {
    "id":
    "622", 
          "
    nameId
    kind": "
    my.alert.testfake.Alert_API_
    each
    _Staging_1604567643224
    "
    ,
    "ownerEmail":
    "john@xx.com",
      }
    "querySourceCode":
    "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
     }
    },
    {
        
    "
    priority
    id":
    5,
    "567890"
        "
    correlationTrigger
    name":
    {
    "myAlertEach3",
        
    "
    kind
    message": "
    each"
    Alert definition created with alerting API / Gradient",
    }
    },
      "description":
    "actionPolicyId": [] }

    400

    Error in request.

    401

    Unauthorized request.

    403

    Forbidden request.

    405

    Method not allowed.

    500

    Server error and Java exception.

    ...

    Update a set of alert definitions in your domain.

    Rw ui expands macro
    Rw expand
    titleRequest

    Request body

    You must specify the parameters to be updated in the request body.

    Check the parameters defined in PUT /alertDefinitions to learn how to update your set of alert definitions. Add all the alerts you want to update in an array as in the example below.

    Example

    Find below a example in cURL language. This is a body example where we are updating 2 different alert definitions:

    Code Block
    curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {"Alert definition long description / Gradient",
        "subcategory": "alert",
        "alertCorrelationContext": {
            "querySourceCode": "from siem.logtrust.web.activity",
            "priority": 1,
            "correlationTrigger": {
               "idkind": "123456each"
        "name": "myAlertEach2",   }
     "message": "Alert definition created}
with alerting API / Gradient",
}
]'

    Learn how to authorize your request in this article.

    Rw expand
    titleResponse

    Code

    Description

    200

    Successful response. Set of alert definitions updated.

    Code Block
    [
  {
    "
    description
    context": {
    "Alert
    definition
    long
    description
    /
    Gradient", 
    "headers": {},
      
    "
    subcategory
    configuration":
    "alert"
    null,
      
    "
    alertCorrelationContext
    entity": {
        "id": "123456",
        "
    querySourceCode
    creationDate":
    "from siem.logtrust.web.activity"
    1678293190000,
        
    "
    priority
    name":
    1
    "myAlertEach2",
    
        
    "
    correlationTrigger
    message":
    {
    "Alert definition created with alerting API / Gradient",
        "
    kind
    description": "
    each"
    Alert definition long description / Gradient",
    }
     "categoryId": "2432",
    }
    }
    "subcategory": "lib.my.tutorials.threats",
    {
        
    "
    id
    subcategoryId": "
    567890
    4453",
        "
    name
    isActive":
    "myAlertEach3"
    false,
        "
    message
    isFavorite": false,
    "Alert
    definition
    created
    with
    alerting
    API
    /
    Gradient
    "isAlertChain": false,
        "
    description
    alertCorrelationContext":
    "Alert definition long description / Gradient",
    {
          "id": "67742",
          "
    subcategory
    nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
          "
    alertCorrelationContext
    ownerEmail":
    {
    "user@devo.com",
          
    "querySourceCode": "from siem.logtrust.web.activity",
          
    "priority": 1,
    
          
    "correlationTrigger": {
            
    "kind": "each"
    }
    ,
    } } ]'

    Learn how to authorize your request in this article.

    Rw expand
    titleResponse

    Code

    Description

    200

    Successful response. Set of alert definitions updated.

    Code Block
    [   {     "contextexternalPeriod": {
null,
     "headers": {},
      "configurationexternalOffset": null,
      "entity": {
        "idinternalPeriod": "123456"null,

       "creationDate": 1678293190000,           "nameinternalOffset": "myAlertEach2", null
          "message": "Alert definition created with alerting API / Gradient"}
        },
        "descriptionactionPolicyId": "Alert[]
definition long description / Gradient",  },
      "categoryIdentityType": "2432com.devo.config.api.model.AlertDefinition",
 
      "subcategoryentityAnnotations": "lib.my.tutorials.threats"[],
        "subcategoryIdentityStream": "4453",{
        "isActivecommitted": false,
        "isFavoriteclosed": false,
      },
      "isAlertChainlengthLong": false-1,
 
      "alertCorrelationContextmediaType": { null,
      "responseCookies": {},
      "idcommitted": "67742"false,
          "nameIdrequestCookies": "my.alert.tutorials.AWSRootAccessConsoleLogin"{},
      "acceptableMediaTypes": [
       "ownerEmail": "user@devo.com", {
          "querySourceCodetype": "from siem.logtrust.web.activity*",
          "prioritysubtype": 1"*",
          "correlationTriggerparameters": {
},
           "kindquality": "each"1000,
            "externalPeriodwildcardType": nulltrue,
            "externalOffsetwildcardSubtype": null,true
            "internalPeriod": null,}
      ],
      "internalOffsetallowedMethods": null[],
      "entityTag": null,
  }    "acceptableLanguages": [
   },
        "actionPolicyId*":
[]       }],
      "entityTypeentityClass": "com.devo.config.api.model.AlertDefinition",
      "entityAnnotationsstringHeaders": []{},
      "entityStreamlinks": {
        "committed": false,
 [],
      "closeddate": falsenull,
      "lastModified": }null,
      "lengthLonglength": -1,
      "mediaTypelocation": null,
      "responseCookieslanguage": {null
    },

     "committedstatus": false200,
 
    "requestCookiescookies": {},

     "acceptableMediaTypesallowedMethods": [],
    "entityTag": null,
  {           "type"statusInfo": "*OK",
    "stringHeaders": {},
    "subtypemediaType": "*"null,
    "metadata": {},
    "parameterslinks": {}[],
    "date": null,
    "qualitylastModified": 1000null,
    "entity": {
      "wildcardTypeid": true,"123456",
      "creationDate": 1678293190000,
      "wildcardSubtypename": true"myAlertEach2",
      "message": "Alert }definition created with alerting  API / ]Gradient",
      "allowedMethodsdescription": [],"Alert definition long description /   "entityTag": nullGradient",
      "acceptableLanguagescategoryId": ["2432",
       "subcategory": "*"
      ]lib.my.tutorials.threats",
      "entityClasssubcategoryId": "com.devo.config.api.model.AlertDefinition4453",
      "stringHeadersisActive": {}false,
      "linksisFavorite": []false,
      "dateisAlertChain": nullfalse,
      "lastModifiedalertCorrelationContext": null,{
        "lengthid": -1"67742",
        "locationnameId": null"my.alert.tutorials.AWSRootAccessConsoleLogin",
        "languageownerEmail": null"user@devo.com",
    },
    "statusquerySourceCode": 200,"from siem.logtrust.web.activity",
        "cookiespriority": {}1,
        "allowedMethodscorrelationTrigger": [],{
    "entityTag": null,     "statusInfokind": "OKeach",
    "stringHeaders": {},     "mediaTypeexternalPeriod": null,
    "metadata": {},     "linksexternalOffset": []null,
    "date": null,     "lastModifiedinternalPeriod": null,
    "entity": {       "idinternalOffset": "123456",null
      "creationDate": 1678293190000, }
     "name": "myAlertEach2" },
      "messageactionPolicyId": "Alert[]
definition created with alerting API / Gradient",
  },
    "descriptionlength": "Alert-1,
definition long description / Gradient"location": null,
      "categoryIdlanguage": "2432"null,
      "subcategoryheaders": "lib.my.tutorials.threats"{}
  },
  {
    "subcategoryIdcontext": "4453",{
      "isActiveheaders": false{},
      "isFavoriteconfiguration": falsenull,
      "isAlertChainentity": {
false,        "alertCorrelationContextid": {"567890",
        "idcreationDate": "67742"1678293187000,
        "nameIdname": "my.alert.tutorials.AWSRootAccessConsoleLoginmyAlertEach3",
        "ownerEmailmessage": "user@devo.comAlert definition created with alerting API / Gradient",
        "querySourceCodedescription": "from siem.logtrust.web.activityAlert definition long description / Gradient",
        "prioritycategoryId": 1"2432",
        "correlationTriggersubcategory": {
 "lib.my.tutorials.AWS",
        "kindsubcategoryId": "each4452",
          "externalPeriodisActive": nullfalse,
          "externalOffsetisFavorite": nullfalse,

         "internalPeriodisAlertChain": nullfalse,
 
        "internalOffsetalertCorrelationContext": null{
        }  "id": "567890",
   },       "actionPolicyIdnameId": []"my.alert.tutorials.AWSWAFRuleDeletion",
     },     "lengthownerEmail": -1,"user@devo.com",
          "locationquerySourceCode": null"from siem.logtrust.web.activity",
    "language": null,     "headerspriority": {}1,
  },   {     "contextcorrelationTrigger": {
 
    "headers": {},       "configurationkind": null"each",
      "entity": {     "externalPeriod": null,
  "id": "567890",         "creationDateexternalOffset": 1678293187000null,
            "nameinternalPeriod": "myAlertEach3"null,
            "messageinternalOffset": "Alert definition created with alerting API / Gradient",null
          }
  "description": "Alert definition long description / Gradient"},
        "categoryIdactionPolicyId": "2432",[]
      },
      "subcategoryentityType": "lib.my.tutorials.AWScom.devo.config.api.model.AlertDefinition",
        "subcategoryIdentityAnnotations": "4452"[],
        "isActiveentityStream": false,{
        "isFavoritecommitted": false,
        "isAlertChainclosed": false,
        "alertCorrelationContext": {
 },
        "idlengthLong": "567890"-1,
          "nameIdmediaType": "my.alert.tutorials.AWSWAFRuleDeletion",
null,
         "ownerEmailresponseCookies": "user@devo.com"{},
          "querySourceCodecommitted": "from siem.logtrust.web.activity",
   false,
      "priorityrequestCookies": 1{},
      "acceptableMediaTypes": [
    "correlationTrigger": {   {
          "kindtype": "each*",
            "externalPeriodsubtype": null"*",
 
          "externalOffsetparameters": null{},
            "internalPeriodquality": null1000,

           "internalOffsetwildcardType": nulltrue,
          }"wildcardSubtype": true
        },
 
      "actionPolicyId": []
      },
      "entityTypeallowedMethods": "com.devo.config.api.model.AlertDefinition"[],
      "entityAnnotationsentityTag": []null,
      "entityStreamacceptableLanguages": {[
        "committed*":
  false,    ],
      "closedentityClass": false"com.devo.config.api.model.AlertDefinition",
      "stringHeaders": {},
      "lengthLonglinks": -1[],
      "mediaTypedate": null,
      "responseCookieslastModified": {}null,
      "committedlength": false-1,
      "requestCookieslocation": {}null,
      "acceptableMediaTypeslanguage": [null
    },
    {"status": 200,
    "cookies": {},
    "typeallowedMethods": "*"[],
    "entityTag": null,
    "subtypestatusInfo": "*OK",
    "stringHeaders": {},
    "parametersmediaType": {}null,
    "metadata": {},
    "qualitylinks": 1000[],
    "date": null,
    "wildcardTypelastModified": truenull,
    "entity": {
      "wildcardSubtypeid": true"567890",
      "creationDate": 1678293187000,
}       ]"name": "myAlertEach3",
      "allowedMethodsmessage": []"Alert definition created with alerting API / Gradient",
      "entityTagdescription": null,"Alert definition long description /   "acceptableLanguages": [Gradient",
      "categoryId":   "*2432",
       ]"subcategory": "lib.my.tutorials.AWS",
      "entityClasssubcategoryId": "com.devo.config.api.model.AlertDefinition4452",
      "stringHeadersisActive": {}false,
      "linksisFavorite": []false,
      "dateisAlertChain": nullfalse,
      "lastModifiedalertCorrelationContext": null,{
        "lengthid": -1,"67741",
        "locationnameId": null,"my.alert.tutorials.AWSWAFRuleDeletion",
        "languageownerEmail": null"user@devo.com",
    },
    "statusquerySourceCode": 200"from siem.logtrust.web.activity",
        "cookiespriority": {}, 1,
        "allowedMethodscorrelationTrigger": [],{
    "entityTag": null,     "statusInfokind": "OKeach",
    "stringHeaders": {},     "mediaTypeexternalPeriod": null,
    "metadata": {},     "linksexternalOffset": []null,
    "date": null,     "lastModifiedinternalPeriod": null,
    "entity": {       "idinternalOffset": "567890",null
      "creationDate": 1678293187000, }
     "name": "myAlertEach3" },
      "messageactionPolicyId": "Alert[]
definition created with alerting API / Gradient" },
      "descriptionlength": "Alert-1,
definition long description / Gradient"location": null,
 
    "categoryIdlanguage": "2432"null,
 
    "subcategoryheaders": "lib.my.tutorials.AWS",
   {}
  "subcategoryId": "4452",
      "isActive": false,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "67741",
        "nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity}
]

    400

    Error in request.

    401

    Unauthorized request.

    403

    Forbidden request.

    405

    Method not allowed.

    500

    Server error and Java exception.

    Anchor
    path33
    path33
    PUT /alertDefinitions/{id}/deliveryPolicy

    Assign a sending policy to a specific alert definition in your domain.

    Rw ui expands macro
    Rw expand
    titleRequest

    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

    type required

    string

    Specify the type of sending policy you want to assign:

    • POLICY_BASED

    • NO_NOTIFICATION

    • DEFAULT_POLICY

    ids

    string

    If the POLICY_BASED type is set, specify the sending policy ID. To get a list with the existing policies and their IDs, you can use the Delivery methods API (get help here).

    Example

    Find below a request example in cURL language. This request assigns the sending policies with IDs 732 and 880 to the alert with ID 123456 in the domain that corresponds to the given token. Learn how to authorize your request in this article.

    Code Block
    curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/{123456}/deliveryPolicy?type=POLICY_BASED&ids=732&ids880"
    Rw expand
    titleResponse

    Code

    Description

    200

    Successful response. Sending policy assigned to alert.

    Code Block
    {
    "type": "POLICY_BASED",
    
    "
    priority
    alertConfig":
    1,
    [
    "correlationTrigger": {
    {
            "
    kind
    id":
    "each"
    732,
            "
    externalPeriod
    name":
    null,
    "sending_policy_weekends"
    "externalOffset": null
    },
        {
    "internalPeriod": null,
               "
    internalOffset
    id":
    null } }
    880,
    "actionPolicyId":
    []
    }, "length": -1, "location": null,
    "name": "sending_policy_weekdays"
    "language":
    null,
      }
    "headers": {}
      ]
}
    ]
    400
    Error in request.
    401
    Unauthorized request.
    403
    Forbidden request.
    405
    Method not allowed.
    500
    Server error and Java exception.
     Anchor
    path4
    path4
    PUT /alertDefinitions/status
    Use this operation to enable or deactivate several alerts at the same time.
     Rw ui expands macro
     Rw expand
    titleRequest
    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
    alertIds required
    string
    Specify the ID of the alert definition(s) that you want to update. Add as many alerIds parameters as required:
    alertIds=205870&alertIds=215374
    enable required
    boolean
    Set this parameter to true if you want to enable the alerts or false if you need to deactivate them.
    Example
    Find below a request example in cURL language. This request will enable the alerts with IDs 123456 and 678900 in the domain that corresponds to the given token. Learn how to authorize your request in this article.
     Code Block
    curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/status?alertIds=123456&alertIds=678900&enable=true"
     Rw expand
    titleResponse
    Code
    Description
    200
    Successful response. Alert statuses updated.
     Code Block
    {"updated":{"123456":true,"678900":true}}
    400
    Error in request.
    401
    Unauthorized request.
    403
    Forbidden request.
    405
    Method not allowed.
    500
    Server error and Java exception.
     Anchor
    path5
    path5
    DELETE /alertDefinitions
    Delete alert definitions in bulk.
     Rw ui expands macro
     Rw expand
    titleRequest
    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
    alertIds required
    string
    Specify the ID of the alert definition(s) that you want to delete. Add as many alerIds parameters as required following this format:
    alertIds=205870&alertIds=215374
     Note
    How can I get the ID of an alert definition?
    Alert definition IDs are not displayed in the Devo platform, so you should get them using GET /alertDefinitions to list all the alerts in the domain. IDs are included in the response.
    You will also get the ID of an alert definition after creating it using POST /alertDefinitions
    Example
    Find below a request example in cURL language. This request will delete the alerts with IDs 123456 and 678900 in the domain that corresponds to the given token. Learn how to authorize your request in this article.
     Code Block
    curl -H "standAloneToken:YOUR_TOKEN" -X DELETE "https://api-us.devo.com/alerts/v1/alertDefinitions?alertIds=215870&alertIds=215873"
     Rw expand
    titleResponse
    Code
    Description
    200
    Successful response. Alert(s) deleted.
    400
    Error in request.
    401
    Unauthorized request.
    403
    Forbidden request.
    405
    Method not allowed.
    500
    Server error and Java exception.
    ...