Skip to main content

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
}
NameSyntaxDescription
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.

NameSyntaxDescription
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.