diff --git a/batch-update-alerts.md b/batch-update-alerts.md new file mode 100644 index 0000000000..2b93144552 --- /dev/null +++ b/batch-update-alerts.md @@ -0,0 +1,108 @@ +--- +title: Batch Update alert entities API +description: Learn how to update Microsoft Defender for Endpoint alerts in a batch by using this API. You can update the status, determination, classification, and assignedTo properties. +keywords: apis, graph api, supported apis, get, alert, information, id +search.product: eADQiWindows 10XVcnh +ms.prod: m365-security +ms.mktglfcycl: deploy +ms.sitesec: library +ms.pagetype: security +ms.author: macapara +author: mjcaparas +ms.localizationpriority: medium +manager: dansimp +audience: ITPro +ms.collection: M365-security-compliance +ms.topic: article +ms.technology: mde +--- + +# Batch update alerts + +[!INCLUDE [Microsoft 365 Defender rebranding](../../includes/microsoft-defender.md)] + + +**Applies to:** [Microsoft Defender for Endpoint](https://go.microsoft.com/fwlink/p/?linkid=2146631) + +- Want to experience Microsoft Defender for Endpoint? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) + +[!include[Microsoft Defender for Endpoint API URIs for US Government](../../includes/microsoft-defender-api-usgov.md)] + +[!include[Improve request performance](../../includes/improve-request-performance.md)] + + +## API description +Updates properties of a batch of existing [Alerts](alerts.md). +
Submission of **comment** is available with or without updating properties. +
Updatable properties are: `status`, `determination`, `classification` and `assignedTo`. + + +## Limitations +1. You can update alerts that are available in the API. See [List Alerts](get-alerts.md) for more information. +2. Rate limitations for this API are 10 calls per minute and 500 calls per hour. + + +## Permissions +One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender for Endpoint APIs](apis-intro.md) + +Permission type | Permission | Permission display name +:---|:---|:--- +Application | Alerts.ReadWrite.All | 'Read and write all alerts' +Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts' + +>[!Note] +> When obtaining a token using user credentials: +>- The user needs to have at least the following role permission: 'Alerts investigation' (See [Create and manage roles](user-roles.md) for more information) +>- The user needs to have access to the device associated with the alert, based on device group settings (See [Create and manage device groups](machine-groups.md) for more information) + +## HTTP request +```http +POST /api/alerts/batchUpdate +``` + +## Request headers + +Name | Type | Description +:---|:---|:--- +Authorization | String | Bearer {token}. **Required**. +Content-Type | String | application/json. **Required**. + + +## Request body +In the request body, supply the IDs of the alerts to be updated and the values of the relevant fields that you wish to update for these alerts. +
Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. +
For best performance you shouldn't include existing values that haven't changed. + +Property | Type | Description +:---|:---|:--- +alertIds | List<String>| A list of the IDs of the alerts to be updated. **Required** +status | String | Specifies the updated status of the specified alerts. The property values are: 'New', 'InProgress' and 'Resolved'. +assignedTo | String | Owner of the specified alerts +classification | String | Specifies the specification of the specified alerts. The property values are: 'Unknown', 'FalsePositive', 'TruePositive'. +determination | String | Specifies the determination of the specified alerts. The property values are: 'NotAvailable', 'Apt', 'Malware', 'SecurityPersonnel', 'SecurityTesting', 'UnwantedSoftware', 'Other' +comment | String | Comment to be added to the specified alerts. + +## Response +If successful, this method returns 200 OK, with an empty response body. + + +## Example + +**Request** + +Here is an example of the request. + +```http +POST https://api.securitycenter.microsoft.com/api/alerts/batchUpdate +``` + +```json +{ + "alertIds": ["da637399794050273582_760707377", "da637399989469816469_51697947354"], + "status": "Resolved", + "assignedTo": "secop2@contoso.com", + "classification": "FalsePositive", + "determination": "Malware", + "comment": "Resolve my alert and assign to secop2" +} +``` diff --git a/windows/security/threat-protection/microsoft-defender-atp/alerts.md b/windows/security/threat-protection/microsoft-defender-atp/alerts.md index 8cb3df6be0..a9c6b01922 100644 --- a/windows/security/threat-protection/microsoft-defender-atp/alerts.md +++ b/windows/security/threat-protection/microsoft-defender-atp/alerts.md @@ -38,6 +38,7 @@ Method |Return Type |Description [Get alert](get-alert-info-by-id.md) | [Alert](alerts.md) | Get a single [alert](alerts.md) object. [List alerts](get-alerts.md) | [Alert](alerts.md) collection | List [alert](alerts.md) collection. [Update alert](update-alert.md) | [Alert](alerts.md) | Update specific [alert](alerts.md). +[Batch update alerts](batch-update-alerts.md) | | Update a batch of [alerts](alerts.md). [Create alert](create-alert-by-reference.md)|[Alert](alerts.md)|Create an alert based on event data obtained from [Advanced Hunting](run-advanced-query-api.md). [List related domains](get-alert-related-domain-info.md)|Domain collection| List URLs associated with the alert. [List related files](get-alert-related-files-info.md) | [File](files.md) collection | List the [file](files.md) entities that are associated with the [alert](alerts.md).