Get the Device Inventory

GET 
/pub/v4.0/device/list

Get a list of all the devices in your IoT Security inventory.
Rate limiting: 60 times per minute

Request

Query Parameters

customerid stringrequired

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= because it is always treated as now.)

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

Responses

200

Successful Response (We only show some important fields here.)

application/json

Schema

Schema

total integer

The number of devices matching the request

devices object[]
An array containing device details
Array [
deviceid string
The device ID, which IoT Security uses to identify and track a device
hostname string
The device hostname
category string
The category to which the device belongs
profile string
The device profile assigned to the device
profile_type string
The type of device profile, such as IoT or Non_IoT
profile_vertical string
The industry vertical for the profile such as Medical, IT Devices, and Office
ip_address string
The IP address of a device
mac_address string
The MAC address of a device
risk_score integer
The risk score of a device
risk_level string
The risk level of a device. There are four: low, medium, high, and critical
last_activity date-time
A UTC timestamp for the last detected device activity
confidence_score string
The confidence score for device classification
tagIdList array
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.
Array [
tagType string
The key for a user-defined tag
tagValue string
The value of the tag key for a user-defined tag
tagId string
The ID of a user-defined tag
]
trafficRestricted boolean
Whether traffic restriction is being applied to a device (yes) or not (no)
]

Example (from schema)

{
  "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": "2024-04-19T21:44:40.195Z",
      "confidence_score": "string",
      "tagIdList": [
        null
      ],
      "allTags": [
        {
          "tagType": "string",
          "tagValue": "string",
          "tagId": "string"
        }
      ],
      "trafficRestricted": true
    }
  ]
}

deviceInventoryResponseExample

{
  "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
    }
  ]
}

4XX

Client Error Response

application/json

Schema

Schema

code string

STATUS_CODE

msg string

GENERAL_MESSAGE

Example (from schema)

{
  "code": "string",
  "msg": "string"
}

Bad Request

{
  "code": 400,
  "msg": "Bad Request. This occurs when an HTTP request contains an invalid query string."
}

Forbidden access

{
  "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."
}

Too many requests

{
  "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."
}

5XX

Server Error Response

application/json

Schema

Schema

code string

STATUS_CODE

msg string

GENERAL_MESSAGE

Example (from schema)

{
  "code": "string",
  "msg": "string"
}

deviceInventoryResponseExample

{
  "code": 500,
  "msg": "Internal server error. A unified status for API communication type errors."
}

Loading...