Articles in this section

See more

Retrieving Device Data

  • Updated
Follow

With the REST API, you can retrieve information related to your devices. The /devices endpoint allows you to retrieve data related to the devices within the access rights of the account issuing the API request. The devices endpoint allows you to perform the following actions:

  • Retrieve data for all devices
  • Retrieve data for a specific device identified by its unique device ID
  • Retrieve data for devices that use a particular IP address
  • Retrieve information about the software installed for a device identified by its unique device ID
  • Retrieve information about the hardware modules installed for a device identified by its unique device ID.

All of the above-mentioned operations are performed via the GET method. The responses from our API adheres to the Portable Inventory Data format and is designed to be human readable and easily  understood. With the devices endpoint, you can gather comprehensive information about the devices that are associated with your account and manage them accordingly.

Follow along with our Postman Collection

You may access requests to the Device endpoint via the Device data folder on our Postman collection

device.gif

Basic queries

Retrieve a single inventory item

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.

Request:

GET ot-base/api/v1/devices/deviceID
import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID

response = requests.get(url, auth=auth)

print(response.status_code)
print(response.text)

 

Retrieve multiple inventory items

If no device ID is specified within the request then all devices within the scope of the requesting user's access rights will be returned.

Note: To prevent overloading the client, information for a maximum of 100 devices is returned by default.

Request:

GET ot-base/api/v1/devices
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

response = requests.get(url, auth=auth)

print(response.status_code)
print(response.text)

 

The Envelope and Pagination

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

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

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.

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Set a numerical for the count parameter
params = {'count': 300}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

For an iterative download of device data you can define an offset from where you want OTbase to start data output. This code by using the offset parameter, followed by the offset of the starting record. (Note that the numbering starts with zero.) You don't even need to keep track of the offset in your own software, OTbase 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, OTbase tells us that output would resume at offset 300:

next_offset.png

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

Request:

GET ot-base/api/v1/devices/?offset=300
import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Set a numerical amount offest parameter
params = {'offset': 300}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Search filters

Retrieve devices at a particular location

By setting the locationid search filter to an existing location id, you will be able to retrieve asset data for devices at that particular location.

Note: The output will also include devices at any sub-location.

Request:

GET ot-base/api/v1/devices/?locationid=enterLocationID
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Replace enterLocationID with a location id between the quotes.
params = {'locationid': 'enterLocationID'} 

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Retrieve devices associated with a particular OT system

Setting the otsystemsearch filter to the name of an existing OT system will return devices associated with that particular OT system.

Request:

GET ot-base/api/v1/devices/?otsystem=enterOTSystemName
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes.
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Replace enterOTSystemName with an otsystem name between the quotes.
params = {'otsystem': 'enterOTSystemName'}  

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

You can also reference an OT system by ID by using the otsystemid search filter in the request URL to return devices associated with a particular OT system

Request:

GET ot-base/api/v1/devices/?otsystemid=enterOTsystemID
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Replace 'enterOTsystemID' with a otsystem id.
params = {'otsystemid': 'enterOTsystemID'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

Retrieve devices with a particular IP address

The ipaddress search filter is used to find for devices that use a particular IP address.

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

Request:

GET ot-base/api/v1/devices/?ipaddress=enterIPaddress
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'

# Replace enterIPaddress with an acutal IP address between the quotes.
params = {'ipaddress': 'enterIPaddress'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Retrieve devices that belong to a particular network

The networkid search filter is used to find devices belonging to a particular network. Here, networkid does not refer to the IP address of the network. It refers to the internal network ID that is automatically assigned by OTbase to reference the network.

Request:

GET ot-base/api/v1/devices/?networkid=enterNetworkId
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'          

# Replace enterNetworkId with a network id bewteen the quotes.
params = {'networkid': 'enterNetworkId'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Retrieve devices with a particular name

The name search filter is used to search for devices with a particular name.

Note: Device names are not necessarily unique, therefore the search may return multiple results.

Request:

GET ot-base/api/v1/devices/?name=enterDeviceName
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'          

# Replace enterDeviceName with a device name between the quotes.
params = {'name': 'enterDeviceName'} 

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Retrieve devices changed since a specific time

The modifiedsearch filter gives you information about devices that were either added to the inventory after the specified time or have been changed since then. You must supply a datetime in the ISO 8601 format based on UTC

Note: Detailed time information such as milliseconds, seconds, or minutes are not needed.

Request:

GET ot-base/api/v1/devices/?modified=enterTimestamp
import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices'          

# Between the quotes, replace enterTimestamp with a timestamp value (ex: '2023-01-31T08:30').
params = {'modified': 'enterTimestamp'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

Example:

This request retrieves devices that have changed or have been added since January 31, 2023, 8:30 a.m.

GET ot-base/api/v1/devices/?modified=2023-01-31T08:30

 

Output modifiers

By default, OTbase does not return software, module, administrator, 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.

 

Retrieve software or firmware associated with a single inventory item

The software installed on a Windows or Unix computer 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.

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/software'

response = requests.get(url, auth=auth)

print(response.status_code)
print(response.text)

Example:

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

 

Retrieve the hardware modules associated with a single inventory item

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

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/modules'

response = requests.get(url, auth=auth)

print(response.status_code)
print(response.text)

Example:

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

 

Retrieve known vulnerabilities for a single inventory item

Known vulnerabilities for a specific device can be queried by accessing the /vulnerabilities sub-resource, as in the request below.

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/vulnerabilities'

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)

 

Request software and firmware data

Setting the includeparameter to software causes software or firmware data to show up in the response for either all devices or single items.

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'

params={'include': 'software'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  

import requests

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'


url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'software'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

 

Request vulnerability data

Setting the includeparameter to vulnerabilities causes vulnerability data to show up in the response for either all devices or single items

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'

params={'include': 'vulnerabilities'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  

import requests  

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'


url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'vulnerabilities'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

 

Request hardware module data

Setting the includeparameter to modules causes module data to show up in the response for either all devices or single items.

Request:

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

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'

params={'include': 'modules'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  

import requests  

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'modules'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

 

Request local administrators

Setting the includeparameter to admins causes module data on local administrative accounts to be included in the response either all devices or single items.

Request:

GET ot-base/api/v1/devices/?include=admins
GET ot-base/api/v1/devices/{deviceID}/?include=admins
import requests            
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'            

params={'include': 'admins'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  


import requests  

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'admins'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

 

Request multiple sub-resources

The include modifier can be combined in order to request the inclusion of multiple sub-resources.

Example:

GET ot-base/api/v1/devices/?include=software,vulnerabilities
GET ot-base/api/v1/devices/{deviceID}/?include=software,vulnerabilities
import requests            
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'            

params={'include': 'software,vulnerabilities'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  

# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'software,vulnerabilities'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

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

 

Request all sub-resources

If all sub-resources need to included, you can set the include parameter to all.

Request:

GET ot-base/api/v1/devices/?include=all
GET ot-base/api/v1/devices/{deviceID}/?include=all
import requests            
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/' 

params={'include': 'all'}

response = requests.get(url, auth=auth, params=params)

print(response.status_code)
print(response.text)    

 

# ========== OR ==========  

import requests  
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID+'/'

params={'include': 'all'}

response = requests.get(url, auth=auth, params=params )

print(response.status_code)
print(response.text)

 

Videos

Related articles

Comments

0 comments

Please sign in to leave a comment.