Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.binarly.io/llms.txt

Use this file to discover all available pages before exploring further.

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
HeaderValue
AuthorizationBearer <access_token>
Content-Typeapplication/json
Body
FieldRequiredDescription
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:
FieldValuesDescription
productId<product_id>Required scope filter - Product ID to query
imageId<image_id>Alternative scope filter - Specific image ID
issueStatusnew, inProgress, remediated, rejectedWorkflow status of the finding
severitycritical, high, medium, low, informationalFinding severity level
findingTypeknownVulnerability, maliciousCode, dependencyVulnerabilityType 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"
      }
    }
  ]
}
FieldDescription
totalTotal count of findings matching criteria
rowsArray of finding objects