Skip to main content
GET
List findings with optional filters

Authorizations

​
Authorization
string
header
required

An Earnie API key, sent as Authorization: Bearer sk_earnie_.... Create one under Settings > API keys. The key's scopes decide which operations it may call.

Query Parameters

​
org_id
string<uuid>

Optional. Defaults to the authenticated principal's organization. When supplied it MUST match the caller's org (else 403) — a principal can only ever list its own org's findings.

​
state
enum<string>
Available options:
open,
assigned,
resolved,
superseded_by_rule,
reopened
​
domain_slug
string
​
project_id
string<uuid>

Filter to findings belonging to this project

​
scan_id
string<uuid>

Filter by last_scan_run_id — findings last reconciled by this scan run. v1 limitation: if two scan runs observe the same identity hash, only the last reconcile result is visible.

​
scan_only
boolean

With true, narrow the scan's findings to the ones that are scan_only: read from a pull request scan's own result set with no standing project finding carrying their id. That is the set the pull request introduced, as the project stood when the scan published, and total counts exactly it. A scan that is not scan-scoped has no such finding, so the answer is empty. Requires scan_id; true without it is a 400. false or absent applies no filter.

​
purl
string

Filter findings by component PURL (matches rule_key, location_purl, or evidence purl).

​
path_prefix
string

Filter to findings whose location_path is exactly this value or a child of it (a directory subtree). Powers the review workspace's file-scoped reads — the rail's keyboard nav, auto-advance, and "open this file's findings" all need one file's findings without fetching the whole project. Do NOT pass a trailing slash — the server strips exactly one trailing '/' before matching, but the canonical form omits it; every match is still exact-path-or-subtree, never a plain substring.

​
domain
enum<string>

Filter findings by their product finding family (distinct from domain_slug, the producing scanner). Lets a caller split a single purl's findings into matched files (domain=oss) vs manifest declarations (domain=deps) as two separate, independently-pageable queries. Unknown values are ignored (no filter applied), same as an omitted param.

Available options:
oss,
deps,
crypto,
ai,
provenance
​
order
enum<string>
default:updated_desc

Sort order. updated_desc (default) orders by updated_at DESC with id ASC as a unique tiebreaker for stability under offset pagination. path_asc orders by location_path ASC (nulls last) with id ASC as tiebreaker — immutable under triage decisions, so pages stay stable while review decisions are made concurrently. Unknown values fall back to the default.

Available options:
updated_desc,
path_asc
​
limit
integer
default:20

Rows per page, up to 1000 — lets the review workspace fetch the full findings set in a bounded number of requests. Out-of-range values fall back to the default of 20.

Required range: x <= 1000
​
offset
integer
default:0
​
view
enum<string>
default:summary

How much evidence each row carries. summary (the default) omits call_chains, resolved_params and matched_text — no list renderer draws a trace, and a crypto finding's chains dwarf everything else on the row. The truncation counters are retained, so a caller can still tell a trace exists and how big it is. full returns the stored evidence unchanged; prefer GET /v1/findings/{findingId} for the one row actually being inspected. Unknown values fall back to summary.

Available options:
summary,
full
​
evidence_source
enum<string>

Filter crypto findings by where the crypto evidence was observed: direct = a first-party file the scan matched; dependency = inside a dependency's own sources. Applies only to findings whose evidence carries a source key (crypto today); a finding with no such key never matches either value and is dropped from a filtered read the same way a facet-less row is dropped by any other narrowing filter. Unknown values are ignored (no filter applied), same as an omitted param or an unrecognised domain value above.

Available options:
direct,
dependency
​
facet
string[]

Narrow to findings whose derived facet index carries a value, as <path>:<value> (for example crypto.mode:cbc). Repeatable. Values repeated for the SAME path are OR-ed; different paths are AND-ed, which is what a multi-select filter panel means by selecting two modes and one asset type. The path vocabulary reuses the policy field catalog's paths (finding., crypto., oss.match_type, license.*, vulnerability.severity, ai.vendor), so a filter and a policy name the same fact the same way and offer the same values; GET /v1/findings/facets enumerates the paths this organization may use, with counts. Unlike domain and evidence_source, an unrecognised path is rejected with 400 rather than ignored. Those fall back to "no filter", which is safe because a caller that asked for nothing gets everything; silently dropping a facet constraint would instead return MORE findings than were asked for while the client presents them as filtered, which is the direction that misleads.

Response

Paginated list of findings

​
items
object[]
required
​
total
integer
required
​
limit
integer
required
​
offset
integer
required