investigations

windows/security/threat-protection/TOC.md

@@ -408,6 +408,12 @@
 ####### [Stop and quarantine file](microsoft-defender-atp/stop-and-quarantine-file.md)
 ####### [Initiate investigation (preview)](microsoft-defender-atp/initiate-autoir-investigation.md)
 
+###### [Automated Investigation]()
+####### [Investigation methods and properties](microsoft-defender-atp/investigation.md)
+####### [List Investigation](microsoft-defender-atp/get-investigation-collection.md)
+####### [Get Investigation](microsoft-defender-atp/get-investigation-object.md)
+####### [Start Investigation](microsoft-defender-atp/start-investigation.md)
+
 ###### [Indicators]()
 ####### [Indicators methods and properties](microsoft-defender-atp/ti-indicator.md)
 ####### [Submit Indicator](microsoft-defender-atp/post-ti-indicator.md)

windows/security/threat-protection/microsoft-defender-atp/get-investigation-collection.md

@@ -0,0 +1,110 @@
+---
+title: List Investigations API
+description: Use this API to create calls related to get Investigations collection
+keywords: apis, graph api, supported apis, Investigations collection
+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
+---
+
+# List Investigations API
+
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+
+## API description
+Retrieves a collection of [Investigations](investigation.md).
+<br>Supports [OData V4 queries](https://www.odata.org/documentation/).
+<br>The OData's ```$filter``` query is supported on: ```startTime```, ```state```, ```machineId``` and ```triggeringAlertId``` properties.
+<br>See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
+
+
+## Limitations
+1. Maximum page size is 10,000.
+2. Rate limitations for this API are 100 calls per minute and 1500 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 ATP APIs](apis-intro.md)
+
+Permission type |	Permission	|	Permission display name
+:---|:---|:---
+Application |	Alert.Read.All |	'Read all alerts'
+Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read 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: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
+
+## HTTP request
+```
+GET https://api.securitycenter.windows.com/api/investigations
+```
+
+## Request headers
+
+Name | Type | Description
+:---|:---|:---
+Authorization | String | Bearer {token}. **Required**.
+
+
+## Request body
+Empty
+
+## Response
+If successful, this method returns 200, Ok response code with a collection of [Investigations](investigation.md) entities.
+
+
+[!include[Improve request performance](../../includes/improve-request-performance.md)]
+
+
+## Example
+
+**Request**
+
+Here is an example of a request to get all investigations: 
+
+
+```
+GET https://api.securitycenter.windows.com/api/investigations
+```
+
+**Response**
+
+Here is an example of the response:
+
+
+```
+HTTP/1.1 200 Ok
+Content-type: application/json
+{
+    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Investigations",
+    "value": [
+        {
+            "id": "63017",
+            "startTime": "2020-01-06T14:11:34Z",
+            "endTime": null,
+            "state": "Running",
+            "cancelledBy": null,
+            "statusDetails": null,
+            "machineId": "a69a22debe5f274d8765ea3c368d00762e057b30",
+            "computerDnsName": "desktop-gtrcon0",
+            "triggeringAlertId": "da637139166940871892_-598649278"
+        }
+		...
+    ]
+}
+```

windows/security/threat-protection/microsoft-defender-atp/get-investigation-object.md

@@ -0,0 +1,66 @@
+---
+title: Get Investigation object API
+description: Use this API to create calls related to get Investigation object
+keywords: apis, graph api, supported apis, Investigation object
+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
+---
+
+# Get Investigation API
+
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+
+## API description
+Retrieves specific [Investigation](investigation.md) by its ID.
+<br> ID can be the investigation ID or the investigation triggering alert ID.
+
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 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 ATP APIs](apis-intro.md)
+
+Permission type |	Permission	|	Permission display name
+:---|:---|:---
+Application |	Alert.Read.All |	'Read all alerts'
+Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read 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: 'View Data' (See [Create and manage roles](user-roles.md) for more information)
+
+## HTTP request
+```
+GET https://api.securitycenter.windows.com/api/investigations/{id}
+```
+
+## Request headers
+
+Name | Type | Description
+:---|:---|:---
+Authorization | String | Bearer {token}. **Required**.
+
+
+## Request body
+Empty
+
+## Response
+If successful, this method returns 200, Ok response code with a [Investigations](investigations.md) entity.
+

windows/security/threat-protection/microsoft-defender-atp/investigation.md

