Compare Findings

Search, filter, and compare security findings using the advanced Grid API.

When to Use This Endpoint

Use this endpoint when you need to:

Compare Images: Identify regressions between two binary file versions.
Advanced Filtering: Filter findings by complex criteria not available in the simple list.
Export: Retrieve findings page by page, or as a CSV file.

Request

Endpoint

POST <BINARLY_API_URL>/api/v4/grids/findings:gridList

Headers

Header	Value
`Authorization`	`Bearer <access_token>`
`Content-Type`	`application/json`

Query Parameters

Parameter	Required	Description
`contentType`	No	Set to `csv` to download the results as CSV

Body

Field	Required	Description
`filters`	No	Array of filter objects (see Filter Reference)
`page`	No	`num` (page number, starts at 1) and `size` (default 10, maximum 100)
`sortBy`	No	`field` and `direction` (`ascend` or `descend`)
`fields`	No	Array of field names to return for each finding

Filter Reference

Filters are optional. Without a productId, imageId or comparison filter, the request returns all findings you can access. The API ignores unknown filter fields without an error, so check field names against this table.

Supported filter fields:

Field	Values	Description
`productId`	`<productId>`	Limit results to one product
`imageId`	`<imageId>`	Limit results to one image
`issueStatus`	`new`, `inProgress`, `remediated`, `rejected`	Workflow status of the finding. Use the `in` comparator
`severity`	`critical`, `high`, `medium`, `low`, `unspecified`	Finding severity level
`type`	`knownVulnerability`, `unknownVulnerability`, `maliciousCode`, `suspiciousCode`, `dependencyVulnerability`, `cryptographicAsset`, `mitigation`, `weakness`, `supplyChainFailure`, `secret`, `leakedSecret`, `uncategorized`	Type of finding. Use the `in` comparator
`compareLeftImageId`	`<imageId>`	Baseline image ID for comparison
`compareRightImageId`	`<imageId>`	Target image ID for comparison
`compareSide`	`left`, `right`, `both`	With a comparison: only in the baseline (resolved), only in the target (new), or in both (unchanged)

Example Request - Compare Images

To identify what changed between a baseline and a target image:

BASELINE_ID="01JQPGDX8QW0YJ0XEKV1EVG534"
TARGET_ID="01JYJ0W0AACGC7QT1Q21SRWG94"

curl -s -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "compareLeftImageId", "value": "'"${BASELINE_ID}"'", "comparator": "equals"},
      {"field": "compareRightImageId", "value": "'"${TARGET_ID}"'", "comparator": "equals"},
      {"field": "compareSide", "value": "right", "comparator": "equals"},
      {"field": "issueStatus", "value": ["new", "inProgress"], "comparator": "in"}
    ],
    "page": {"num": 1, "size": 100}
  }' \
  "${BINARLY_API_URL}/api/v4/grids/findings:gridList"

This returns the open findings that are new in the target image. Use left for findings resolved since the baseline, or leave out compareSide to get all three groups.

The issueStatus filter requires the in comparator with an array of status values, not equals with a single string.

Response

Returns one page of findings and the total number of matches. The example shows a few of the fields each row contains.

{
  "total": 23,
  "rows": [
    {
      "id": "01K6Z3V9Q2M7XH4D8RTN5B1C0E",
      "name": "vulnerability/uefi/dxe/arbitrary-write-via-pointer-via-nvram-variable",
      "displayName": "DXE Memory Corruption",
      "severity": "high",
      "type": "unknownVulnerability",
      "issueStatus": "new",
      "compareSide": "right"
    }
  ]
}

Field	Description
`total`	Total count of findings matching criteria
`rows`	Array of finding objects for the requested page
`rows[].id`	Finding ID
`rows[].name`	Finding rule name
`rows[].displayName`	Human-readable finding name
`rows[].severity`	Severity level
`rows[].type`	Finding type
`rows[].issueStatus`	Workflow status
`rows[].compareSide`	Only with a comparison: `left` (resolved), `right` (new) or `both` (unchanged)

Overview

Use Cases

Reference

When to Use This Endpoint

Request

Filter Reference

Example Request - Compare Images

Response