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: