Appliance management API reference for on-premises management consoles

This article lists the appliance management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.

appliances (Manage OT sensor appliances)

Use this API to manage your OT sensor appliances from an on-premises management console.

URI: /external/v1/appliances or /external/v2/appliances

GET

Request

No query parameters

Response

Type: JSON

A JSON array of appliance objects that represent sensor appliances.

Name	Type	Nullable / Not nullable	List of values
id	Long integer	Not nullable	The sensor ID
name	String	Not nullable	The sensor's name
interfaceAddress	String	Not nullable	The sensor's console URL
state	JSON array	Not nullable	A JSON array that describes the sensor's connection status. For more information, see XsenseState fields.
version	String	Not nullable	The software version currently installed on the sensor.
alertCount	Long integer	Not nullable	The total number of alerts currently active on the sensor.
deviceCount	Long integer	Not nullable	The number of devices currently detected by the sensor.
unhandledAlertsCount	long	Not nullable	The current number of unhandled alerts on the sensor.
isActivated	Boolean	Not nullable	One of the following: Activated or Unactivated
dataIntelligenceVersion	String	Not nullable	The version of threat intelligence data currently installed on the sensor
upgradeStatus	JSON array	Not nullable	A JSON array that describes the sensor's update status. For more information, see UpgradeStatusBean fields.
upgradeFinishTime	Long	Nullable	The time the last software update completed, in the following format: YYYY-MM-DD
hasLog	Boolean	Not nullable	Defines whether an upgrade log exists for the sensor.
zoneId	Long integer	Nullable	The ID of sensor's zone.
isInLearningMode	Boolean	Not nullable	Defines whether the sensor is currently in learning mode.

XsenseState fields

Name	Type	Nullable / Not nullable	List of values
id	Long integer	Not nullable	An internal, auto-incremented ID on the on-premises management console database.
xsenseId	Long integer	Not nullable	The sensor ID.
connectionState	A JSON array of datetime values	Not nullable	One of the following: SYNCED, OUT_OF_SYNC, TIME_DIFF_OFFSET, DISCONNECTED
cmSyncedUntil	DateTime	Not nullable	The timestamp for the most recent data sent from the sensor.
sensorSyncedUntil	DateTime	Not nullable	The timestamp for the last update from the on-premises management console to the sensor.
sensorLastMessage	DateTime	Not nullable	The timestamp for the last update from the sensor.

UpgradeStatusBean fields

Name	Type	Nullable / Not nullable	List of values
startTime	DateTime	Not nullable	The time the last update process was started.
percentage	Integer between 0-100	Not nullable	The completion percentage of the last update process.
stage	String	Not nullable	One of the following statues: - UPLOADING: Uploading Package - PREPARE_TO_INSTALL: Preparing To Install - STOPPING_PROCESSES Stopping Processes - BACKING_UP_DATA: Backing Up Data - TAKING_SNAPSHOT: Taking Snapshot - UPDATING_CONFIGURATION: Updating Configuration - UPDATING_DEPENDENCIES: Updating Dependencies - UPDATING_LIBRARIES: Updating Libraries - PATCHING_DATABASES: Patching Databases - STARTING_PROCESSES: Starting Processes - VALIDATING_SYSTEM_SANITY: Validating System Sanity - VALIDATION_SUCCEEDED_REBOOTING: Validation Succeeded - SUCCESS: Success - FAILURE: Failure - UPGRADE_STARTED: Upgrade Started - STARTING_INSTALLATION: Starting Installation - INSTALLING_OPERATING_SYSTEM: Installing OS

Response example

[
 {
    "dataIntelligenceVersion":"Dec 22, 2021",
    "name":"Microsoft Defender for IoT",
    "isActivated":true,
    "hasLog":false,
    "zoneId":null,
    "upgradeStatus":null,
    "deviceCount":22,
    "state":{
       "sensorLastMessage":1660217831000,
       "xsenseId":1,
       "sensorSyncedUntil":1660217741000,
       "connectionState":{
          "isConsideredConnected":true,
          "id":1,
          "description":"Connection is successful"
       },
       "cmSyncedUntil":1660217825000,
       "id":1
    },
    "version":"22.1.4.8-r-6372aad",
    "alertCount":9,
    "upgradeFinishTime":null,
    "uid":"a6218f1a-8ebf-4bb3-8613-c859b17eef01",
    "interfaceAddress":"https://173.70.549.76",
    "id":1,
    "unhandledAlertsCount":9
  }
]

cURL command

Type: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/appliances'

Example:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/appliances'

Next steps

For more information, see the Defender for IoT API reference overview.