Unified Software API to combine package data and software instance data

10.0.5 With the /api/sam/unified/current/software API, you can view the currently installed software instances and package data together.

Simplified integrations with one API that covers discovered software

The API shows the following information:
  • Currently installed software instances and package data
  • Software instances and package data that are not suppressed
  • Package data that is not recognized
  • The computer data that can be accessed through computer association, such as computer association

Permissions

User You must have the View Endpoints and View Raw Data permissions to use this API.

Resource URL

https://hostname:port/api/sam/unified/current/software?token=<token>

Syntax

GET /api/sam/unified/current/software?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 Unified Software element
Response format application/json
Response codes

200 – OK

400 – "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 association together with their descriptions, use the following request:
GET /api/sam/unified/current/schemas/software.json?token=<token>

Available columns

Table 2. Columns with information about computer details
Column Description Displayed by default Type
id Identifier of the component instance or package. ✓ Numeric
name Name of the component or package. ✓ String
release Release of the component or package version. ✓ String
detailed_version Detailed version of the component or package version. ✓ String
discoverable_guid Globally unique identifier (GUID) of the component or sha1 of the package. ✓ String
discoverable_family_guid Family GUID of the component. For packages, the returned value is null. ✓ String
publisher_name Component publisher or package vendor. ✓ String
discovery_start Date and time when the component or package was reported for the first time. The time is specified in the GMT time zone. ✓ String
discovery_path The installation path is available on /api/sam/raw_unix_package_facts and /api/sam/unified/current/software APIs.

For BigFix Inventory version below 10.0.12:
  • For component instance: path to the folder where the component is installed
  • For Windows packages: returned value is null
  • For Unix packages: returned value is null
From BigFix Inventory version 10.0.12:
  • For component instance: path to the folder where the component is installed
  • For Windows packages: it is the package installation path
  • For Unix packages: returned value is null

10.0.13 From BigFix Inventory version 10.0.13:

  • Starting from version 10.0.13, the installation path is also collected for Linux packages.
Important: For packages with long installation path, the installation path is truncated. In some cases the installation path is empty. For example, for the libraries.
 ✓ String
Note:

In BigFix Inventory version 10.0.15, the defect in which 'discovery_path' property contains an unwanted end-of-line (eol) ' \n' character at the end of the path has been fixed. The path, for example, "C:\Program Files (x86)\Mozilla Firefox\n".
source Type of the software:
  • 0: component instance
  • 1: Windows package
  • 2: Unix package
 Numeric
computer.id ID of the computer where the software is discovered. ✓ Numeric
computer.name Name of the computer where the software is discovered. ✓ String

Applicable association

You can additionally retrieve data from the computer association.

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 release
URL?columns[]=name&columns[]=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 ID descending
URL?order[]=id desc
 Alphanumeric
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 that 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-number> | <json-null>

For more information about operators, see: Common connectors and operators.

Example: Retrieve a software instance whose name contains "BigFix" or the discovery start is within a specific date range
URL?criteria={ "or": [ ["name", "contains", "BigFix"], 
{ "and": [ ["discovery_start", ">", "2018-10-01T00:00:00+00:00Z"], 
["discovery_start", "<", "2018-10-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.

Example: Retrieve software instances that were first reported within the last 7 days
URL?criteria={"and":[["discovery_start","last","P7D"]]}
 String

Example conversations

To review the suppressed windows packages, use the following API:
GET api/sam/raw_package_facts?columns[]=name&columns[]=
is_suppressed&columns[]=comment&criteria=
{"and":[["is_suppressed","=",1]]}
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
To review the suppressed UNIX packages, use the following API:
GET api/sam/raw_unix_package_facts?columns[]=name&columns[]=
is_suppressed&columns[]=comment&criteria=
{"and":[["is_suppressed","=",1]]}
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
To review the suppressed software instances, use the following API:
GET /api/sam/v2/software_instances?columns[]=component_name&columns[]
=component_release&columns[]=is_suppressed&columns[]=exclusion_or_suppress_comment&criteria=
{"and":[["is_suppressed","=",1]]}
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623
To view associated computer data, use the following API:
GET /api/sam/unified/current/software?columns[]=name&columns[]=release&columns[]
=computer.name&columns[]=computer.ip_address
&token=7adc3efb175e2bc0f4484bdd2efca54a8fa04623