Findings API

List, read and triage alerts from a script — the same rules the console follows, including the reason every dismissal needs.

An alert in the console is a finding in the API. Reading needs the VIEWER role and the read scope; changing anything needs ANALYST and write. See API keys and roles.

List findings

curl "https://soc.example.com/api/findings?severity=critical&status=open&include_detail=false" \
  -H "X-API-Key: legit_…"

Parameter	Meaning
`limit`	1–1,000, default 200
`severity`	`info`, `low`, `medium`, `high` or `critical`
`status`	For example `open`, `confirmed`, `escalated`
`q`	Text search
`source_type`	Where the event came from, such as `windows_event` or `ssh_monitor`
`team`	`Identity & Access`, `Endpoint & Malware`, `Network & C2`, `Intrusion Response`, `General SOC`
`assigned_to`	`me`, `unassigned` or a username
`sla_breached`	`true` for alerts past their triage deadline
`include_detail`	`false` leaves out evidence, the AI reasoning trace and the timeline. Lists are about half the size.

The answer is {"items": [...], "total": n}.

What a finding holds

Field	Meaning
`id`, `title`, `summary`	Identity and description
`severity`, `risk_score`, `confidence_score`	Severity, and two scores from 0 to 100
`status`	Where it is in triage
`rule_key`	The rule that raised it, when one did
`asset_hostname`, `affected_assets`	The machine, and every entity involved
`mitre_attack`	ATT&CK technique IDs, such as `T1110.001`
`occurrence_count`, `last_seen_at`	How often the same signal repeated, and when last
`assigned_to`	Who owns it
`evidence`, `timeline`	The events and rule matches behind it, and what happened to it since
`recommended_actions`, `ai_summary`	What to do next, and the analyst’s explanation

Change the status

curl -X PATCH https://soc.example.com/api/findings/<id>/status \
  -H "X-API-Key: legit_…" -H "Content-Type: application/json" \
  -d '{"status": "dismissed", "reason": "Quarterly scan by the IT team", "fp_reason_category": "approved_scan"}'

The same transitions apply as in the console (see Statuses).

Answer	Why
`200`	Changed; the updated finding is returned
`400`	Dismissing without a `reason`
`404`	No such finding in your tenant
`422`	The transition is not allowed (for example, out of `resolved`), or an unknown `status` or `fp_reason_category`

fp_reason_category is one of known_tool, approved_scan, test_activity, wrong_rule_logic, other. Escalating opens an investigation for the finding if none is linked yet.

To assign a finding, post {"action": "assign", "assigned_to": "alice"} to /api/findings/<id>/triage.

Other endpoints

Method and path	Does
`GET /api/findings/{id}`	One finding, in full
`GET /api/findings/{id}/evidence`	Its evidence
`GET /api/findings/{id}/timeline`	What happened to it, in order
`GET /api/findings/{id}/audit`	Every status change: who, from, to, why
`GET`, `POST /api/findings/{id}/notes`	Read notes, or add one: `{"note": "…"}`
`POST /api/findings/{id}/investigate`	Open an investigation from it
`GET /api/findings/stats`	Totals: open, confirmed, dismissed, and by severity
`GET /api/findings/sla-summary`	Deadlines: breached, at risk, on track; mean time to respond
`GET /api/findings/export/csv`, `/export/xlsx`	A spreadsheet of the findings
`GET /api/findings/rule-metrics/{rule_key}`	A rule’s hits, false positives and false-positive rate