Detection and incident API
Review detections and manage investigation ownership, state, and timeline.
Investigation write authority does not grant response execution or evidence access. Incident closure preserves outstanding containment and findings.
Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.
List detections
/organizations/{organization_id}/detectionsReturns source, times, severity, rule and feed revisions, evidence availability, and incident references. Standard limit and cursor apply. Unknown filters return 422.
asset_idstringoptionalFilter affected asset.
categorystringoptionalInstalled detection category identifier.
dispositionstringoptionalTriage state.
Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.
Review a detection
/organizations/{organization_id}/detections/{detection_id}Updates the detection disposition while preserving the original observation. Requires If-Match.
dispositionstringrequiredRequested triage state.
reasonstringrequiredAudited justification. Empty values are invalid.
Returns detection review state and new ETag.
Create an incident
/organizations/{organization_id}/incidentsCreates an investigation. It does not contain targets or enable a playbook automatically.
titlestringrequiredIncident title.
severitystringrequiredInitial priority.
owner_idstringrequiredResponsible organization member.
asset_idsstring[]requiredExisting assets visible to the caller; duplicates reject the request.
detection_idsstring[]optionalExisting visible observations to link.
[]visibilitystringoptionalRestricted incidents require explicit membership.
restrictedReturns incident ID, open state, linked observations, and ETag.
List incidents
/organizations/{organization_id}/incidentsReturns visible incident summaries with owner, severity, state, and active response-control count. Standard limit and cursor apply. Unknown filters return 422.
statestringoptionalInvestigation phase.
asset_idstringoptionalFilter affected asset.
Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.
Read an incident
/organizations/{organization_id}/incidents/{incident_id}Returns linked detection, finding, evidence metadata, action IDs, timeline, and residual-control summary. Sensitive artifacts remain separately authorized.
Returns data and request_id.
Update an incident
/organizations/{organization_id}/incidents/{incident_id}Updates incident ownership or investigation state. Requires If-Match; contained requires reviewing incomplete actions. Closing requires a resolution and explicit residual-state acknowledgement.
statestringoptionalRequested investigation phase.
owner_idstringoptionalReplacement responsible member.
resolutionstringoptionalRequired closure explanation.
acknowledge_residual_controlsbooleanoptionalWhether the caller acknowledges residual controls. true records acknowledgement; false leaves it unacknowledged and prevents closure with active controls or unresolved findings.
falseReturns the updated incident and ETag. No isolation release or finding resolution occurs.
Append a timeline note
/organizations/{organization_id}/incidents/{incident_id}/notesAppends an attributable note. Original observations remain immutable.
bodystringrequiredFactual update; distinguish hypotheses and avoid secrets.
occurred_attimestampoptionalOptional event time; omission uses creation time. Creation time is always separately recorded.
Returns note ID, author, event time, and creation time.