Skip to main content

Advanced Search REST API

APIs for automating the Advanced Search features.

Create the Advanced Search Index

Creating or rebuilding the index is demanding on IQ Server's database. The index will continue to process after making the request so have patience.

  • Requires user with the System Administrator role.

  • Allow many minutes for the request to complete

  • Avoid performing this operation during peak hours for large instances

POST /api/v2/search/advanced/index


curl -u admin:admin123 -X POST http://localhost:8070/api/v2/search/advanced/index

GET Advanced Search Results

Searches are made using GET requests. Parameters need to be URL-encoded for special characters.

GET /api/v2/search/advanced?query=query&pageSize=10&page=1

The mandatory query parameter is the string to search for. Query parameters: pageSize and page are optional with default values of 10 and 1 respectively.

The allComponents parameter is used to retrieve search results including components with no violations. The default value is false and optional.

For example, using a local installation of IQ Server with its default configuration, a request using the cURL tool would be:

curl -u admin:admin123 http://localhost:8070/api/v2/search/advanced?query=itemType%3Aorganization&pageSize=10&page=1&allComponents=true

In this request the ':' is URL encoded to '%3A'. As with the Advanced Search feature in the UI, asterisks '*' are wildcards and are URL encoded to %2A

When the search index does not exist or is unreadable, the request returns a 409 status code. Otherwise, a JSON response body is returned.




The requested search query.


The requested page number of the results.


The requested number of results per page.


The total number of results.


If the total number of results is exact, then this is true. Otherwise it's false indicating that this is a lower bound on the total number of results. An inexact value can happen when there is a large number of results making an exact count too expensive to compute.


An array where each element is a collection of search results that have been grouped according to some criteria.


The field name that the search results have been grouped on.


The field value that the search results have been grouped on.


This holds information shared between each element in a group e.g. when grouping on a security vulnerability, this is its description.


An array of search results, each of these will contain an itemType indicating what type of result it is as well as a resultIndex indicating the order of the result. A lower resultIndex indicates a more relevant result that will appear earlier. Additionally each element may contain properties representing field names and values relevant to its type.

An example of a successful response body for the above example search request is as follows:

    "searchQuery": "itemType:organization",
    "page": 1,
    "pageSize": 10,
    "totalNumberOfHits": 2,
    "isExactTotalNumberOfHits": true,
    "groupingByDTOS": [
            "groupIdentifier": "ITEM_TYPE",
            "groupBy": "ORGANIZATION",
            "additionalInfo": null,
            "searchResultItemDTOS": [
                    "itemType": "ORGANIZATION",
                    "organizationId": "ROOT_ORGANIZATION_ID",
                    "organizationName": "Root Organization",
                    "resultIndex": 1
                    "itemType": "ORGANIZATION",
                    "organizationId": "aadb7e6a9c1444378498af5e0f7decab",
                    "organizationName": "org",
                    "resultIndex": 2

GET Export CSV Search Results

Use the following endpoint to export the results in CSV format. The endpoint receives 2 parameters:

  • query parameter contains the search query

  • allComponents parameter to get non-violating components (defaults to false)

GET /api/v2/search/advanced/export/csv?query=query&allComponents=true

Fields are filled according to the item type, and an empty field means that the item type does not contain the value itself.


curl -u admin:admin123 -X GET http://localhost:8070/api/v2/search/advanced/export/csv?query=componentName%3Ajquery%2A > output.csv

The resulting .csv will contains violating components with a componentName field that matches the search phrase jquery*. As we did not use the allComponents parameter, our data is limited to components associated with a violation.

Delimiter for Advanced Search CSV Export

By default, the delimiter for advanced search CSV export is a comma, this delimiter can be changed using the Configuration REST API.

For prior releases use the config.yml property.

advancedSearchCSVExportDelimiter: ;