Get the Device Inventory
Get a list of all the devices in your IoT Security inventory.
Rate limiting: 60 times per minute
Query Parameters
- customerid string required
The customer ID to which the API call is directed
- stime date-time
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=
- offset integer
An optional integer that sets the number of items to skip
- pagelength integer
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.
- detail string
Possible values: [
true
,false
]The return of more device attributes (true) or fewer attributes (false)
- sortdirection string
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.
- sortfield string
The device attribute to use for sorting. Currently only MAC is supported.
- trafficRestricted string
Possible values: [
yes
,no
]Field to filter devices with traffic restricted
Example: yes
- 200
- 4XX
- 5XX
Successful Response (We only show some important fields here.)
- application/json
- Schema
- Example (from schema)
- deviceInventoryResponseExample
Schema
- total integer
The number of devices matching the request
devices object[]
An array containing device details
Array [deviceid stringThe device ID, which IoT Security uses to identify and track a device
hostname stringThe device hostname
category stringThe category to which the device belongs
profile stringThe device profile assigned to the device
profile_type stringThe type of device profile, such as IoT or Non_IoT
profile_vertical stringThe industry vertical for the profile such as Medical, IT Devices, and Office
ip_address stringThe IP address of a device
mac_address stringThe MAC address of a device
risk_score integerThe risk score of a device
risk_level stringThe risk level of a device. There are four: low, medium, high, and critical
last_activity date-timeA UTC timestamp for the last detected device activity
confidence_score stringThe confidence score for device classification
tagIdList arrayA 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.
Array [tagType stringThe key for a user-defined tag
tagValue stringThe value of the tag key for a user-defined tag
tagId stringThe ID of a user-defined tag
]trafficRestricted booleanWhether 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-03-17T18:32:03.799Z",
"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
- application/json
- Schema
- Example (from schema)
- Bad Request
- Forbidden access
- Too many requests
Schema
- code string
STATUS_CODE
- msg string
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
- application/json
- Schema
- Example (from schema)
- deviceInventoryResponseExample
Schema
- code string
STATUS_CODE
- msg string
GENERAL_MESSAGE
{
"code": "string",
"msg": "string"
}
{
"code": 500,
"msg": "Internal server error. A unified status for API communication type errors."
}