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

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?token=token

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Header
Accept-Language (optional)
Values
en-US (only English is supported)

Negotiates the language of the response. If the header is not specified, the content is returned in the server language.

Request format application/json
Response headers
Header
Content-Type
Values
application/json

Specifies the content type of the response.

Header
Content-Language
Values
en-US, …

Specifies the language of the response content. If the header is not specified, the content is returned in the server language.

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 api/sam/v2/schemas/computer.json?token=token

Available columns

Table 2. Available columns
Column Description Displayed by default Type
id Identifier of the computer as defined in BigFix Inventory. Numeric
bigfix_id Identifier of the computer as defined in BigFix. Numeric
computer_group_id Identifier of the BigFix Inventory computer group to which the computer belongs. The value 0 represents the All Computers group. Numeric
name Name of the computer. String
dns_name DNS of the computer. String
ip_address IP address of the computer. String
os Operating system of the computer. String
os_type Type of the operating system 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
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
is_deleted Information whether the computer was removed. Boolean
deletion_date Date and time when the computer was removed. The time is specified in the GMT time zone. String
is_managed_by_vm_manager Information whether the computer is managed by a VM manager. Boolean

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 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
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
token A unique user authentication identifier. You can retrieve it by using REST API for retrieving authentication token. You can also log in to BigFix Inventory, hover over the User icon User icon, and click Profile. Then, click Show token. Alphanumeric
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 api/sam/v2/computers?token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"name":"NC9143126194",
"ip_address":["9.143.126.194"],
"os":"Win2012R2 6.3.9600",
"last_seen":"2016-09-22T10:32:12Z",
"is_deleted":1
}]

Example conversation - all columns

Request
GET 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
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"id":2,
"bigfix_id":11368943,
"computer_group_id":0,
"name":"NC9143126194",
"dns_name":"NC9143126194",
"ip_address":["9.143.126.194"],
"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 api/sam/v2/computers?columns[]=id
&columns[]=is_deleted&columns[]=deletion_date
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"id":21,
"is_deleted":1,
"deletion_date":"2016-10-18T14:51:52Z"
}]

Example conversation - association

Request
GET api/sam/v2/computers?columns[]=id
&columns[]=computer_health.catalog_version
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
Host: localhost:9081 
Accept: application/json 
Accept-Language: en-US
Response body
[{
"id":1,
"catalog_version":1304630
}]