Incident Manager API

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.

Deleting PIT

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.

Request without PIT

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.

Multiple Selection

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.

Aggregation Results

Retrieving Aggregation Result and Incidents by Aggregation Result ID

GET _im/aggregations/results?incident_aggregation_result_id={id}

Retrieving All Aggregation Results by Aggregation ID

GET _im/aggregations/results?incident_aggregation_id={id}

Retrieving All Aggregation Results

GET _im/aggregations/results

Updating Aggregation Result

PUT _im/aggregations/results/{incident_aggregation_id}/{incident_aggregation_result_id}?sync={bool}
{

}

warning

Only the changed fields should be included in the request body, for example:

{
  "comment": "test comment",
  "reviewer": "test"
}

Sync

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.

Retrieving MITRE by Incident ID

GET _im/incidents/{incident_id}/mitre

CRUD for Incidents

Retrieving an Incident by ID

GET _im/incidents/{incident_id}

Retrieving All Incidents

GET _im/incidents/

Filters

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}

Updating an Incident

PUT _im/incidents/{incident_id}

warning

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}

Bulk Updating Incidents

POST _im/incidents/bulkUpdate

The format is similar to a standard bulk request to OpenSearch. Example request:

POST _im/incidents/bulkUpdate
{"update":{"_index":".smos_incident-2024.21","_id":"i59eb2be0-1841-11ef-9ffd-ad0f43d0acc5"}}
{"doc":{"reviewer":"test","status":"in_work_incident","_meta":{"id":"i59eb2be0-1841-11ef-9ffd-ad0f43d0acc5"}}}

warning

Only the changed fields and _meta should be included in the request body.