Integration API reference for on-premises management consoles (Public preview)
This article lists the APIs supported for integrating Microsoft Defender for IoT with partner services.
For example, this API is currently implemented with Tutorial: Integrate ServiceNow with Microsoft Defender for IoT, via the ServiceNow Service Graph Connector for Defender for IoT.
Note
Integration APIs are meant to run continuously and create a constantly running data stream, such as to query for new data from the last five minutes. Integration APIs return data with a timestamp.
To simply query data, use the regular, non-integration APIs instead, for either an on-premises management console to query all devices, or for a specific sensor to query devices from that sensor only. For more information, see Defender for IoT API reference.
URI: /external/v3/integration/
devices (Create and update devices)
This API returns data about all devices that were updated after the given timestamp.
URI: /external/v3/integration/devices/<timestamp>
URI parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
timestamp | The start time from which results are returned, in milliseconds from Epoch time and in UTC timezone. | /external/v3/integration/devices/1664781014000 |
Required |
GET
Query parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
sensorId | Return only devices seen by a specific sensor. Use the ID value from the results of the sensors (Get sensors) API. | 1 |
Optional |
notificationType | Determines the types of devices to return. Supported values include: - 0 : Both updated and new devices (default). - 1 : Only new devices. - 2 : Only updated devices. |
2 |
Optional |
page | Defines the number where the result page numbering begins. For example, 0 = first page is 0. Default = 0 |
0 |
Optional |
size | Defines the page sizing. Default = 50 |
75 |
Optional |
connections (Get device connections)
This API returns data about all device connections that were updated after the given timestamp.
URI: /external/v3/integration/connections/<timestamp>
URI parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
timestamp | The start time from which results are returned, in milliseconds from Epoch time and in UTC timezone. | /external/v3/integration/devices/1664781014000 |
Required |
GET
Query parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
page | Defines the number where the result page numbering begins. For example, 0 = first page is 0. Default = 0 |
0 |
Optional |
size | Defines the page sizing. Default = 50 |
75 |
Optional |
device (Get details for a device)
This API returns data about a specific device per a given device ID.
URI: /external/v3/integration/device/{deviceId}
GET
Query parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
deviceId | The ID of the requested device on the on-premises management console | 1 |
Required |
deleteddevices (Get deleted devices)
This API returns a list of IDs of recently deleted devices, from the supplied timestamp.
URI: /external/v3/integration/deleteddevices/
GET
URI parameters:
Name | Description | Example | Required / Optional |
---|---|---|---|
timestamp | The start time from which results are returned, in milliseconds from Epoch time and in UTC timezone. | /external/v3/integration/deleteddevices/1664781014000 |
Required |
sensors (Get sensors)
This API returns a list of sensor objects for connected OT network sensors.
URI: /external/v3/integration/sensors/
GET
URI: /sensors
No query parameters
devicecves (Get device CVEs)
This API returns a list of active CVEs for all devices that were updated since the supplied timestamp.
URI: /external/v3/integration/devicecves/
GET
URI: /external/v3/integration/devicecves/<timestamp>
URI parameters
Name | Description | Example | Required / Optional |
---|---|---|---|
timestamp | The start time from which results are returned, in milliseconds from Epoch time and in UTC timezone. | /external/v3/integration/devicecves/1664781014000 |
Required |
Query parameters
Name | Description | Example | Required / Optional |
---|---|---|---|
page | Defines the number where the result page numbering begins. | 0 = first page is 0. Default = 0 |
Optional |
size | Defines the page sizing. | Default = 50 |
Optional |
sensorId | Shows results from a specific sensor, as defined by the given sensor ID. | 1 |
Optional |
score | Determines a minimum CVE score to be retrieved. All results will have a CVE score equal to or greater than the given value. | Default = 0 . |
Optional |
deviceIds | A comma-separated list of device IDs from which you want to show results. | For example: 1232,34,2,456 |
Optional |
Next steps
For more information, see: