---
title: "Working with alert definitions using the API"
canonical: "https://docs.devo.com/space/latest/95128671/Working%20with%20alert%20definitions%20using%20the%20API"
format: markdown
---
> Macro (toc)
## Overview
Check the list of available endpoints and methods to work with alert definitions using the Alerts API:
| **Endpoints and methods** | **Description** |
| --- | --- |
| [GET]`/alertDefinitions` [see below](#path1) | Get the list of all the alerts defined in a domain. |
| [POST]`/alertDefinitions`[see below](#path2) | Create a new alert definition. |
| [POST]`/alertDefinitions/batch`[see below](#path23) | Create a set of new alert definitions. |
| [PUT] `/alertDefinitions`[see below](#path3) | Update a specific alert definition. |
| [PUT] `/alertDefinitions/batch`[see below](#path35) | Update a set of alert definitions. |
| [PUT] `/alertDefinitions/{id}/deliveryPolicy`[see below](#path33) | Assign a sending policy to a specific alert definition. |
| [PUT] `/alertDefinitions/status`[see below](#path4) | Update the status of several alert definitions in bulk. |
| [DELETE]`/alertDefinitions`[see below](#path5) | Delete alert definitions in bulk. |
## Endpoints and methods
### > Macro (anchor)
**GET**`/alertDefinitions`
Get the list of all the alerts defined in a given domain.
### 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** |
| --- | --- | --- |
| `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.
> ⚠️ **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:
```
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:
```
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](https://devodocs.atlassian.net/wiki/spaces/latest/pages/127762507).
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Alerts' information retrieved.
```
[
{
"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. |
### > Macro (anchor)
**POST** `/alertDefinitions`
Create a new alert definition.
### Request
#### 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 [Alert trigger method](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126609) to know the accepted fields.
This field can add to the *extraData* field, which is subject to the limit:
> Macro (excerpt-include) |
| `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 [Alert trigger method](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126609) to know the accepted fields.
This field can add to the *extraData* field, which is subject to the limit:
> Macro (excerpt-include) |
| `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 dont 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`
> ⚠️ When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed [here](https://docs.devo.com/space/latest/95206409/Alerts+monitoring).
- `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` |
| `deliveryPolicy` | `object` | This JSON object includes the following parameters:
- `type` - (`string`) Specify the type of sending policy you want to assign:
- `POLICY_BASED`
- `NO_NOTIFICATION`
- `DEFAULT_POLICY`
> ℹ️ If the `POLICY_BASED` type is set, specify the `policies (ids)`. To get a list with the existing policies and their IDs, you can use the Delivery methods API (get help [here](https://docs.devo.com/space/latest/715030548/Working+with+sending+policies+using+the+API#GET---/policies)).
- `policies` - (`integer`) Enter the id of the sending policy. You can insert more than one if needed, as shown in the example [PUT] `/alertDefinitions/{id}/deliveryPolicy`[see below](#path33) |
Depending on the type of alert specified, you are allowed to include different parameters:
| **Alert type** | **Parameters** | **Description** |
| --- | --- | --- |
| `each`
> ⚠️ The parameters for the `each` type alerts are mandatory if the specified query includes [subqueries](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95191366).
> ⚠️
> ⚠️ However, not every query containing a subquery is allowed. Learn more about this in the section below.
> ⚠️ Note that if you use this method and include a subquery, the minimum grouping time is 1 minute, and the maximum is 100 days. | `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).
> Macro (excerpt-include) |
| `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` | Determines the duration of the intervals used by the system to check for events.
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` | Determines the duration of the intervals used by the system to check for events.
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. |
| `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` | `period` | Specifies “Run every:” 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 secondsand the maximum value is 100 days. |
| `backPeriod` | Specifies “Check last:” how far in the past the search extends.
> Macro (excerpt-include) |
| `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](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126609).
#### **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](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95191366) 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 (more about them[here](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95203983)) 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?** |
| --- | --- |
| ```
from T1
``` | This query does not include any subquery, so it is not allowed. |
| ```
from T1
where x in (
from T2
where y in (
from T3
)
)
``` | This query includes nested subqueries, so it is not allowed. |
| ```
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. |
| ```
from T1
where x in (
from T2
group every 10m
)
``` | This query includes a temporal grouping in its subquery, so it is not allowed. |
| ```
from T1
where x in (
from T2
)
``` | This query has neither a group nor a time range in its subquery, so it is allowed. |
| ```
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](https://devodocs.atlassian.net/wiki/spaces/latest/pages/127762507).
**Each alert example**
```
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"
}
},
"deliveryPolicy": {
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
}
]
}
}'
```
**Each alert example with subquery**
```
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**
```
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,
"keys": [],
"threshold": 10000
}
}
}'
```
**Low alert example**
```
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
}
}
}'
```
**Inactivity alert example**
```
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
"name": "Alert definition / Inactivity",
"message": "Alert definition created with alerting API / Inactivity",
"description": "Alert definition long description / Inactivity",
"subcategory": "Subcategory/Inactivity",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 5,
"correlationTrigger": {
"kind": "inactivity",
"period": 1800000,
"keys": ["username"]
}
}
}'
```
**Rolling alert example**
```
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
"name": "Alert definition / Rolling",
"message": "Alert definition created with alerting API / Rolling",
"description": "Alert definition long description / Rolling",
"subcategory": "Subcategory/Rolling",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity group every -",
"priority": 4,
"correlationTrigger": {
"kind": "rolling",
"period": 300000,
"backPeriod": 3600000
}
}
}'
```
**Deviation alert example**
```
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
"name": "Alert definition / Deviation",
"message": "Alert definition created with alerting API / Deviation",
"description": "Alert definition long description / Deviation",
"subcategory": "Subcategory/Deviation",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
"priority": 5,
"correlationTrigger": {
"kind": "deviation",
"threshold": 40,
"absolute": true,
"aggregationColumn": [ "count" ]
}
}
}'
```
**Gradient alert example**
```
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
"name": "Alert definition / Gradient",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"subcategory": "Subcategory/Gradient",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
"priority": 1,
"correlationTrigger": {
"kind": "gradient",
"threshold": 40,
"absolute": false,
"aggregationColumn": [ "count" ]
}
}
}'
```
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Alert created.
```
{
"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": {
"id": "622",
"nameId": "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": 5,
"correlationTrigger": {
"kind": "each"
}
},
"actionPolicyId": []
}
``` |
| 400 | Error in request. |
| 401 | Unauthorized request. |
| 403 | Forbidden request. |
| 405 | Method not allowed. |
| 500 | Server error and Java exception. |
### > Macro (anchor)
**POST** `/alertDefinitions/batch`
Create a set of new alert definitions.
### Request
#### 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:
```
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",
"description": "Alert definition long description / Gradient",
"subcategory": "alert",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each"
}
},
"deliveryPolicy": {
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
}
]
}
},
{
"name": "myAlertEach3",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"subcategory": "alert",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each"
}
}
}
]'
```
Learn how to authorize your request [in this article](https://devodocs.atlassian.net/wiki/spaces/latest/pages/127762507).
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Set of alert definitions created.
```
[
{
"context": {
"headers": {},
"configuration": null,
"entity": {
"id": "226687",
"creationDate": 1685441802355,
"name": "myAlertEach2",
"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": "78228",
"nameId": "my.alert.tutorials.myAlertEach2",
"ownerEmail": "user@devo.com",
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each",
"externalPeriod": null,
"externalOffset": null,
"internalPeriod": null,
"internalOffset": null
}
},
"actionPolicyId": []
},
"entityType": "com.devo.config.api.model.AlertDefinition",
"entityAnnotations": [],
"entityStream": {
"committed": false,
"closed": false
},
"lengthLong": -1,
"mediaType": null,
"responseCookies": {},
"committed": false,
"requestCookies": {},
"stringHeaders": {},
"allowedMethods": [],
"entityTag": null,
"acceptableMediaTypes": [
{
"type": "*",
"subtype": "*",
"parameters": {},
"quality": 1000,
"wildcardType": true,
"wildcardSubtype": true
}
],
"acceptableLanguages": [
"*"
],
"entityClass": "com.devo.config.api.model.AlertDefinition",
"links": [],
"date": null,
"lastModified": null,
"length": -1,
"location": null,
"language": null
},
"status": 200,
"entity": {
"id": "226687",
"creationDate": 1685441802355,
"name": "myAlertEach2",
"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": "78228",
"nameId": "my.alert.tutorials.myAlertEach2",
"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": {}
},
{
"context": {
"headers": {},
"configuration": null,
"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": []
},
"entityType": "com.devo.config.api.model.AlertDefinition",
"entityAnnotations": [],
"entityStream": {
"committed": false,
"closed": false
},
"lengthLong": -1,
"mediaType": null,
"responseCookies": {},
"committed": false,
"requestCookies": {},
"stringHeaders": {},
"allowedMethods": [],
"entityTag": null,
"acceptableMediaTypes": [
{
"type": "*",
"subtype": "*",
"parameters": {},
"quality": 1000,
"wildcardType": true,
"wildcardSubtype": true
}
],
"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. |
### > Macro (anchor)
**PUT** `/alertDefinitions`
Update a specific alert definition in your domain.
### Request
#### 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.
> ⚠️ **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.
> ⚠️ **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 [Alert trigger methods](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126609) 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 theydepend on the trigger method used. See each [Alert trigger methods](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126609) 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.
> ⚠️ **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`
> ⚠️ When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed [here](https://docs.devo.com/space/latest/95206409/Alerts+monitoring).
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` |
| `deliveryPolicy` | `object` | This JSON object includes the following parameters:
- `type` - (`string`) Specify the type of sending policy you want to assign:
- `POLICY_BASED`
- `NO_NOTIFICATION`
- `DEFAULT_POLICY`
> ℹ️ If the `POLICY_BASED` type is set, specify the `policies (ids)`. To get a list with the existing policies and their IDs, you can use the Delivery methods API (get help [here](https://docs.devo.com/space/latest/715030548/Working+with+sending+policies+using+the+API#GET---/policies)).
- `policies` - (`integer`) Enter the id of the sending policy. You can insert more than one if needed, as shown in the example [PUT] `/alertDefinitions/{id}/deliveryPolicy`[see below](#) |
#### 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:
```
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,
},
"deliveryPolicy": {
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
}
]
}
}'
```
Learn how to authorize your request [in this article](https://devodocs.atlassian.net/wiki/spaces/latest/pages/127762507).
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Alert updated.
```
{
"id": "70736",
"creationDate": 1604567644173,
"name": "Alert_API_each",
"message": "New message",
"description": "New description",
"categoryId": "7",
"subcategory": "lib.my.testfake.AlertAPI_v660",
"subcategoryId": "133",
"isActive": true,
"isFavorite": false,
"isAlertChain": false,
"alertCorrelationContext": {
"id": "622",
"nameId": "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": 5,
"correlationTrigger": {
"kind": "each"
}
},
"actionPolicyId": []
}
``` |
| 400 | Error in request. |
| 401 | Unauthorized request. |
| 403 | Forbidden request. |
| 405 | Method not allowed. |
| 500 | Server error and Java exception. |
### > Macro (anchor)
**PUT** `/alertDefinitions/batch`
Update a set of alert definitions in your domain.
### Request
#### 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:
```
curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
{
"id": "123456"
"name": "myAlertEach2",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"subcategory": "alert",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each"
}
}
},
{
"id": "567890"
"name": "myAlertEach3",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"subcategory": "alert",
"alertCorrelationContext": {
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
},
"deliveryPolicy": {
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
}
]
}
}
]'
```
Learn how to authorize your request [in this article](https://devodocs.atlassian.net/wiki/spaces/latest/pages/127762507).
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Set of alert definitions updated.
```
[
{
"context": {
"headers": {},
"configuration": null,
"entity": {
"id": "123456",
"creationDate": 1678293190000,
"name": "myAlertEach2",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"categoryId": "2432",
"subcategory": "lib.my.tutorials.threats",
"subcategoryId": "4453",
"isActive": false,
"isFavorite": false,
"isAlertChain": false,
"alertCorrelationContext": {
"id": "67742",
"nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
"ownerEmail": "user@devo.com",
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each",
"externalPeriod": null,
"externalOffset": null,
"internalPeriod": null,
"internalOffset": null
}
},
"actionPolicyId": []
},
"entityType": "com.devo.config.api.model.AlertDefinition",
"entityAnnotations": [],
"entityStream": {
"committed": false,
"closed": false
},
"lengthLong": -1,
"mediaType": null,
"responseCookies": {},
"committed": false,
"requestCookies": {},
"acceptableMediaTypes": [
{
"type": "*",
"subtype": "*",
"parameters": {},
"quality": 1000,
"wildcardType": true,
"wildcardSubtype": true
}
],
"allowedMethods": [],
"entityTag": null,
"acceptableLanguages": [
"*"
],
"entityClass": "com.devo.config.api.model.AlertDefinition",
"stringHeaders": {},
"links": [],
"date": null,
"lastModified": null,
"length": -1,
"location": null,
"language": null
},
"status": 200,
"cookies": {},
"allowedMethods": [],
"entityTag": null,
"statusInfo": "OK",
"stringHeaders": {},
"mediaType": null,
"metadata": {},
"links": [],
"date": null,
"lastModified": null,
"entity": {
"id": "123456",
"creationDate": 1678293190000,
"name": "myAlertEach2",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"categoryId": "2432",
"subcategory": "lib.my.tutorials.threats",
"subcategoryId": "4453",
"isActive": false,
"isFavorite": false,
"isAlertChain": false,
"alertCorrelationContext": {
"id": "67742",
"nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
"ownerEmail": "user@devo.com",
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each",
"externalPeriod": null,
"externalOffset": null,
"internalPeriod": null,
"internalOffset": null
}
},
"actionPolicyId": []
},
"length": -1,
"location": null,
"language": null,
"headers": {}
},
{
"context": {
"headers": {},
"configuration": null,
"entity": {
"id": "567890",
"creationDate": 1678293187000,
"name": "myAlertEach3",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"categoryId": "2432",
"subcategory": "lib.my.tutorials.AWS",
"subcategoryId": "4452",
"isActive": false,
"isFavorite": false,
"isAlertChain": false,
"alertCorrelationContext": {
"id": "567890",
"nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
"ownerEmail": "user@devo.com",
"querySourceCode": "from siem.logtrust.web.activity",
"priority": 1,
"correlationTrigger": {
"kind": "each",
"externalPeriod": null,
"externalOffset": null,
"internalPeriod": null,
"internalOffset": null
}
},
"actionPolicyId": []
},
"entityType": "com.devo.config.api.model.AlertDefinition",
"entityAnnotations": [],
"entityStream": {
"committed": false,
"closed": false
},
"lengthLong": -1,
"mediaType": null,
"responseCookies": {},
"committed": false,
"requestCookies": {},
"acceptableMediaTypes": [
{
"type": "*",
"subtype": "*",
"parameters": {},
"quality": 1000,
"wildcardType": true,
"wildcardSubtype": true
}
],
"allowedMethods": [],
"entityTag": null,
"acceptableLanguages": [
"*"
],
"entityClass": "com.devo.config.api.model.AlertDefinition",
"stringHeaders": {},
"links": [],
"date": null,
"lastModified": null,
"length": -1,
"location": null,
"language": null
},
"status": 200,
"cookies": {},
"allowedMethods": [],
"entityTag": null,
"statusInfo": "OK",
"stringHeaders": {},
"mediaType": null,
"metadata": {},
"links": [],
"date": null,
"lastModified": null,
"entity": {
"id": "567890",
"creationDate": 1678293187000,
"name": "myAlertEach3",
"message": "Alert definition created with alerting API / Gradient",
"description": "Alert definition long description / Gradient",
"categoryId": "2432",
"subcategory": "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",
"priority": 1,
"correlationTrigger": {
"kind": "each",
"externalPeriod": null,
"externalOffset": null,
"internalPeriod": null,
"internalOffset": null
}
},
"actionPolicyId": []
},
"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. |
### > Macro (anchor)
**PUT** `/alertDefinitions/{id}/deliveryPolicy`
Assign a sending policy to a specific alert definition in your domain.
### Request
#### Request body
You must specify the parameters to be updated in the request body.
| **Parameter** | **Type** | **Definition** |
| --- | --- | --- |
| `type` required | `string` | Specify the type of sending policy you want to assign:
- `POLICY_BASED`
- `NO_NOTIFICATION`
- `DEFAULT_POLICY` |
| `policies` | `object` | > ℹ️ 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](https://docs.devo.com/space/latest/715030548/Working+with+sending+policies+using+the+API#GET---/policies)).
This JSON object includes the following parameters:
- `sending policy ID` -(`integer`) Enter the id of the sending policy. You can insert more than one if needed, as shown in the example below. |
#### Example 1
Find below a request example in cURL language. This request assigns the sending policies with IDs `23424` to the alert with ID `123456` in the domain that corresponds to the given token. Learn how to authorize your request [in this article](https://docs.devo.com/space/latest/100565313).
```
curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/{123456}/deliveryPolicy
{
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
}
]
}
```
#### Example 2 (with multiple policies)
This request assigns the sending policies with IDs `23424` and `1234` to the alert with ID `123456` in the domain that corresponds to the given token. Learn how to authorize your request [in this article](https://docs.devo.com/space/latest/100565313).
```
curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/{123456}/deliveryPolicy
{
"type": "POLICY_BASED",
"policies": [
{
"id": 23424
},
{
"id": 1234
}
]
}
```
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Sending policy assigned to alert.
```
{
"type": "POLICY_BASED",
"alertConfig": [
{
"id": 732,
"name": "sending_policy_weekends"
},
{
"id": 880,
"name": "sending_policy_weekdays"
}
]
}
``` |
| 400 | Error in request. |
| 401 | Unauthorized request. |
| 403 | Forbidden request. |
| 405 | Method not allowed. |
| 500 | Server error and Java exception. |
### > Macro (anchor)
**PUT** `/alertDefinitions/status`
Use this operation to enable or deactivate several alerts at the same time.
### 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** |
| --- | --- | --- |
| `alertIds` required | `string` | Specify the ID of the alert definition(s) that you want to update. Add as many `alerIds` parameters as required:
`alertIds=205870alertIds=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](https://docs.devo.com/space/latest/100565313).
```
curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/status?alertIds=123456&alertIds=678900&enable=true"
```
### Response
| **Code** | **Description** |
| --- | --- |
| 200 | Successful response. Alert statuses updated.
```
{"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. |
### > Macro (anchor)
**DELETE** `/alertDefinitions`
Delete alert definitions 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** |
| --- | --- | --- |
| `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=205870alertIds=215374`
> ⚠️ **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](https://docs.devo.com/space/latest/100565313).
```
curl -H "standAloneToken:YOUR_TOKEN" -X DELETE "https://api-us.devo.com/alerts/v1/alertDefinitions?alertIds=215870&alertIds=215873"
```
### Response
| **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. |