Findings API

Findings are the output of a completed investigation — each finding represents a specific observation on a specific endpoint, annotated with a reasoning chain, severity, and confidence score. The Findings API lets you pull the findings feed into your SIEM, ticketing system, or dashboard, and mark findings as dismissed once they have been reviewed.

---

GET /v1/findings

List findings across all investigations for the account. Results are sorted by discovered_at descending (newest first) and are cursor-paginated.

Scope required: findings:read

Common query parameters:

Parameter	Description
severity	low, medium, high, or critical
investigation_id	Scope to a single investigation
dismissed	true or false (default: false)
limit	Page size, 1-1000 (default 100)
cursor	Opaque cursor from a prior response’s next_cursor

curl "https://puck.acme.com/v1/findings?severity=critical&dismissed=false" \
  -H "Authorization: Bearer $PUCK_API_KEY"

const url = new URL("https://puck.acme.com/v1/findings");
url.searchParams.set("severity", "critical");
url.searchParams.set("dismissed", "false");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` },
});
const { findings, next_cursor } = await res.json();

---

POST /v1/findings/{id}/dismiss

Mark a finding as dismissed. Dismissed findings are excluded from the default list view but remain in the audit log and are still retrievable with ?dismissed=true. Dismissal is idempotent.

Scope required: findings:dismiss

Include a reason field: false_positive, accepted_risk, resolved, or duplicate. A free-text notes field is also accepted.

curl -X POST "https://puck.acme.com/v1/findings/fnd_01hx/dismiss" \
  -H "Authorization: Bearer $PUCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "false_positive", "notes": "Known-good tool" }'

const res = await fetch(
  `https://puck.acme.com/v1/findings/${findingId}/dismiss`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PUCK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reason: "false_positive" }),
  }
);
const finding = await res.json();