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 large datasets of findings.

Request

Endpoint

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

Headers

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

Body

Field	Required	Description
`filters`	✅	Array of filter objects (see example)

Filter Reference

[!IMPORTANT] The grid API requires at least one scope filter (productId or imageId) to return results. Requests without a scope filter may return 400 Bad Request.

Supported filter fields:

Field	Values	Description
`productId`	`<product_id>`	Required scope filter - Product ID to query
`imageId`	`<image_id>`	Alternative scope filter - Specific image ID
`issueStatus`	`new`, `inProgress`, `remediated`, `rejected`	Workflow status of the finding
`severity`	`critical`, `high`, `medium`, `low`, `informational`	Finding severity level
`findingType`	`knownVulnerability`, `maliciousCode`, `dependencyVulnerability`	Type of finding
`compareLeftImageId`	`<image_id>`	Baseline image ID for comparison
`compareRightImageId`	`<image_id>`	Target image ID for comparison

Example Request - Compare Images

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

BASELINE_ID="01JQ..."
TARGET_ID="01JY..."

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": "issueStatus", "value": ["new", "inProgress"], "comparator": "in"}
    ]
  }' \
  "${BINARLY_API_URL}/api/v4/grids/findings:gridList"

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

Response

Returns a paginated list of findings with comparison status.

{
  "total": 5,
  "rows": [
    {
      "id": "finding_123",
      "pname": "OpenSSL Vulnerability",
      "severity": "high",
      "comparison": {
        "status": "new"
      }
    }
  ]
}

Field	Description
`total`	Total count of findings matching criteria
`rows`	Array of finding objects

Overview

Use Cases

Reference

When to Use This Endpoint

Request

Filter Reference

Example Request - Compare Images

Response

​When to Use This Endpoint

​Request

​Filter Reference

​Example Request - Compare Images

​Response

When to Use This Endpoint

Request

Filter Reference

Example Request - Compare Images

Response