Retrieval of hardware inventory (v2)
Available from 9.2.8.
You use the GET
operation
on the api/sam/v2/computers
element to request information about computers in your
infrastructure. The API returns details of existing computers as well as historical data about
computers that were removed.
Permissions
You must have the View Endpoints and View Hardware Inventory permission to use this
API.
Resource URL
https://hostname:port/api/sam/v2/computers
Resource information
Operation details | Description |
---|---|
HTTP method | GET |
Request headers |
|
Request format | application/json |
Response headers |
|
Response payload | Computer Systems element |
Response format | application/json |
Response codes |
|
Schema description
GET https://hostname:port/api/sam/v2/schemas/computer.json
Available columns
Column | Description | Displayed by default | Type |
---|---|---|---|
bigfix_id | Identifier of the computer as defined in BigFix®. For disconnected computers, the value is undefined. | Numeric | |
computer_group_id | Identifier of the main computer group of the user who sends the API request. The value 0 represents the All Computers group. | Numeric | |
![]() |
Identifier of the data source. | Numeric | |
![]() |
Name of the data source. | String | |
![]() |
Type of the data source. Possible values are:
|
Number | |
![]() |
Identifier of the disconnected computer as defined in the config/endpoint_id.txt file in the disconnected scanner folder. For computers that do not report to a disconnected data source, the value is null. | String | |
deletion_date | Date and time when the computer was removed. The time is specified in the GMT time zone. | String | |
dns_name | DNS of the computer. | String | |
first_seen | Date and time when the computer reported to BigFix for the first time. The time is specified in the GMT time zone. | String | |
id | Identifier of the computer as defined in License Metric Tool. | Numeric | |
ip_address | IP address of the computer. | ✓ | String |
is_deleted | Information whether the computer was removed. | ✓ | Boolean |
is_managed_by_vm_manager | Information whether the computer is managed by a VM manager. | Boolean | |
last_seen | Date and time when the computer reported to BigFix for the last time. The time is specified in the GMT time zone. | ✓ | String |
name | Name of the computer. | ✓ | String |
os | Operating system of the computer. | ✓ | String |
os_type | Type of the operating system of the computer. | String | |
partition_id | ID of the partition. For a VM running in a virtualization type that requires VM manager connection, the value is the attribute commonly referred to in IBM License Metric Tool as VM UUID (universally unique identifier of a VM). For a partition (LPAR or WPAR) running on a Power system, the value is the Partition ID. For a guest running on an IBM Z (z/VM guest, z/KVM guest or z/CX guest), it is the guest Name. For a VM running on a Microsoft Hyper-V, VMware ESXi, KVM, Citrix Hypervisor and Nutanix AVH managed by Nutanix PRISM it is SMBios System Serial Number. For a Solaris zone, it shows the zone Name. For a physical machine or computer running in a public cloud, it is no data. | String |
Applicable associations
For more information about how to use API associations, see: REST API associations.
null
.Query parameters
Parameter | Description | Required | Value |
---|---|---|---|
columns[] | Specify which columns to retrieve. If you do not specify this parameter, only
default columns are retrieved. Example: Retrieve product name and
release
|
String | |
order | Specify how to sort the returned data. The default direction for sorting
columns is ascending. If you want to specify a descending sort, append desc to the
column name. Example: Order by computer ID
descending:
|
String | |
limit | Specify the number of rows to retrieve. If you omit this parameter, all rows
are retrieved. Example: Retrieve 100 records
|
Numeric | |
offset | Specify the number of rows to skip for retrieving results. You can use it
together with the limit parameter to paginate results. Example: Retrieve 50 records starting
after record 150
|
Numeric | |
criteria | Retrieve records which match specific conditions. The parameter should have the following
structure, written in one line:
For more information about operators, see: Common connectors and operators. Example: retrieve
computers that reported for the first time within a specific date range:
For columns that use the date and time values, you can retrieve data also for a period instead of a specific date. To do so, use last or next as <operator>, and then specify the time value in the following convention: PxD/PxW/PxM/PxY, where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively. Example: Retrieve computers that were first reported within the last 7 days
|
String |
Example conversation - default columns
- Request
-
GET https://hostname:port/api/sam/v2/computers
- Request header
-
Accept: application/json Accept-Language: en-US Token: <token>
- Response body
-
[{ "name":"<name>", "ip_address":["<ip_address>"], "os":"Win2012R2 6.3.9600", "last_seen":"2016-09-22T10:32:12Z", "is_deleted":1 }]
Example conversation - all columns
- Request
-
GET https://hostname:port/api/sam/v2/computers ?columns[]=id&columns[]=bigfix_id&columns[]=computer_group_id &columns[]=name&columns[]=dns_name&columns[]=ip_address &columns[]=os&columns[]=os_type&columns[]=first_seen &columns[]=last_seen&columns[]=is_deleted &columns[]=deletion_date&columns[]=is_managed_by_vm_manager
- Request header
-
Accept: application/json Accept-Language: en-US Token: <token>
- Response body
-
[{ "id":2, "bigfix_id":11368943, "computer_group_id":0, "name":"<name>", "dns_name":"<name>", "ip_address":["<ip_address>"], "os":"Win2012R2 6.3.9600", "os_type":"Windows", "first_seen":"2016-10-04T09:42:55Z", "last_seen":"2016-09-22T10:32:12Z", "is_deleted":1, "deletion_date":"2016-12-19T09:40:14Z", "is_managed_by_vm_manager":0 }]
Example conversation - additional column
- Request
-
GET https://hostname:port/api/sam/v2/computers ?columns[]=id&columns[]=is_deleted&columns[]=deletion_date
- Request header
-
Accept: application/json Accept-Language: en-US Token: <token>
- Response body
-
[{ "id":21, "is_deleted":1, "deletion_date":"2016-10-18T14:51:52Z" }]
Example conversation - association
- Request
-
GET https://hostname:port/api/sam/v2/computers ?columns[]=id&columns[]=computer_health.catalog_version
- Request header
-
Accept: application/json Accept-Language: en-US Token: <token>
- Response body
-
[{ "id":1, "catalog_version":1304630 }]