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
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.
API Request
Python Code
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.
API Request
Python Code
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 andnext_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.
API Request
Python Code
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:
Hence, if we want to continue the listing, our API call would be
API Request
Python Code
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.
API Request
Python Code
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 otsystem
search filter to the name of an existing OT system will return devices associated with that particular OT system.
API Request
Python Code
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
API Request
Python Code
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.
API Request
Python Code
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.
API Request
Python Code
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.
API Request
Python Code
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 modified
search 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.
API Request
Python Code
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.
API Request
Python Code
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.
API Request
Python Code
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.
API Request
Python Code
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 include
parameter to software causes software or firmware data to show up in the response for either all devices or single items.
API Request
Python Code
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 include
parameter to vulnerabilities causes vulnerability data to show up in the response for either all devices or single items
API Request
Python Code
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 compliance data
Setting the include
parameter to compliance causes compliance data to show up in the response for either all devices or single items
API Request
Python Code
Request:
GET ot-base/api/v1/devices/?include=compliance
GET ot-base/api/v1/devices/{deviceID}/?include=compliance
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': 'compliance'}
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': 'compliance'}
response = requests.get(url, auth=auth, params=params )
print(response.status_code)
print(response.text)
Request hardware module data
Setting the include
parameter to modules causes module data to show up in the response for either all devices or single items.
API Request
Python Code
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 include
parameter to admins causes module data on local administrative accounts to be included in the response either all devices or single items.
API Request
Python Code
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.
API Request
Python Code
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.
API Request
Python Code
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)
Comments
0 comments
Please sign in to leave a comment.