Retrieval of hardware inventory (v2)

Edit online

9.2.8 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

User 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

Table 1. Resource information
Operation details	Description
HTTP method	`GET`
Request headers	`Accept-Language` (optional) Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language. Values: `en-US` (only English is supported) `Token` Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests. Values: an alphanumeric string that is generated in License Metric Tool
Request format	`application/json`
Response headers	`Content-Type` Use: Specifies the content type of the response. Values: `application/json` `Content-Language` Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language. Values: en-US, …
Response payload	`Computer Systems` element
Response format	`application/json`
Response codes	`200 – OK` `500 – “Bad Request”` if a query parameter contains errors or is missing

Schema description

To retrieve the list of all columns that are returned by this REST API together with their descriptions, use the following request.

GET https://hostname:port/api/sam/v2/schemas/computer.json

Available columns

Table 2. 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
datasource_id	Identifier of the data source.		Numeric
datasource_name	Name of the data source.		String
datasource_type	Type of the data source. Possible values are: 0 - BigFix data source 1 - disconnected data source		Number
disconnected_endpoint_id	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

You can additionally retrieve data from the following associations:

Note: Retrieving data from multiple API associations in a single request might increase the response time.

For more information about how to use API associations, see: REST API associations.

Important: All associations provide data about items that currently exist in the infrastructure. For removed computers and uninstalled software, these associations return null.

Query parameters

Table 3. Query parameters
Parameter	Description	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 `URL?columns[]=computer_group_id&columns[]=first_seen`	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: `URL?order[]=id desc`	String
limit	Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved. Example: Retrieve 100 records `URL?limit=100`	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 `URL?limit=50&offset=150`	Numeric
criteria	Retrieve records which match specific conditions. The parameter should have the following structure, written in one line: `<criteria> ::= <left-brace> <boolean-operator><colon> <left-bracket> <criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace> <boolean-operator> ::= "and" \| "or" <criterion> ::= <criteria> \| <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket> <column> ::= <json-string> <operator> ::= <json-string> <value> ::= <json-array> \| <json-string> \| <json-numver> \| <json-null>` For more information about operators, see: Common connectors and operators. Example: retrieve computers that reported for the first time within a specific date range: `URL?criteria={"and":[["first_seen", ">", "1970-01-01T00:00:00+00:00Z"], ["first_seen", "<", "1970-01-02T00:00:00+00:00Z"]]}` 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 `URL?criteria={"and":[["first_seen","last","P7D"]]}`	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
}]