@@ -0,0 +1,64 @@
+---
+title: Investigation resource type
+description: Microsoft Defender ATP Investigation entity.
+keywords: apis, graph api, supported apis, get, alerts, investigations
+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
+---
+
+# Investigation resource type
+
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+Represent an Automated Investigation entity in Microsoft Defender ATP.
+<br> See [Overview of automated investigations](automated-investigations.md) for more information.
+
+## Methods
+Method|Return Type |Description
+:---|:---|:---
+[List Investigations](.md) | Investigation collection | Get a collection of Investigation
+[Get single Investigation](.md) | Investigation entity | Gets a single Investigation entity.
+[Start Investigation](.md) | Investigation entity | Starts Investigation on a machine.
+
+
+## Properties
+Property |	Type	|	Description
+:---|:---|:---
+id | String | Identity of the investigation entity. 
+startTime | DateTime Nullable | The date and time when the investigation was created. 
+endTime | DateTime Nullable | The date and time when the investigation was completed. 
+cancelledBy | String | The ID of the user/application that cancelled that investigation. 
+investigationState | Enum | The current state of the investigation. Possible values are: 'Unknown', 'Terminated', 'SuccessfullyRemediated', 'Benign', 'Failed', 'PartiallyRemediated', 'Running', 'PendingApproval', 'PendingResource', 'PartiallyInvestigated', 'TerminatedByUser', 'TerminatedBySystem', 'Queued', 'InnerFailure', 'PreexistingAlert', 'UnsupportedOs', 'UnsupportedAlertType', 'SuppressedAlert'.
+statusDetails | String | Additional information about the state of the investigation.
+machineId | String | The ID of the machine on which the investigation is executed.
+computerDnsName | String | The name of the machine on which the investigation is executed.
+triggeringAlertId | String | The ID of the alert that triggered the investigation.
+
+
+## Json representation
+
+```json
+{
+    "id": "63004",
+    "startTime": "2020-01-06T13:05:15Z",
+    "endTime": null,
+    "state": "Running",
+    "cancelledBy": null,
+    "statusDetails": null,
+    "machineId": "e828a0624ed33f919db541065190d2f75e50a071",
+    "computerDnsName": "desktop-test123",
+    "triggeringAlertId": "da637139127150012465_1011995739"
+}
+```

windows/security/threat-protection/microsoft-defender-atp/start-investigation.md

@@ -0,0 +1,99 @@
+---
+title: Start Investigation API
+description: Use this API to start investigation on a machine.
+keywords: apis, graph api, supported apis, 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
+---
+
+# Start Investigation API
+
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
+
+
+## API description
+Starts automated investigation on a machine.
+<br>See [Overview of automated investigations](automated-investigations.md) for more information.
+
+
+-------------------------- im here
+
+## Limitations
+1. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
+
+
+[!include[Machine actions note](../../includes/machineactionsnote.md)]
+
+## Permissions
+One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md)
+
+Permission type |	Permission	|	Permission display name
+:---|:---|:---
+Application |	Machine.Isolate |	'Isolate machine'
+Delegated (work or school account) | Machine.Isolate |	'Isolate machine'
+
+>[!Note]
+> When obtaining a token using user credentials:
+>- The user needs to have at least the following role permission: 'Active remediation actions' (See [Create and manage roles](user-roles.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.md) for more information)
+
+
+## HTTP request
+```
+POST https://api.securitycenter.windows.com/api/machines/{id}/isolate
+```
+
+## 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**.
+IsolationType	| String |	Type of the isolation. Allowed values are: 'Full' or 'Selective'.
+
+**IsolationType** controls the type of isolation to perform and can be one of the following:
+- Full – Full isolation
+- Selective – Restrict only limited set of applications from accessing the network (see [Isolate machines from the network](respond-machine-alerts.md#isolate-machines-from-the-network) for more details)
+
+
+## Response
+If successful, this method returns 201 - Created response code and [Machine Action](machineaction.md) in the response body.
+
+
+## Example
+
+**Request**
+
+Here is an example of the request.
+
+[!include[Improve request performance](../../includes/improve-request-performance.md)]
+
+```
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate
+Content-type: application/json
+{
+  "Comment": "Isolate machine due to alert 1234",
+  “IsolationType”: “Full” 
+}
+
+
+- To unisolate a machine, see [Release machine from isolation](unisolate-machine.md).