Incidents¶
Incidents represent correlated security events that require investigation. The UI shows them as work units. The incident engine aggregates related artifacts, nodes, and observations into actionable incidents with severity ratings and status tracking.
Endpoints¶
| Method | Path | Description | Permission |
|---|---|---|---|
| GET | /v1/incidents | List incidents with filters | work_units:read |
| GET | /v1/incidents/:id | Get incident details | work_units:read |
| GET | /v1/incidents/:id/artifacts | Get the incident's artifacts | Read access to the incident |
| GET | /v1/incidents/:id/graph/edges | Get the incident's graph edges | Read access to the incident |
| GET | /v1/incidents/:id/notes | List notes | work_units:read |
| POST | /v1/incidents/:id/notes | Add a note | work_units:write |
| GET | /v1/incidents/:id/audit | Get the audit log | work_units:read |
| PUT | /v1/incidents/:id/status-audit | Update the status and record it in the audit log | work_units:write |
Status Values¶
| ID | Name | Classification |
|---|---|---|
| 1 | New | -- |
| 2 | Investigating | -- |
| 3 | Resolved | True Positive |
| 4 | Closed | False Positive |
| 5 | Disrupted | True Positive |
GET /v1/incidents¶
List incidents for the organization, with optional filtering and pagination.
Query Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
status_id | string | No | One status ID, or a comma-separated list of them (status_id=4,5). The parameter can also be repeated. |
suspicion_level | string | No | low, medium or high, or a comma-separated list of them (suspicion_level=low,high). The parameter can also be repeated. |
severity_level | integer | No | Severity level (1-10) |
min_suspicion | number | No | Minimum suspicion score |
max_suspicion | number | No | Maximum suspicion score |
node_id | string | No | Incidents that include a graph node |
attack_technique_id | string | No | Incidents that include a MITRE ATT&CK technique |
client_ip | string | No | Incidents that include a client IP address |
limit | integer | No | Max results (default 100, max 500) |
offset | integer | No | Pagination offset. limit plus offset may not exceed 10,000. |
- A list of status IDs or suspicion levels returns incidents in any of them.
- An empty entry (
4,,5), a value that is not a positive integer, or a suspicion level other than the three is refused with a 400 that names the parameter. - A list of two or more statuses is read over the newest 10,000 incidents of the organization. When that read comes back full, the response sets
meta.capped: true, a sign that older matches exist. - A
node_id,attack_technique_idorclient_ipfilter reads only that item's newest incidents, up tolimit, andtotalcounts only those. Beside a status, severity or work definition filter,meta.cappedis true when that read comes back full. time_startandtime_endare not filters of this route.
Example Request¶
curl -X GET "https://analytics.example.com/api/v1/incidents?status_id=1,2&suspicion_level=high&limit=10" \
-H "Authorization: Bearer $TOKEN"
GET /v1/incidents/:id¶
Retrieve full details for a single incident.
Path Parameters¶
| Parameter | Type | Description |
|---|---|---|
id | UUID | Incident ID |
Example Request¶
curl -X GET "https://analytics.example.com/api/v1/incidents/d290f1ee-6c54-4b01-90e6-d701748f0851" \
-H "Authorization: Bearer $TOKEN"
GET /v1/incidents/:id/artifacts¶
Return the incident's artifacts, oldest first. The work-unit detail page reads them once for its histogram, table and timeline.
| Parameter | Type | Description |
|---|---|---|
limit | integer | Page size (default 500, max 1,000) |
page | integer | 1-based page number (default 1) |
The incident is read first, so a caller can read only the artifacts of an incident it can already read. An unknown or another organization's ID answers 404.
GET /v1/incidents/:id/graph/edges¶
Return the incident's graph edges with their time fields, ordered by when they started. Work-unit Replay uses this endpoint.
| Parameter | Type | Description |
|---|---|---|
limit | integer | Page size (default 500, max 1,000) |
page | integer | 1-based page number (default 1) |
The response carries meta.truncated when the edge set is incomplete: a very busy node, or an incident of more than 2,000 nodes, made the read stop short. The Replay view shows at most 600 nodes and says so when it leaves some out.
PUT /v1/incidents/:id/status-audit¶
Update the status of an incident and record the change in its audit log. Status transitions drive true positive and false positive classification.
Request Body¶
| Field | Type | Required | Description |
|---|---|---|---|
status_id | integer | Yes | New status ID (1-5) |
Example Request¶
curl -X PUT "https://analytics.example.com/api/v1/incidents/d290f1ee-6c54-4b01-90e6-d701748f0851/status-audit" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"status_id": 3}'
Work Collections¶
POST and PUT on /v1/work-collections change only what the request states.
- Every member (
name,description,criteriaorcriteria_json,enabled,assigned_to,status_id) is optional. - A member the body leaves out, or sets to null, keeps its stored value. A member it states, empty included, replaces it.
- Members the server owns (counts, dates, creator, organization, ID) are ignored.
- A collection created without
enabledis stored disabled. - A request that states nothing, that states both
criteriaandcriteria_json, or whose collection does not validate is a 400.
Reading collections needs collections:read; creating and changing them needs collections:write.
Error Responses¶
| Status | Description |
|---|---|
| 400 | A malformed parameter, ID or JSON body, or a negative limit or offset. The code is invalid_parameter and the response names the parameter. |
| 401 | Missing or invalid token |
| 403 | Insufficient permissions |
| 404 | Incident not found |
| 500 | Internal server error |