David comments

windows/security/threat-protection/windows-defender-atp/alerts-windows-defender-advanced-threat-protection-new.md

@@ -22,20 +22,20 @@ Represents an alert entity in WDATP.
 # Methods
 Method|Return Type |Description
 :---|:---|:---
-[Get alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | Get a single [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) object.
+[Get alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) | Get a single [alert](alerts-windows-defender-advanced-threat-protection-new.md) object.
-[List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) collection | List [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) collection.
+[List alerts](get-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | List [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection.
-[Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)|[alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md)|Create an alert based on event data obtained from [Advanced Hunting](run-advanced-query-api.md)
+[Create alert](create-alert-by-reference-windows-defender-advanced-threat-protection-new.md)|[alert](alerts-windows-defender-advanced-threat-protection-new.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-windows-defender-advanced-threat-protection-new.md)|Domain collection|List Urls associated with the alert.
-[List related files](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) collection |  List the [file](files-windows-defender-advanced-threat-protection-new.md) entities that are associated with the [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md).
+[List related files](get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) collection |  List the [file](files-windows-defender-advanced-threat-protection-new.md) entities that are associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
 [List related IPs](get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md) | IP collection | List IPs that are associated witht the alert.
-[Get related Machine](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) entity | The [machine](machine-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md).
+[Get related machines](get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) | The [machine](machine-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
-[Get related user](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) | The [user](user-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md).
+[Get related users](get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md) | [user](user-windows-defender-advanced-threat-protection-new.md) | The [user](user-windows-defender-advanced-threat-protection-new.md) that is associated with the [alert](alerts-windows-defender-advanced-threat-protection-new.md).
 
 
 # Properties
 Property |	Type	|	Description
 :---|:---|:---
-id | string | alert id.
+id | String | alert id.
 severity | String | severity of the alert. Allowed values are: 'Low', 'Medium' and 'High'.
 status | String | Specifies the current status of the alert. The property values are: 'New', 'InProgress' and 'Resolved'.
 description | String | Description of the threat, identified by the alert.
@@ -51,7 +51,7 @@ determination | String | Specifies the determination of the alert. The property
 resolvedTime | DateTimeOffset | The date and time in which the status of the alert was changed to 'Resolved'.
 lastEventTime | DateTimeOffset | The last occurance of the event that triggered the alert on the same machine.
 firstEventTime | DateTimeOffset | The first occurance of the event that triggered the alert on that machine.
-machineId | string | id of a [machine](machine-windows-defender-advanced-threat-protection-new.md) entity that is associated with the alert.
+machineId | String | id of a [machine](machine-windows-defender-advanced-threat-protection-new.md) entity that is associated with the alert.
 
 # JSON representation
 ```

windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md

@@ -41,7 +41,7 @@ POST /api/machines/{id}/collectInvestigationPackage
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 ## Request body
@@ -61,11 +61,7 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/collectInvestigationPackage

windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md

@@ -59,8 +59,7 @@ category| String | Category of the alert. The property values are: 'None', 'Susp
 
 
 ## Response
-If successful, this method returns 200 OK, and a new [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body.
+If successful, this method returns 200 OK, and a new [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body. If event with the specified properties (_reportId_, _eventTime_ and _machineId_) was not found - 404 Not Found.
-If event with the specified properties (_reportId_, _eventTime_ and _machineId_) was not found - 404 Not Found.
 
 
 ## Example
@@ -69,11 +68,7 @@ If event with the specified properties (_reportId_, _eventTime_ and _machineId_)
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 POST https://api.securitycenter.windows.com/api/CreateAlertByReference

windows/security/threat-protection/windows-defender-atp/exposed-apis-windows-defender-advanced-threat-protection-new.md

@@ -1,189 +0,0 @@
----
-title: Use Windows Defender Advanced Threat Protection APIs  
-description: Use the exposed data and actions using a set of progammatic APIs that are part of the Microsoft Intelligence Security Graph.
-keywords: apis, graph api, supported apis, actor, alerts, machine, user, domain, ip, file, advanced hunting, query
-search.product: eADQiWindows 10XVcnh
-ms.prod: w10
-ms.mktglfcycl: deploy
-ms.sitesec: library
-ms.pagetype: security
-ms.author: macapara
-author: mjcaparas
-ms.localizationpriority: medium
-ms.date: 30/07/2018
----
-
-# Use Windows Defender ATP APIs 
-
-**Applies to:**
-
-- Windows 10 Enterprise
-- Windows 10 Education
-- Windows 10 Pro
-- Windows 10 Pro Education
-- Windows Defender Advanced Threat Protection (Windows Defender ATP)
-
-
->Want to experience Windows Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/en-us/WindowsForBusiness/windows-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
-
-Windows Defender ATP exposes much of its data and actions through a set of programmatic APIs. Those APIs will enable you to automate workflows and innovate based on Windows Defender ATP capabilities. The API access requires OAuth2.0 authentication. For more information, see [OAuth 2.0 Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-code).
-
-In general, you’ll need to take the following steps to use the APIs:
-- Create an app
-- Get an access token
-- Use the token to access Windows Defender ATP API
-
-This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
-
-## Create an app
-
-1.	Log on to [Azure](https://portal.azure.com).
-
-2.	Navigate to **Azure Active Directory** > **App registrations** > **New application registration**. 
-
-    ![Image of Microsoft Azure and navigation to application registration](images/atp-azure-new-app.png)
-
-3.	In the Create window, enter the following information then click **Create**.
-
-    ![Image of Create application window](images/webapp-create.png)
-
-    - **Name:** WdatpEcosystemPartner
-    - **Application type:** Web app / API
-    - **Redirect URI:** `https://WdatpEcosystemPartner.com` (The URL where user can sign in and use your app. You can change this URL later.)
-
-
-4.	Click **Settings** > **Required permissions** > **Add**.
-
-    ![Image of new app in Azure](images/webapp-add-permission.png)
-
-5.	Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
-	
-	**Note**: WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.
-
-    ![Image of API access and API selection](images/webapp-add-permission-2.png)
-
-6. Click **Select permissions** > **Run advanced queries** > **Select**.
-	
-	**Important note**: You need to select the relevant permission. 'Run advanced queries' is only an example!
-
-    ![Image of select permissions](images/webapp-select-permission.png)
-
-	- In order to send telemetry events to WDATP, check 'Write timeline events' permission
-	- In order to send TI events to WDATP, check 'Read and write IOCs belonging to the app' permission
-	- In order to run advanced queries in WDATP, check 'Run advanced queries' permission
-
-8. User with "Global Admin" permissions, need to click **Grant Permissions** in the **Required Permissions** tab.
-
-8. Click **Done**
-
-    ![Image of add permissions completion](images/webapp-add-permission-end.png)
-
-9. Click **Keys** and type a key name and click **Save**.
-
-	**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
-
-    ![Image of create app key](images/webapp-create-key.png)
-
-10. Write down your application ID.
-    
-	![Image of app ID](images/webapp-get-appid.png)
-
-11. Set your application to be multi-tenanted
-	
-	This is **required** for 3rd party apps (i.e., if you create an application that is intended to run in multiple customers tenant).
-
-	This is **not required** if you create a service that you want to run in your tenant only (i.e., if you create an application for your own usage that will only interact with your own data)​
-
-	Click **Properties** > **Yes** > **Save**.
-
-	![Image of multi tenant](images/webapp-edit-multitenant.png)
-
-
-## Application consent
-
-You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
-
-You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
-
-Consent link is of the form: 
-
-```
-https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true​
-```
-
-where 00000000-0000-0000-0000-000000000000​ should be replaced with your Azure application ID
-
-
-## Get an access token
-
-For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols-oauth-client-creds)
-
-### Using C#
-
->The below code was tested with nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8
-
-- Create a new Console Application
-- Install Nuget [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/)
-- Add the below using
-
-	```
-	using Microsoft.IdentityModel.Clients.ActiveDirectory;
-	```
-
-- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
-
-	```
-	string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
-	string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
-	string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here
-
-	const string authority = "https://login.windows.net";
-	const string wdatpResourceId = "https://api.securitycenter.windows.com/windowsatpservice";
-
-	AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
-	ClientCredential clientCredential = new ClientCredential(appId, appSecret);
-	AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
-	string token = authenticationResult.AccessToken;
-	```
-
-### Using PowerShell 
-
-Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
-
-### Using Python
-
-Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
-
-### Using Curl
-
-> [!NOTE]
-> The below procedure supposed Curl for Windows is already installed on your computer
-
-- Open a command window
-- ​Set CLIENT_ID to your Azure application ID
-- Set CLIENT_SECRET to your Azure application secret
-- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application
-- Run the below command:
-
-```
-curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice​/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID​%/oauth2/v2.0/token" -k​
-```
-
-You will get an answer of the form:
-
-```
-{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
-```
-
-## Validate the token
-
-- Copy/paste into [JWT](https://jwt.ms/) the token you get in the previous step 
-- Validate you get a 'roles' claim with the desired permission as you've chosen when adding permissions to the applications:
-
-![Image of token validation](images/webapp-validate-token.png)
-
-> [!NOTE]
-> The same token can be used for 1 hour and then it expired
-
-## Related topics
-- [Supported Windows Defender ATP APIs](supported-apis-windows-defender-advanced-threat-protection-new.md)

windows/security/threat-protection/windows-defender-atp/files-windows-defender-advanced-threat-protection-new.md

@@ -23,7 +23,7 @@ Represent a file entity in WDATP.
 Method|Return Type |Description
 :---|:---|:---
 [Get file](get-file-information-windows-defender-advanced-threat-protection-new.md) | [file](files-windows-defender-advanced-threat-protection-new.md) | Get a single file 
-[List file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) collection | Get the [alert](get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md) entities that are associated with the file.
+[List file related alerts](get-file-related-alerts-windows-defender-advanced-threat-protection-new.md) | [alert](alerts-windows-defender-advanced-threat-protection-new.md) collection | Get the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities that are associated with the file.
 [List file related machines](get-file-related-machines-windows-defender-advanced-threat-protection-new.md) | [machine](machine-windows-defender-advanced-threat-protection-new.md) collection | Get the [machine](machine-windows-defender-advanced-threat-protection-new.md) entities associated with the alert.
 [file statistics](get-file-statistics-windows-defender-advanced-threat-protection-new.md) | Statistics summary | Retrieves the prevalence for the given file.
 

windows/security/threat-protection/windows-defender-atp/find-machine-info-by-ip-windows-defender-advanced-threat-protection-new.md

@@ -22,7 +22,7 @@ ms.date: 07/25/2018
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
 
-Find a machine entity around a specific timestamp by internal IP.
+Find a machine by internal IP.
 
 >[!NOTE]
 >The timestamp must be within the last 30 days.
@@ -44,7 +44,7 @@ GET /api/machines/find(timestamp={time},key={IP})
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body

windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md

@@ -41,15 +41,14 @@ GET /api/alerts/{id}
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful, this method returns 200 OK, and an [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body.
+If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body. If alert with the specified id was not found - 404 Not Found.
-If alert with the specified id was not found - 404 Not Found.
 
 
 ## Example
@@ -58,11 +57,7 @@ If alert with the specified id was not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442

windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md

@@ -40,7 +40,7 @@ GET /api/alerts/{id}/domains
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -57,11 +57,7 @@ If alert not found or domain not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md

@@ -40,7 +40,7 @@ GET /api/alerts/{id}/files
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -57,11 +57,7 @@ If alert not found or files not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442/files

windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md

@@ -41,15 +41,14 @@ GET /api/alerts/{id}/ips
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and alert and an IP exist - 200 OK.
+If successful and alert and an IP exist - 200 OK. If alert not found or IPs not found - 404 Not Found.
-If alert not found or IPs not found - 404 Not Found.
 
 
 ## Example
@@ -58,11 +57,7 @@ If alert not found or IPs not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/alerts/636688558380765161_2136280442/ips

windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md

@@ -42,7 +42,7 @@ GET /api/alerts/{id}/machine
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -58,11 +58,7 @@ If alert not found or machine not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md

@@ -41,7 +41,7 @@ GET /api/alerts/{id}/user
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -58,11 +58,7 @@ If alert not found or user not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```
@@ -78,7 +74,7 @@ Here is an example of the response.
 HTTP/1.1 200 OK
 Content-type: application/json
 {
-    "@odata.context": "https://wdatpapi-eus-stg.cloudapp.net/api/$metadata#Users/$entity",
+    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
     "id": "contoso\\user1",
     "firstSeen": "2018-08-02T00:00:00Z",
     "lastSeen": "2018-08-04T00:00:00Z",

windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md

@@ -46,15 +46,14 @@ Method supports $skip and $top query parameters.
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful, this method returns 200 OK, and a list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects in the response body.
+If successful, this method returns 200 OK, and a list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects in the response body. If no recent alerts found - 404 Not Found.
-If no recent alerts found - 404 Not Found.
 
 
 ## Example
@@ -63,11 +62,7 @@ If no recent alerts found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/alerts

windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -41,16 +41,15 @@ GET /api/domains/{domain}/alerts
 ## Request headers
 
 Header | Value 
-:---|:---
+:---|:---|:---
-Authorization | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and domain and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) objects.
+If successful and domain and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities. If domain or alert does not exist - 404 Not Found.
-If domain or alert does not exist - 404 Not Found.
 
 
 ## Example
@@ -59,11 +58,7 @@ If domain or alert does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/domains/client.wns.windows.com/alerts

windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -30,7 +30,8 @@ One of the following permissions is required to call this API. To learn more, in
 
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
-Application |	URL.Read.All |	'Read URLs'
+Application |	Machine.Read.All |	'Read all machine profiles'
+Application |	Machine.ReadWrite.All |	'Read and write all machine information'
 
 ## HTTP request
 ```
@@ -39,17 +40,16 @@ GET /api/domains/{domain}/machines
 
 ## Request headers
 
-Header | Value 
+Name | Type | Description
-:---|:---
+:---|:---|:---
-Authorization | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and domain and machine exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) objects.
+If successful and domain and machine exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities. If domain or machines do not exist - 404 Not Found.
-If domain or machines do not exist - 404 Not Found.
 
 
 ## Example
@@ -58,11 +58,7 @@ If domain or machines do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md

@@ -48,7 +48,7 @@ Authorization | Bearer {token}. **Required**.
 Empty
 
 ## Response
-If successful and domain exists - 200 OK, with statistics object in the respnose body.
+If successful and domain exists - 200 OK, with statistics object in the response body.
 If domain does not exist - 404 Not Found.
 
 
@@ -58,11 +58,7 @@ If domain does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/domains/example.com/stats

windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md

@@ -42,7 +42,7 @@ GET /api/files/{id}
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -59,11 +59,7 @@ If file does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1

windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -42,7 +42,7 @@ GET /api/files/{id}/alerts
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -59,11 +59,7 @@ If file or alerts do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/alerts

windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -42,7 +42,7 @@ GET /api/files/{id}/machines
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -59,11 +59,7 @@ If file or machines do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/files/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/machines

windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md

@@ -41,7 +41,7 @@ GET /api/files/{id}/stats
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -58,11 +58,7 @@ If file do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/files/6532ec91d513acc05f43ee0aa3002599729fd3e1/stats

windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -42,7 +42,7 @@ GET /api/ips/{ip}/alerts
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -59,11 +59,7 @@ If IP and alerts do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -20,7 +20,7 @@ ms.date: 12/08/2017
 **Applies to:**
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Retrieves a collection of alerts related to a given IP address.
+Retrieves a collection of machines that communicated with or from a particular IP.
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -39,7 +39,7 @@ GET /api/ips/{ip}/machines
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -56,11 +56,7 @@ If IP or machines do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/machines

windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection.md

@@ -36,8 +36,7 @@ Content type | application/json
 Empty
 
 ## Response
-If successful and IP and machines exists - 200 OK.
+If successful and IP and machines exists - 200 OK. If IP or machines do not exist - 404 Not Found.
-If IP or machines do not exist - 404 Not Found.
 
 
 ## Example

windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md

@@ -39,15 +39,14 @@ GET /api/ips/{ip}/stats
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and file exists - 200 OK with statistical data in the body.
+If successful and ip exists - 200 OK with statistical data in the body. IP do not exist - 404 Not Found.
-If file do not exist - 404 Not Found.
 
 
 ## Example
@@ -56,11 +55,7 @@ If file do not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/ips/10.209.67.177/stats
@@ -76,7 +71,7 @@ HTTP/1.1 200 OK
 Content-type: application/json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgIPStats",
-    "ipAddress": "192.168.1.1",
+    "ipAddress": "10.209.67.177",
     "orgPrevalence": "63515",
     "orgFirstSeen": "2017-07-30T13:36:06Z",
     "orgLastSeen": "2017-08-29T13:32:59Z"

windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md

@@ -40,7 +40,7 @@ GET /api/machines/{id}
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -57,11 +57,7 @@ If machine with the specified id was not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07

windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md

@@ -40,7 +40,7 @@ GET /api/machines/{id}/logonusers
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -57,11 +57,7 @@ If no machine found or no users found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/logonusers

windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -40,15 +40,14 @@ GET /api/machines/{id}/alerts
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and machine and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body.
+If successful and machine and alert exists - 200 OK with list of [alert](alerts-windows-defender-advanced-threat-protection-new.md) entities in the body. If no machine or no alerts found - 404 Not Found.
-If no machine or no alerts found - 404 Not Found.
 
 
 ## Example
@@ -57,15 +56,11 @@ If no machine or no alerts found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```
-GET https://api.securitycenter.windows.com/api/machines/{id}/alerts
+GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/alerts
 ```
 
 **Response**

windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md

@@ -13,7 +13,7 @@ ms.localizationpriority: medium
 ms.date: 12/08/2017
 ---
 
-# Get MachineAction object API
+# Get machineAction API
 
 [!include[Prerelease information](prerelease.md)]
 
@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Get actions done on a machine.
+Get action performed on a machine.
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -40,15 +40,14 @@ GET /api/machineactions/{id}
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful, this method returns 200, Ok response code with a [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) object.
+If successful, this method returns 200, Ok response code with a [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) entity. If machine action entity with the specified id was not found - 404 Not Found.
-If machine action with the specified id was not found - 404 Not Found.
 
 ## Example
 
@@ -56,11 +55,7 @@ If machine action with the specified id was not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/machineactions/2e9da30d-27f6-4208-81f2-9cd3d67893ba

windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
- Gets collection of actions done on machines. Get MachineAction collection API supports OData V4 queries.
+ Gets collection of actions done on machines. Get MachineAction collection API supports [OData V4 queries](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption).
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -40,14 +40,14 @@ GET /api/machineactions
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful, this method returns 200, Ok response code with a collection of [Machine Action](machineaction-windows-defender-advanced-threat-protection-new.md) objects since the Retention policy time of the organization.
+If successful, this method returns 200, Ok response code with a collection of [machineAction](machineaction-windows-defender-advanced-threat-protection-new.md) entities.
 
 
 ## Example 1
@@ -56,11 +56,7 @@ If successful, this method returns 200, Ok response code with a collection of [M
 
 Here is an example of the request on an organization that has three MachineActions.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/machineactions
@@ -128,11 +124,7 @@ GET https://api.securitycenter.windows.com/api/machineactions?$filter=machineId
 
 Here is an example of the response.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 HTTP/1.1 200 Ok

windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Retrieves a collection of recently seen machines.
+Retrieves a collection of machines that have communicated with WDATP cloud on the last 30 days.
 
 ## Permissions
 
@@ -39,15 +39,14 @@ GET /api/machines
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
+If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If no recent machines - 404 Not Found.
-If no recent machines - 404 Not Found.
 
 
 ## Example
@@ -56,11 +55,7 @@ If no recent machines - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/machines

windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Get a URI that allows downloading of an investigation package.
+Get a URI that allows downloading of an [investigation package](collect-investigation-package-windows-defender-advanced-threat-protection-new).
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -32,14 +32,14 @@ Application |	Machine.CollectForensics |	'Collect forensics'
 
 ## HTTP request
 ```
-GET /api/machineactions/{id}/getPackageUri
+GET /api/machineactions/{machine action id}/getPackageUri
 ```
 
 ## Request headers
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -64,11 +64,7 @@ GET https://api.securitycenter.windows.com/api/machineactions/7327b54fd718525cbc
 
 Here is an example of the response.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/get-user-information-windows-defender-advanced-threat-protection-new.md

@@ -39,15 +39,14 @@ GET /api/users/{id}/
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and user exists - 200 OK with [user](user-windows-defender-advanced-threat-protection-new.md) entity in the body.
+If successful and user exists - 200 OK with [user](user-windows-defender-advanced-threat-protection-new.md) entity in the body. If user does not exist - 404 Not Found.
-If user does not exist - 404 Not Found.
 
 
 ## Example
@@ -56,14 +55,10 @@ If user does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
-GET https://api.securitycenter.windows.com/api/users/{id}
+GET https://api.securitycenter.windows.com/api/users/user1@contoso.com
 Content-type: application/json
 ```
 
@@ -76,11 +71,15 @@ Here is an example of the response.
 HTTP/1.1 200 OK
 Content-type: application/json
 {
-    "@odata.context": "https://api.securitycenter.windows.com/testwdatppreview/$metadata#Users/$entity",
+    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users/$entity",
-    "id": "",
+    "id": "user1@contoso.com",
-    "accountSid": null,
+    "firstSeen": "2018-08-02T00:00:00Z",
-    "accountName": "",
+    "lastSeen": "2018-08-04T00:00:00Z",
-    "accountDomainName": "",
+    "mostPrevalentMachineId": null,
-…
+    "leastPrevalentMachineId": null,
+    "logonTypes": "Network",
+    "logOnMachinesCount": 3,
+    "isDomainAdmin": false,
+    "isOnlyNetworkUser": null
 }
 ```

windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -40,15 +40,14 @@ GET /api/users/{id}/alerts
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and user and alert exists - 200 OK.
+If successful and user and alert exists - 200 OK. If user or alerts does not exist - 404 Not Found.
-If user does not exist - 404 Not Found.
 
 
 ## Example
@@ -57,11 +56,7 @@ If user does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/alerts

windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -40,15 +40,14 @@ GET /api/users/{id}/machines
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
 Empty
 
 ## Response
-If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body.
+If successful and machines exists - 200 OK with list of [machine](machine-windows-defender-advanced-threat-protection-new.md) entities in the body. If user or machines does not exist - 404 Not Found.
-If user or machines does not exist - 404 Not Found.
 
 
 ## Example
@@ -57,11 +56,7 @@ If user or machines does not exist - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/users/user1@contoso.com/machines

windows/security/threat-protection/windows-defender-atp/improverequestperformance-new.md

@@ -0,0 +1,8 @@
+---
+ms.date: 08/28/2017
+---
+>[!NOTE]
+>For better performance, you can use server closer to your geo location:
+> - api-us.securitycenter.windows.com
+> - api-eu.securitycenter.windows.com
+> - api-uk.securitycenter.windows.com

windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md

@@ -54,11 +54,7 @@ If successful and domain exists - 200 OK. If domain does not exist - 404 Not Fou
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 GET https://api.securitycenter.windows.com/api/domains/example.com

windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md

@@ -39,7 +39,7 @@ GET /api/ips/{ip}
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 
 
 ## Request body
@@ -63,11 +63,7 @@ GET https://api.securitycenter.windows.com/api/ips/10.209.67.177
 
 Here is an example of the response.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 
 ```

windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md

@@ -39,7 +39,7 @@ POST /api/machines/{id}/isolate
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 ## Request body
@@ -65,14 +65,10 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/isolate
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/isolate
 Content-type: application/json
 {
   "Comment": "Isolate machine due to alert 1234",
@@ -95,9 +91,11 @@ Content-type: application/json
     "requestorComment": "Isolate machine due to alert 1234",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:12:18.9725659Z",
     "lastUpdateTimeUtc": "2017-12-04T12:12:18.9725659Z" 
 }
 
 ```
+
+To unisolate a machine, see [Release machine from isolation](unisolate-machine-windows-defender-advanced-threat-protection-new.md).

windows/security/threat-protection/windows-defender-atp/machine-windows-defender-advanced-threat-protection-new.md

@@ -33,13 +33,13 @@ firstSeen | DateTimeOffset | First date and time where the [machine](machine-win
 osPlatform | String | OS platform.
 osVersion | String | OS Version.
 lastIpAddress | Ip | Last IP on local NIC on the [machine](machine-windows-defender-advanced-threat-protection-new.md).
-lastExternalIpAddress | Ip | Last Ip through which the [machine](machine-windows-defender-advanced-threat-protection-new.md) accessed the internet.
+lastExternalIpAddress | Ip | Last IP through which the [machine](machine-windows-defender-advanced-threat-protection-new.md) accessed the internet.
 agentVersion | String | Version of WDATP agent.
 groupName | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) group name (when defined).
 osBuild | Int | OS build number.
 healthStatus | String | [machine](machine-windows-defender-advanced-threat-protection-new.md) health status.
 isAadJoined | Boolean | Is [machine](machine-windows-defender-advanced-threat-protection-new.md) AAD joined.
 machineTags | String collection | Set of [machine](machine-windows-defender-advanced-threat-protection-new.md) tags.
-rbacGroupId | Int | Group Id.
+rbacGroupId | Int | Group ID.
 riskScore | String | Risk score as evaludated by WDATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
-aadDeviceId | String | AAD Device Id (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined).
+aadDeviceId | String | AAD Device ID (when [machine](machine-windows-defender-advanced-threat-protection-new.md) is Aad Joined).

windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md

@@ -39,7 +39,7 @@ POST /api/machines/{id}/offboard
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 ## Request body
@@ -59,14 +59,10 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/offboard
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/offboard
 Content-type: application/json
 {
   "Comment": "Offboard machine by automation"
@@ -88,7 +84,7 @@ Content-type: application/json
     "requestorComment": "offboard machine by automation",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:09:24.1785079Z",
     "lastUpdateTimeUtc": "2017-12-04T12:09:24.1785079Z" 
 }

windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Restrict execution of all applications on the machine except a predefined set.
+Restrict execution of all applications on the machine except a predefined set (see [Response machine alerts](respond-machine-alerts-windows-defender-advanced-threat-protection.md) for more information)
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -39,7 +39,7 @@ POST /api/machines/{id}/restrictCodeExecution
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 ## Request body
@@ -60,7 +60,7 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 Here is an example of the request.
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/restrictCodeExecution 
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/restrictCodeExecution 
 Content-type: application/json
 {
   "Comment": "Restrict code execution due to alert 1234"
@@ -71,11 +71,7 @@ Content-type: application/json
 
 Here is an example of the response.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 HTTP/1.1 201 Created
@@ -88,9 +84,12 @@ Content-type: application/json
     "requestorComment": "Restrict code execution due to alert 1234",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:15:04.3825985Z",
     "lastUpdateTimeUtc": "2017-12-04T12:15:04.3825985Z" 
 }
 
 ```
+
+To remove code execution restriction from a machine, see [Remove app restriction](unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md).
+

windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Initiate Windows Defender Antivirus scan on the machine.
+Initiate Windows Defender Antivirus scan on a machine.
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -39,7 +39,7 @@ POST /api/machines/{id}/runAntiVirusScan
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json
 
 ## Request body
@@ -68,7 +68,7 @@ If successful, this method returns 201, Created response code and _MachineAction
 Here is an example of the request.
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/runAntiVirusScan 
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runAntiVirusScan 
 Content-type: application/json
 {
   "Comment": "Check machine for viruses due to alert 3212",
@@ -80,11 +80,7 @@ Content-type: application/json
 
 Here is an example of the response.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 HTTP/1.1 201 Created
@@ -97,7 +93,7 @@ Content-type: application/json
     "requestorComment": "Check machine for viruses due to alert 3212",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:18:27.1293487Z",
     "lastUpdateTimeUtc": "2017-12-04T12:18:27.1293487Z"
 }

windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md

@@ -39,7 +39,7 @@ POST /api/machines/{id}/unisolate
 
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 
@@ -60,14 +60,10 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/unisolate 
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unisolate 
 Content-type: application/json
 {
   "Comment": "Unisolate machine since it was clean and validated"
@@ -92,10 +88,12 @@ Content-type: application/json
     "requestorComment": "Unisolate machine since it was clean and validated ",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:13:15.0104931Z",
     "lastUpdateTimeUtc": "2017-12-04T12:13:15.0104931Z" 
 }
 
-
 ```
+
+To isolate a machine, see [Isolate machine](isolate-machine-windows-defender-advanced-threat-protection-new.md).
+

windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md

@@ -38,7 +38,7 @@ POST /api/machines/{id}/unrestrictCodeExecution
 ## Request headers
 Name | Type | Description
 :---|:---|:---
-Authorization | string | Bearer {token}. **Required**.
+Authorization | String | Bearer {token}. **Required**.
 Content-Type | string | application/json. **Required**.
 
 ## Request body
@@ -58,14 +58,10 @@ If successful, this method returns 201 - Created response code and [Machine Acti
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
-POST https://api.securitycenter.windows.com/api/machines/fb9ab6be3965095a09c057be7c90f0a2/unrestrictCodeExecution 
+POST https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/unrestrictCodeExecution 
 Content-type: application/json
 {
   "Comment": "Unrestrict code execution since machine was cleaned and validated"
@@ -88,9 +84,11 @@ Content-type: application/json
     "requestorComment": "Unrestrict code execution since machine was cleaned and validated ",
     "status": "InProgress",
     "error": "None",
-    "machineId": "f46b9bb259ed4a7fb9981b73510e3cc7aa81ec1f",
+    "machineId": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
     "creationDateTimeUtc": "2017-12-04T12:15:40.6052029Z",
     "lastUpdateTimeUtc": "2017-12-04T12:15:40.6052029Z"
 }
 
 ```
+
+To restrict code execution on a machine, see [Restrict app execution](restrict-code-execution-windows-defender-advanced-threat-protection-new.md).

windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md

@@ -21,7 +21,7 @@ ms.date: 12/08/2017
 
 - Windows Defender Advanced Threat Protection (Windows Defender ATP)
 
-Update the properties of an alert object.
+Update the properties of an alert entity.
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Create your app](exposed-apis-windows-defender-advanced-threat-protection-new.md#create-an-app)
@@ -55,8 +55,7 @@ determination | String | Specifies the determination of the alert. The property
 
 
 ## Response
-If successful, this method returns 200 OK, and an [alert](alerts-windows-defender-advanced-threat-protection-new.md) object in the response body with the updated properties.
+If successful, this method returns 200 OK, and the [alert](alerts-windows-defender-advanced-threat-protection-new.md) entity in the response body with the updated properties. If alert with the specified id was not found - 404 Not Found.
-If alert with the specified id was not found - 404 Not Found.
 
 
 ## Example
@@ -65,16 +64,11 @@ If alert with the specified id was not found - 404 Not Found.
 
 Here is an example of the request.
 
->[!NOTE]
+[!include[Improve request performance](improverequestperformance-new.md)]
->For better performance, you can use server closer to your geo location:
-> - api-us.securitycenter.windows.com
-> - api-eu.securitycenter.windows.com
-> - api-uk.securitycenter.windows.com
 
 ```
 PATCH https://api.securitycenter.windows.com/api/alerts/636688558380765161_2136280442
 Content-Type: application/json
-
 {
 	"assignedTo": "Our designated secop"
 }
@@ -87,7 +81,7 @@ Here is an example of the response.
 ```
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
-    "id": "636692338844234222_1806644926",
+    "id": "636688558380765161_2136280442",
     "severity": "Medium",
     "status": "InProgress",
     "description": "An anomalous memory operation appears to be tampering with a process associated with the Windows Defender EDR sensor.",