Get the Device Inventory
Get a list of all the devices in your IoT Security inventory.
Rate limiting: 60 times per minute
Query Parameters
The customer ID to which the API call is directed
An optional string that sets the start of a time range for devices to retrieve. This is the time when a device was last active. (It’s unnecessary to set etime=now or etime=
An optional integer that sets the number of items to skip
An optional integer that sets the number of items in one response; that is, in one page. The maximum page length you can set is 1000. The default page length for alerts, devices, and vulnerability instances is 1000. Because of these high default values, we recommend setting the page length to a smaller number, especially for alerts and vulnerabilities.
Possible values: [true
, false
]
The return of more device attributes (true) or fewer attributes (false)
Possible values: [asc
, desc
]
The alphanumeric order in which devices are displayed by MAC address. asc indicates an ascending order from smallest tolargest. desc, which is the default, indicates a descending order from largest to smallest.
The device attribute to use for sorting. Currently only MAC is supported.
Possible values: [yes
, no
]
Field to filter devices with traffic restricted
- 200
- 4XX
- 5XX
Successful Response (We only show some important fields here.)
Schema
- Array [
- Array [
- ]
- ]
The number of devices matching the request
devices object[]
An array containing device details
The device ID, which IoT Security uses to identify and track a device
The device hostname
The category to which the device belongs
The device profile assigned to the device
The type of device profile, such as IoT or Non_IoT
The industry vertical for the profile such as Medical, IT Devices, and Office
The IP address of a device
The MAC address of a device
The risk score of a device
The risk level of a device. There are four: low, medium, high, and critical
A UTC timestamp for the last detected device activity
The confidence score for device classification
A list of IDs for user- and system-defined tags assigned to a device
allTags object[]
An array of user-defined tags assigned to a device. Each item in the array consists of three attributes: tagType, tagValue, and tagId.
The key for a user-defined tag
The value of the tag key for a user-defined tag
The ID of a user-defined tag
Whether traffic restriction is being applied to a device (yes) or not (no)
{
"total": 0,
"devices": [
{
"deviceid": "string",
"hostname": "string",
"category": "string",
"profile": "string",
"profile_type": "string",
"profile_vertical": "string",
"ip_address": "string",
"mac_address": "string",
"risk_score": 0,
"risk_level": "string",
"last_activity": "2023-09-29T17:03:13.129Z",
"confidence_score": "string",
"tagIdList": [
null
],
"allTags": [
{
"tagType": "string",
"tagValue": "string",
"tagId": "string"
}
],
"trafficRestricted": true
}
]
}
{
"total": 1,
"devices": [
{
"deviceid": "34:02:86:44:65:36",
"hostname": "InfusionPump-20",
"category": "Infusion System",
"profile": "Sigma Spectrum Infusion System",
"profile_type": "IoT",
"profile_vertical": "Medical",
"ip_address": "192.168.10.121",
"mac_address": "34:02:86:44:65:36",
"risk_score": 0,
"risk_level": "low",
"last_activity": "2018-05-31T18:39:37.404Z",
"confidence_score": "90",
"allTags": [
{
"tagType": "zzzNoTagTypeABC",
"tagValue": "special_blocked",
"tagId": "60f221a219e22f10003a965e"
}
],
"trafficRestriced": true
}
]
}
Client Error Response
Schema
STATUS_CODE
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 400,
"msg": "Bad Request. This occurs when an HTTP request contains an invalid query string."
}
{
"code": 403,
"msg": "Forbidden access. Either the provided API key is invalid or it does not have the required RBAC permissions to run this API."
}
{
"code": 429,
"msg": "Too many requests. The number of requests for device details for a single device exceeded the rate limit of 180 queries per minute per tenant."
}
Server Error Response
Schema
STATUS_CODE
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 500,
"msg": "Internal server error. A unified status for API communication type errors."
}