Incident Manager API
Response examples are shortened: repeated objects and fields that do not affect understanding of the structure are omitted. Personal data and infrastructure details are anonymized.
Point In Time
To ensure proper pagination before requesting incidents and aggregation results, you need to request a Point In Time (PIT). When switching pages in the Incident Manager, the PIT should remain the same; otherwise, you need to request a new PIT and delete the old one using an API request.
The number of active PITs in the system is limited, so if a PIT is no longer relevant, you must make a request to delete it.
Requesting PIT
To obtain a PIT for requesting incidents and aggregation results, execute the following request:
GET _im/incidents/pit
To obtain a PIT for requesting only incidents, add the is_show_aggs=false flag to the request:
GET _im/incidents/pit?is_show_aggs=false
Deleting PIT
When the PIT becomes irrelevant (e.g., the user closes the Incident Manager, updates filters, etc.), it must be deleted.
DELETE _im/incidents/pit
{
"id": "{pit_id}"
}
Retrieving Incidents and Aggregation Results
The general format for requesting incidents and aggregation results:
GET _im/incidents_full_types
{
"pit": "pit_id",
"from": 0,
"size": 25,
"search_query": "{\"match_all\":{}}",
"additional_fields": [],
"end_time": "now",
"start_time": "now-1d",
"with_total_docs": true,
"is_show_aggs": true
}
| Name | Syntax | Description |
|---|---|---|
| pit | <string> | Point In Time obtained from the Request PIT section. |
| from | <int> | Starting index for the search. |
| size | <int> | Number of results in the response. |
| search_query | <string> | DSL query formed based on the search string. |
| additional_fields | <array> | See Additional Fields. |
| start_time | <string> | Start timestamp for the search. |
| end_time | <string> | End timestamp for the search. |
| with_total_docs | <bool> | If true, additionally returns the total_docs field containing the total number of documents. |
| is_show_aggs | <bool> | If true, returns incidents and aggregation results; if false, returns only incidents. |
If PIT is not specified in the request, the response will always return documents from the current version of the index.
Additional Fields
The additional_fields parameter is used to pass custom filters. It is an array of objects containing the fields name, type, and value.
| Name | Syntax | Description |
|---|---|---|
name | <string> | The name of the field to filter. |
type | <string> | The type of the field. Acceptable values are number, text, select, multiselect. |
value | <string> | The filter value. |
For type=multiselect, the value field should be an array of strings, not a single string.
Example of filling additional_fields:
[
{
"name": "select_field",
"type": "select",
"value": "test"
},
{
"name": "text_field",
"type": "text",
"value": "test*"
},
{
"name": "multiselect_field",
"type": "multiselect",
"value": ["t1", "t2"]
}
]
Retrieving Statistics for Incidents and Aggregation Results
The general format for requesting statistics for incidents and aggregation results:
POST _im/incidents_full_types/stats/severity
{
"search_query": "{\"match_all\":{}}",
"additional_fields": [],
"end_time": "now",
"start_time": "now-1d",
"is_show_aggs": true
}
The parameters are similar to the incidents and aggregation results request.
Response Example
[
{
"severity": "2",
"result_count": 350
},
{
"severity": "3",
"result_count": 92
},
{
"severity": "4",
"result_count": 6
},
{
"severity": "1",
"result_count": 4
}
]
Aggregation Results
Retrieving Aggregation Result and Incidents by Aggregation Result ID
GET _im/aggregations/results?incident_aggregation_result_id={id}
Request and Response Example
GET _im/aggregations/results?incident_aggregation_result_id=AGG-260914-222
{
"incident_agg_result": {
"_meta": {
"from_system": false,
"id": "AGG-260914-222"
},
"aggregation_info": {
"severity": "2",
"workflow_id": "initial-workflow",
"id": "MA:_Podozritelnoe_povedenie_polzovatelya",
"status": "init"
},
"mitre_fields": [
{
"severity": "high",
"job_id": "RULE_-_MA_-_Sysmon_-_OS_Credential_Dumping",
"layers": ["<layer_id>"],
"technique_id": ["T1003"]
}
],
"incident_identifiers": [
"INC-260914-499249",
"INC-260914-499248"
],
"incidents_count": 9,
"status": "init"
},
"incidents": {
"INC-260914-499249": {
"_meta": {
"id": "INC-260914-499249"
},
"incident_title": "Suspicious activity on workstation-01",
"severity": "2",
"aggregation_id": "MA:_Podozritelnoe_povedenie_polzovatelya",
"status": "init"
}
}
}
Retrieving All Aggregation Results by Aggregation ID
GET _im/aggregations/results?incident_aggregation_id={id}
Request and Response Example
GET _im/aggregations/results?incident_aggregation_id=MA:_Podozritelnoe_povedenie_polzovatelya
[
{
"incident_agg_result": {
"_index": ".sm_incident_aggregation_results-2026.38",
"_meta": {
"id": "AGG-260916-226"
},
"aggregation_info": {
"id": "MA:_Podozritelnoe_povedenie_polzovatelya",
"severity": "2",
"status": "init"
},
"incident_identifiers": [
"INC-260916-500281",
"INC-260916-500280"
],
"incidents_count": 5
},
"incidents": {
"INC-260916-500281": {
"_meta": {
"id": "INC-260916-500281"
},
"severity": "2",
"status": "init"
}
}
}
]
Retrieving All Aggregation Results
GET _im/aggregations/results
Response Example
[
{
"_index": ".sm_incident_aggregation_results-2026.38",
"_meta": {
"id": "AGG-260916-226"
},
"aggregation_info": {
"id": "MA:_Podozritelnoe_povedenie_polzovatelya",
"severity": "2",
"status": "init"
},
"incident_identifiers": [
"INC-260916-500281",
"INC-260916-500280"
],
"incidents_count": 5,
"closed": false
}
]
Updating Aggregation Result
PUT _im/aggregations/result/{incident_aggregation_id}/{incident_aggregation_result_id}?sync={bool}
{
"<field_name>": "<new_value>"
}
Only the changed fields should be included in the request body, for example:
{
"comment": "test comment",
"reviewer": "test"
}
If the sync=true parameter is set, changes to the status, workflow_id, severity, comment, and reviewer fields in the aggregation result will also be applied to the incidents contained in the aggregation.
Request and Response Example
PUT _im/aggregations/result/MA:_Podozritelnoe_povedenie_polzovatelya/AGG-260914-222?sync=false
{
"comment": "API update test"
}
Updated aggregation result with id: AGG-260914-222
Retrieving MITRE by Incident ID
The request returns information about MITRE ATT&CK® techniques associated with the incident. This data is not generated from incident card fields. It comes from documents in the .smos_mitre-* index created by the active Record MITRE ATT&CK® Techniques action.
To link a MITRE ATT&CK® record to an incident, the Record MITRE ATT&CK® Techniques action must run after the Create Incident action in one job execution. In this case, Search Anywhere Framework automatically adds the incident_id field to the record.
| Field | Description |
|---|---|
incident_id | Identifier of the linked incident. |
@timestamp | Time when the technique trigger record was created. |
custom_fields | Result fields passed by the active action. The contents depend on the job settings. |
layers | Identifiers of the MITRE ATT&CK® layers selected in the active action. |
rule | Name of the correlation rule. |
technique_id | Identifiers of the MITRE ATT&CK® techniques selected in the active action. |
GET _im/incidents/{incident_id}/mitre
Request and Response Example
GET _im/incidents/INC-260915-499823/mitre
[
{
"incident_id": "INC-260915-499823",
"@timestamp": "2026-09-15T10:07:19.500+0300",
"custom_fields": {
"host.ip": "192.0.2.10",
"image": "C:\\Windows\\System32\\example.exe",
"process_id": "595533",
"user.name": "user01",
"host.name": "workstation-01"
},
"layers": ["<layer_id>"],
"rule": "RULE - MA - Sysmon - System Time Discovery",
"technique_id": ["T1124"]
}
]
CRUD for Incidents
Retrieving an Incident by ID
GET _im/incidents/{incident_id}
Request and Response Example
GET _im/incidents/INC-260915-499823
{
"incident_type": "default",
"workflow_id": "initial-workflow",
"_index": ".smos_incident-smart_sec-2026.38",
"_meta": {
"id": "INC-260915-499823"
},
"incident_title": "System time discovery on workstation-01",
"severity": "2",
"is_aggregated": false,
"reviewer": "empty",
"tags": [
{
"type": "mitre",
"value": "T1124"
}
],
"incident_category_id": "smart_sec",
"_id": "INC-260915-499823",
"status": "init"
}
Retrieving All Incidents
GET _im/incidents/
Response Example
[
{
"incident_type": "default",
"workflow_id": "initial-workflow",
"_index": ".smos_incident-smart_sec-2026.38",
"_meta": {
"id": "INC-260916-500293"
},
"incident_title": "System time discovery on workstation-01",
"severity": "2",
"incident_category_id": "smart_sec",
"_id": "INC-260916-500293",
"status": "init"
}
]
When requesting all incidents, you can specify incident filters using GET request parameters.
For example, to request incidents from the last hour where the test_field is equal to 5, use the following request:
GET _im/incidents?start_time=now-1h&end_time=now&test_field=5
Creating an Incident
POST _im/incidents/{incident_id}
The request body must contain the data for the new incident. The _meta.id value must match the incident_id in the request path.
Request and Response Example
POST _im/incidents/INC-260915-900001
{
"_meta": {
"id": "INC-260915-900001"
},
"incident_type": "default",
"incident_category_id": "smart_sec",
"incident_title": "API test incident",
"incident_description": "Incident created to test the Incident Manager API",
"severity": "2",
"status": "init",
"workflow_id": "initial-workflow",
"reviewer": "empty",
"damage": "0",
"source_events": "no",
"is_aggregated": false,
"aggregation_id": "",
"incident_index_suffix": "",
"drilldown_type": "",
"drilldown_context": "",
"comment": "",
"info": "",
"line": "",
"log": "",
"division": ["IT"],
"user_sm": ["all"],
"fields": {},
"order_fields": [],
"inventory": [],
"tags": []
}
{
"message": "created"
}
Updating an Incident
PUT _im/incidents/{incident_id}
Only the changed fields and _meta should be included in the request body, for example:
{
"_meta": {
"id": "i59eb2be0-1841-11ef-9ffd-ad0f43d0acc5"
},
"comment": "test comment",
"reviewer": "test"
}
Deleting an Incident
DELETE _im/incidents/{incident_id}
Request and Response Example
DELETE _im/incidents/INC-260915-900001
deleted
Bulk Updating Incidents
POST _im/incidents/bulkUpdate
The request body is in NDJSON format: the update operation and the doc object are placed on separate lines. The last line must be followed by a line break.
Request and Response Example
POST _im/incidents/bulkUpdate
{"update":{"_index":".smos_incident-smart_sec-2026.38","_id":"INC-260914-499249"}}
{"doc":{"comment":"API bulk update test","_meta":{"id":"INC-260914-499249"}}}
OK
Only the changed fields and _meta should be included in the request body.