diff --git a/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md b/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
index d619963f4f..0e8ba41a5c 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/add-or-remove-machine-tags.md
@@ -18,10 +18,19 @@ ms.topic: article
# Add or Remove Machine Tags API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+**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
+Adds or remove tag to a specific [Machine](machine.md).
+
+
+## Limitations
+1. You can post on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-This API adds or remove tag to a specific machine.
## 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)
@@ -77,34 +86,4 @@ Content-type: application/json
"Action": "Add"
}
-```
-**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#Machine/$entity",
- "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
-}
-
-```
-
- To remove machine tag, set the Action to 'Remove' instead of 'Add' in the request body.
\ No newline at end of file
diff --git a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
index c803a1d4de..5976574977 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/find-machines-by-ip.md
@@ -18,13 +18,19 @@ ms.topic: article
# Find machines by internal IP API
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [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)
-Find machines seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.
-The given timestamp must be in the past 30 days.
+## API description
+Find [Machines](machine.md) seen with the requested internal IP in the time range of 15 minutes prior and after a given timestamp.
+
+
+## Limitations
+1. The given timestamp must be in the past 30 days.
+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)
@@ -70,37 +76,5 @@ Here is an example of the request.
[!include[Improve request performance](../../includes/improve-request-performance.md)]
```
-GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2018-09-22T08:44:05Z)
-```
-
-**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#Machines",
- "value": [
- {
- "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
- "lastSeen": "2018-09-22T08:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "10.248.240.38",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- }
- ]
-}
+GET https://api.securitycenter.windows.com/api/machines/findbyip(ip='10.248.240.38',timestamp=2019-09-22T08:44:05Z)
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
index 20ff89878c..be84e2c9ca 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-alert-related-machine-info.md
@@ -93,7 +93,7 @@ Content-type: application/json
"firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
"osPlatform": "Windows10",
- "version": null,
+ "version": "1709",
"osProcessor": "x64",
"lastIpAddress": "172.17.230.209",
"lastExternalIpAddress": "167.220.196.71",
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
index 2f8eda6c03..aaaa6abf4d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-by-id.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get machine by ID API
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [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 [Machine](machine.md) by its machine ID or computer name.
+
+
+## Limitations
+1. You can get machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-Retrieves a machine entity by ID.
## 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)
@@ -83,20 +91,22 @@ Content-type: application/json
{
"@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machine",
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
"rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
"machineTags": [ "test tag 1", "test tag 2" ]
}
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
index 9d364b0815..59e1357d2e 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-log-on-users.md
@@ -18,11 +18,19 @@ ms.topic: article
# Get machine log on users API
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [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 logged on users on a specific machine.
+
+
+## Limitations
+1. You can query on machines last seen in the past 30 days.
+2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-Retrieves a collection of logged on users.
## 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)
@@ -81,26 +89,19 @@ Content-type: application/json
"value": [
{
"id": "contoso\\user1",
- "firstSeen": "2018-08-02T00:00:00Z",
- "lastSeen": "2018-08-04T00:00:00Z",
- "mostPrevalentMachineId": null,
- "leastPrevalentMachineId": null,
- "logonTypes": "Network",
- "logOnMachinesCount": 3,
- "isDomainAdmin": false,
- "isOnlyNetworkUser": null
+ "accountName": "user1",
+ "accountDomain": "contoso",
+ "accountSid": "S-1-5-21-72051607-1745760036-109187956-93922",
+ "firstSeen": "2019-12-18T08:02:54Z",
+ "lastSeen": "2020-01-06T08:01:48Z",
+ "mostPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
+ "leastPrevalentMachineId": "111153d0c675eaa415b8e5f383c6388bff446c62",
+ "logonTypes": "Interactive",
+ "logOnMachinesCount": 8,
+ "isDomainAdmin": true,
+ "isOnlyNetworkUser": false
},
- {
- "id": "contoso\\user2",
- "firstSeen": "2018-08-02T00:00:00Z",
- "lastSeen": "2018-08-05T00:00:00Z",
- "mostPrevalentMachineId": null,
- "leastPrevalentMachineId": null,
- "logonTypes": "Network",
- "logOnMachinesCount": 3,
- "isDomainAdmin": false,
- "isOnlyNetworkUser": null
- }
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md b/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
index f6499ab7bb..dd13f88123 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machine-related-alerts.md
@@ -17,13 +17,20 @@ ms.topic: article
---
# Get machine related alerts API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-Retrieves a collection of alerts related to a given machine ID.
+**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 all [Alerts](alerts.md) related to a specific machine.
+
+
+## Limitations
+1. You can query on machines last seen in the past 30 days.
+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
:---|:---|:---
@@ -54,52 +61,3 @@ Empty
## Response
If successful and machine exists - 200 OK with list of [alert](alerts.md) entities in the body. If machine was not found - 404 Not Found.
-
-
-## Example
-
-**Request**
-
-Here is an example of the request.
-
-[!include[Improve request performance](../../includes/improve-request-performance.md)]
-
-
-```
-GET https://api.securitycenter.windows.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/alerts
-```
-
-**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#Alerts",
- "value": [
- {
- "id": "441688558380765161_2136280442",
- "incidentId": 8633,
- "assignedTo": "secop@contoso.com",
- "severity": "Low",
- "status": "InProgress",
- "classification": "TruePositive",
- "determination": "Malware",
- "investigationState": "Running",
- "category": "MalwareDownload",
- "detectionSource": "WindowsDefenderAv",
- "threatFamilyName": "Mikatz",
- "title": "Windows Defender AV detected 'Mikatz', high-severity malware",
- "description": "Some description",
- "alertCreationTime": "2018-11-25T16:19:21.8409809Z",
- "firstEventTime": "2018-11-25T16:17:50.0948658Z",
- "lastEventTime": "2018-11-25T16:18:01.809871Z",
- "resolvedTime": null,
- "machineId": "9d80fbbc1bdbc5ce968f1d37c72384cbe17ee337"
- }
- ]
-}
-```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/get-machines.md b/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
index 1434e0878e..31ef6bb72d 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/get-machines.md
@@ -18,17 +18,23 @@ ms.topic: article
# List machines API
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
-- [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)
-This API can do the following actions:
-- Retrieves a collection of machines that have communicated with Microsoft Defender ATP cloud on the last 30 days.
-- Get Machines collection API supports [OData V4 queries](https://www.odata.org/documentation/).
-- The OData's Filter query is supported on: "Id", "ComputerDnsName", "LastSeen", "LastIpAddress", "HealthStatus", "OsPlatform", "RiskScore", "MachineTags" and "RbacGroupId".
+## API description
+Retrieves a collection of [Machines](machine.md) that have communicated with Microsoft Defender ATP cloud on the last 30 days.
+
Supports [OData V4 queries](https://www.odata.org/documentation/).
+
The OData's ```$filter``` query is supported on: ```computerDnsName```, ```lastSeen```, ```lastIpAddress```, ```healthStatus```, ```osPlatform```, ```riskScore```, ```rbacGroupId``` and ```machineTags``` properties.
+
See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
+
+
+## Limitations
+1. You can get machines last seen in the past 30 days.
+2. Maximum page size is 10,000.
+3. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.
-See examples at [OData queries with Microsoft Defender ATP](exposed-apis-odata-samples.md)
## Permissions
@@ -88,42 +94,25 @@ Content-type: application/json
"value": [
{
"id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
- "computerDnsName": "mymachine1.contoso.com",
- "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
"lastSeen": "2018-08-02T14:55:03.7791856Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "172.17.230.209",
- "lastExternalIpAddress": "167.220.196.71",
- "agentVersion": "10.5830.18209.1001",
- "osBuild": 18209,
- "healthStatus": "Active",
- "rbacGroupId": 140,
- "rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "isAadJoined": true,
- "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
- "machineTags": [ "test tag 1", "test tag 2" ]
- },
- {
- "id": "7292e4b8cb74ff1cc3d8a495eb29dc8858b732f7",
- "computerDnsName": "mymachine2.contoso.com",
- "firstSeen": "2018-07-09T13:22:45.1250071Z",
- "lastSeen": "2018-07-09T13:22:45.1250071Z",
- "osPlatform": "Windows10",
- "osVersion": "10.0.0.0",
- "lastIpAddress": "192.168.12.225",
- "lastExternalIpAddress": "79.183.65.82",
- "agentVersion": "10.5820.17724.1000",
- "osBuild": 17724,
- "healthStatus": "Inactive",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
"rbacGroupId": 140,
"rbacGroupName": "The-A-Team",
- "riskScore": "Low",
- "isAadJoined": false,
- "aadDeviceId": null,
- "machineTags": [ "test tag 1" ]
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "test tag 2" ]
}
+ ...
]
}
```
diff --git a/windows/security/threat-protection/microsoft-defender-atp/machine.md b/windows/security/threat-protection/microsoft-defender-atp/machine.md
index ebf28c8c6d..4edb6f1e70 100644
--- a/windows/security/threat-protection/microsoft-defender-atp/machine.md
+++ b/windows/security/threat-protection/microsoft-defender-atp/machine.md
@@ -50,5 +50,31 @@ rbacGroupName | String | Machine group Name.
rbacGroupId | Int | Machine group unique ID.
riskScore | Nullable Enum | Risk score as evaluated by Microsoft Defender ATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
exposureScore | Nullable Enum | [Exposure score](tvm-exposure-score.md) as evaluated by Microsoft Defender ATP. Possible values are: 'None', 'Low', 'Medium' and 'High'.
-aadDeviceId | Nullable Guid | AAD Device ID (when [machine](machine.md) is Aad Joined).
+aadDeviceId | Nullable representation Guid | AAD Device ID (when [machine](machine.md) is Aad Joined).
machineTags | String collection | Set of [machine](machine.md) tags.
+
+
+## Json representation
+
+```json
+{
+ "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
+ "computerDnsName": "mymachine1.contoso.com",
+ "firstSeen": "2018-08-02T14:55:03.7791856Z",
+ "lastSeen": "2018-08-02T14:55:03.7791856Z",
+ "osPlatform": "Windows10",
+ "version": "1709",
+ "osProcessor": "x64",
+ "lastIpAddress": "172.17.230.209",
+ "lastExternalIpAddress": "167.220.196.71",
+ "osBuild": 18209,
+ "healthStatus": "Active",
+ "rbacGroupId": 140,
+ "rbacGroupName": "The-A-Team",
+ "riskScore": "Low",
+ "exposureLevel": "Medium",
+ "isAadJoined": true,
+ "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
+ "machineTags": [ "test tag 1", "test tag 2" ]
+}
+```
\ No newline at end of file