Unified Software API to combine package data and software instance data

Simplified integrations with one API that covers discovered software

Permissions

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

Schema description

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 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
is_processed	Indicates whether a component instance's processing has been completed. Value '1' means the processing has been completed. If the value is '0', some information (for example, classification details) may not be available until the next data import is finished. For package data, the value is always '1'. By default, only component instances with completed processing are returned. To return unprocessed component instances, use the 'include_unprocessed' parameter.		Boolean

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 , 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
include_unprocessed	Specify if the response should include unprocessed component instances. When not provided or set to 'false,' only component instances with completed processing are returned.		Boolean

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