deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-05-27 20:57:23 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merged PR 14741: Add new api page

Browse Source 
Add new api page
This commit is contained in:
Ron Yitzhak 2019-03-14 16:12:28 +00:00 committed by Joey Caparas
commit b7ba39119b
3 changed files with 100 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
windows/security/threat-protection/TOC.md
View File

@ -292,6 +292,7 @@
######## [Run antivirus scan](windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md)
######## [Offboard machine](windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md)
######## [Stop and quarantine file](windows-defender-atp/stop-and-quarantine-file-windows-defender-advanced-threat-protection-new.md)
######## [Initiate investigation (preview)](windows-defender-atp/initiate-autoir-investigation-windows-defender-advanced-threat-protection-new.md)
####### [User](windows-defender-atp/user-windows-defender-advanced-threat-protection-new.md)
######## [Get user related alerts](windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md)

1
windows/security/threat-protection/windows-defender-atp/TOC.md
View File

@ -288,6 +288,7 @@
####### [Run antivirus scan](run-av-scan-windows-defender-advanced-threat-protection-new.md)
####### [Offboard machine](offboard-machine-api-windows-defender-advanced-threat-protection-new.md)
####### [Stop and quarantine file](stop-and-quarantine-file-windows-defender-advanced-threat-protection-new.md)
####### [Initiate investigation (preview)](initiate-autoir-investigation-windows-defender-advanced-threat-protection-new.md)
###### [User](user-windows-defender-advanced-threat-protection-new.md)
####### [Get user related alerts](get-user-related-alerts-windows-defender-advanced-threat-protection-new.md)

98
windows/security/threat-protection/windows-defender-atp/initiate-autoir-investigation-windows-defender-advanced-threat-protection-new.md Normal file
View File

@ -0,0 +1,98 @@
---
title: Initiate machine investigation API
description: Use this API to create calls related to initiating an investigation on a machine.
keywords: apis, graph api, supported apis, initiate AutoIR investigation
search.product: eADQiWindows 10XVcnh
ms.prod: w10
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
---
# Initiate machine investigation API (Preview)
**Applies to:**
- [Windows Defender Advanced Threat Protection (Windows Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
> [!IMPORTANT]
> Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Initiate AutoIR investigation on a machine.
>[!Note]
> This page focuses on performing an automated investigation on a machine. See [Automated Investigation](automated-investigations-windows-defender-advanced-threat-protection.md) for more information.
## Limitations
1. The number of executions is limited (up to 5 calls per hour).
2. For Automated Investigation limitations, see [Automated Investigation](automated-investigations-windows-defender-advanced-threat-protection.md).
## Permissions
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Windows Defender ATP APIs](apis-intro.md)
Permission type | Permission | Permission display name
:---|:---|:---
Application | Alert.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-windows-defender-advanced-threat-protection.md) for more information)
>- The user needs to have access to the machine, based on machine group settings (See [Create and manage machine groups](machine-groups-windows-defender-advanced-threat-protection.md) for more information)
## HTTP request
```
POST https://api.securitycenter.windows.com/api/machines/{id}/InitiateInvestigation
```
## Request headers
Name | Type | Description
:---|:---|:---
Authorization | String | Bearer {token}. **Required**.
Content-Type | string | application/json. **Required**.
## Request body
In the request body, supply a JSON object with the following parameters:
Parameter | Type | Description
:---|:---|:---
Comment | String | Comment to associate with the action. **Required**.
## Response
If successful, this method returns 200 OK response code with object that holds the investigation ID in the "value" parameter. If machine was not found - 404 Not Found.
## Example
**Request**
Here is an example of the request.
[!include[Improve request performance](improverequestperformance-new.md)]
```
POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/InitiateInvestigation
Content-type: application/json
{
"Comment": "Initiate an investigation on machine fb9ab6be3965095a09c057be7c90f0a2"
}
```
**Response**
Here is an example of the response.
```
HTTP/1.1 200 Created
Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Edm.Int64",
"value": 5146
}
```