Retrieving device data using the REST API

Device data can be retrieved using the devices resource. It allows you to:

• retrieve device data for all the devices within scope of the access rights of the account that is issueing the REST API call
• retrieve device data for a particular device that is identified by its device ID
• retrieve device data for devices that use a particular IP address
• retrieve software installed on a particular device that is identified by its device ID
• retrieve hardware modules installed in a particular device that is identified by its device ID.

The GET method is used for all operations mentioned above. The resulting content conforms to the Portable Inventory Data format.

Basic queries

Retrieving a single inventory item

GET ot-base/api/v1/devices/{deviceID}

Individual devices can be retrieved by specifying the device identifier in the API call. This will result in only the metadata for this particular device being returned.

Retrieving multiple inventory items

GET ot-base/api/v1/devices

Retrieves all devices within the scope of the access rights for the account that is issueing the API call.

The result contains an info element after the devices element which informs you about

• the total number of items for this query (total),
• the offset with which this query was started (offset), and
• the next offset that you need to use if you want to continue the listing (next_offset).

In the interest of not overloading the client, output will contain device data for a maximum of 100 devices by default. You can control the number of records that are transmitted by using the count parameter, followed by the desired number of records. In the following example, output stops after 300 records:

GET ot-base/api/v1/devices/?count=300

For an iterative download of device data you can define an offset from where you want OT-BASE to start data output. This is achieved by using the offset parameter, followed by the offset of the starting record. (Note that the numbering counts with zero.) You don't even need to keep track of the offset in your own software, OT-BASE takes care of that for you. The info item in the REST response shows in the next_offset field which offset you need to use to continue the listing.

In this example, OT-BASE tells us that output would resume at offset 300:

Hence, if we want to continue the listing, our API call would be

GET ot-base/api/v1/devices/?offset=300

Search filters

Retrieving devices at a particular location

GET ot-base/api/v1/devices/?locationid=locationID

The locationid filter allows you to retrieve asset data for devices at a particular location, referenced by its location identifer. Output includes devices at any sub-location.

Retrieving devices associated with a particular OT system

GET ot-base/api/v1/devices/?otsystem=OTsystemName

Returns devices associated with a particular OT system, as referenced by its system name.

GET ot-base/api/v1/devices/?otsystemid=OTsystemID

Returns devices associated with a particular OT system, as referenced by its system identifier.

Retrieving devices with a particular IP address

The ipaddress filter can be used to search for devices that use a particular IP address:

GET ot-base/api/v1/devices/?ipaddress=X.X.X.X

where X.X.X.X is substituted by the IP address that you are searching.

Note that an IP address is not necessarily unique, therefore the search may return multiple results.

Retrieving devices that belong to a particular network

The networkid filter can be used to search for devices that belong to a particular network:

GET ot-base/api/v1/devices/?networkid=NetworkId

where NetworkId is substituted by the internal network ID that is automatically assigned by OT-BASE uses to reference the network. Note that this is not the IP address of the network.

Retrieving devices with a particular name

The name filter can be used to search for devices with a particular name:

GET ot-base/api/v1/devices/?name=xyz

where xyz is substituted by the name of the device that you are searching.

Note that a device name is not necessarily unique, therefore the search may return multiple results.

Retrieving only devices that have been changed since a particular point in time

GET ot-base/api/v1/devices/?modified=timestamp

will return only asset data for devices that have been changed since the specified timestamp, or have been added to the inventory since the timestamp.

The timestamp is specified in the ISO 8601 format and is based on UTC (Universal Time Coordinated). Higher-precision parts of the time stamp can be omitted, i.e. you don't have to specifiy milliseconds, seconds, minutes etc.

Example:

GET ot-base/api/v1/devices/?modified=2020-03-31T08:30

will retrieve devices that have changed or have been added since March 31, 2020, 8:30 a.m.

Output modifiers

By default, OT-BASE does not return software, module, or vulnerability data associated with inventory items. This data can be obtained by addressing sub-resources for individual devices, or by using output modifiers for bulk queries.

Retrieving the software or firmware associated with a single inventory item

GET ot-base/api/v1/devices/{deviceID}/software

The software installed on your Windows or *nix computers can be extensive, therefore software is not included in the inventory output by default. However you can retrieve software installed on any single device by accessing the software sub-resource, as in the command line above.

In the following example, we are retrieving the firmware installed on a device identified as "LU.BK12":

Retrieving the hardware modules associated with a single inventory item

GET ot-base/api/v1/devices/{deviceID}/modules

Hardware modules such as I/O interfaces are also not part of the standard output for the devices resource but can be retrieved using the modules sub-resource.

In the next example, we are retrieving the I/O modules of a device identified as "LU.BK12":

Retrieving known vulnerabilities for a single inventory item

GET ot-base/api/v1/devices/{deviceID}/vulnerabilities

Known vulnerabilities for a specific device can be queried by accessing the vulnerabilities sub-resource, as in the command line above.

Requesting software and firmware data

GET ot-base/api/v1/devices/?include=software
GET ot-base/api/v1/devices/{deviceID}/?include=software

Causes software and firmware data to be included in the response.

Requesting vulnerability data

GET ot-base/api/v1/devices/?include=vulnerabilities
GET ot-base/api/v1/devices/{deviceID}/?include=vulnerabilities

Causes vulnerability data to be included in the response.

Requesting hardware module data

GET ot-base/api/v1/devices/?include=modules
GET ot-base/api/v1/devices/{deviceID}/?include=modules

Causes hardware module data to be included in the response.

Requesting multiple sub-resources

"Include" modifiers can be combined in order to request the inclusion of multiple sub-resources. For example,

GET ot-base/api/v1/devices/?include=software,vulnerabilities
GET ot-base/api/v1/devices/{deviceID}/?include=software,vulnerabilities

will cause both software and vulnerability data to be included in the response.

When all sub-resources shall be included, the following query can be used:

GET ot-base/api/v1/devices/?include=all
GET ot-base/api/v1/devices/{deviceID}/?include=all

Videos