Situation configuration management endpoints in the REST API

Use these endpoints to retrieve and update situation configurations in BMC Helix AIOps. Define how situations are correlated, filtered, and prioritized across services. By using these APIs, administrators can programmatically view existing configurations and make changes without requiring manual updates in the UI.

You can perform the following operations related to situation configurations:

Search situation configurations

Retrieves a list of existing situation configurations for the tenant. You can use this endpoint to view configuration details such as correlation settings, topology filters, fingerprint intervals, and policy-based visibility.

POST situations_configurations/search

Search situation configurations endpoint details

Request URL

https://<tenant-base-url>/aiops-config/api/v1.0/situation_configurations/search

Example request URL with optional parameters

POST https://<tenant-base-url>/aiops-config/api/v1.0/situation_configurations/search

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions on obtaining the JWT token, see Access and authentication for the REST API.

Parameters

You can use the following parameters to control the request and response of the API. These parameters are grouped into top-level request body parameters, configuration object parameters, and query parameters.

Top-level request body parameters

Parameter name	Value type	Mandatory	Description	Located in	Example
name	String	No	Unique user-defined name of the situation configuration. Administrators assign this value when creating the configuration. It helps identify the configuration across tenants.	Request body	ml_situation_config
enable	Boolean	No	Determines whether the situation configuration is active. true: The configuration is enabled and applied. false: The configuration is disabled.	Request body	true
description	String	No	Short description of the situation configuration, explaining its purpose or usage.	Request body	ml_situation_config_description
id (search only)	String	No	Unique identifier of the situation configuration. Used to search for or update a specific configuration.	Request body	Need example
createdBy (search only)	String	No	ID of the user who created the situation configuration. It can be used as a filter in search operations.	Request body	Need example
configuration	Object	No	Contains advanced settings that define how situations are detected, merged, and correlated.	Request body	See Configuration object parameters table below.

Configuration object parameters

Name	Value type	Mandatory	Description	Located in	Example
merge_window	String	No	Time window (in minutes) during which related events are merged into a single situation.	Request body	5
correlation_window	String	No	Time window (in minutes) used to correlate related events into a situation.	Request body	10
bgp_event_identifier	String	No	Comma-separated list of identifiers for Border Gateway Protocol (BGP) related events to use in correlation.	Request body	BGP_EVENT,BGP_Test
incident_filter_type	String	No	Specifies whether to include or exclude incidents in situation detection. Supported values: include, exclude.	Request body	include
incident_service_key_list	String	No	Comma-separated list of service keys to filter incidents associated with situations.	Request body	l72W0nXzF6ZFWcjiCK8g_cVZLxOauaUG, l72W0nXzF6ZFWcjiCK8g_cVZLxOauaU1
incident_create_delay_in_minutes	String	No	Delay (in minutes) before creating an incident from a situation.	Request body
situation-severity	String	No	Specifies the default severity level assigned to situations detected by this configuration. priority-from-highest-severity: Indicates how the situation priority is calculated when multiple events share the highest severity. The situation’s priority is set to the highest priority among the events with the highest severity within that situation. highest-severity: The situation’s severity is set to the highest severity of any event within that situation. root-cause-severity: The situation’s severity is set based on the severity of the root cause event. Important: After a situation is formed, any changes to event severity are not automatically reflected in the situation. Situation severity and priority are determined from the highest-severity event only when the situation-severity parameter is set to priority-from-highest-severity value in the situations_configurations/search API, and the Multi-service Situations feature is enabled.	Request body	situation-severity: "priority-from-highest-severity" situation-severity: "root-cause-severity" situation-severity: "highest-severity"
topology_skip_link_kind	String	No	Type of topology links to exclude from correlation.	Request body	NetworkLink
topology_skip_node_kind	String	No	Type of topology nodes to exclude from correlation.	Request body	NetworkRoutingGroup
topology_include_location	Boolean	No	Determines whether location data is considered in situation correlation.	Request body	false
topology_include_location_focus	String	No	Defines the topology focus areas (such as infrastructure, software, or location) to include in correlation.	Request body	infrastructure,software-connected,location:out
topology_exclude_reverse_link_kind	String	No	Specifies the types of reverse link to exclude from topology-based correlation.	Request body	Management
topology_include_reverse_node_kind	String	No	Specifies the types of reverse node types to include in topology-based correlation.	Request body	NetworkInterface
offline_fingerprint_interval	String	No	Time interval (in minutes) used for creating fingerprints when the system is offline.	Request body	60
fingerprint_idle_interval_for_expiry	String	No	Time interval (in seconds) after which idle fingerprints expire.	Request body	14400
show_policy_based_situations	Boolean	Yes	Determines whether policy-based situations are displayed on the Situations page. true: Policy-based situations are shown. false: Policy-based situations are hidden.	Request body	true
show_indirect_impact_services	Boolean	No	Determines whether services that are indirectly impacted by a situation are displayed. true (default): Indirectly impacted services are shown. false: Indirectly impacted services are hidden.	Request body	true
situation_confirmed_time_range_hrs	String	No	Time range (in hours) for confirming situations.	Request body	6
master_situation_supported_kind	String	No	List of CI types supported for creating master situations.	Request body	NetworkInterface,Database,Host

(Optional) Query parameters for pagination and sorting

Parameter	Value type	Mandatory	Description	Located in	Example
limit	Number	No	Maximum number of situation configurations to return in the response.	Query parameter	10
offset	Number	No	Starting position for retrieving records (used for pagination).	Query parameter	5
sortBy	String	No	Field used to sort the results. Supported values: name, createdTime, modifiedTime.	Query parameter	name
order	String	No	Sort order for the results. Supported values: asc, desc.	Query parameter	asc

Request body

{
"requestBody": {
   "required": true,
   "content": {
     "application/json": {
       "schema": {
         "type": "object",
         "properties": {}
       }
     }
   }
}
}

Example request body

POST request with an empty JSON body ({}) when no search filters are applied.

Sample response

{
   "statusMsg": "Situation configuration list retrieved successfully.",
   "totalRecords": 1,
   "situations": [
       {
           "tenantId": "123456789",
           "id": "123xxxxx-4567-8911-a123b-1a23b4c5d6e7",
           "name": "samplename",
           "description": "123456789ababababcdcdadadadadad123412345678",
           "configuration": {
              'merge_window': '30',
     'correlation_window': '30',
     'offline_fingerprint_interval': '1440',
     'show_policy_based_situations': 'true',
     'topology_include_reverse_node_kind': '',
     'fingerprint_idle_interval_for_expiry': '43200',
     "incident_service_key_list": "12345abcVFk8LG7Gz_rI2XA_12345678"
           },
           "enable": true,
           "createdTime": 1740396669407,
           "modifiedTime": 1758168422782,
           "createdBy": "558240917570502"
       }
    ]
}

Unsuccessful responses

Unauthorized (invalid or missing token)

{
"timestamp": "2025-08-18T08:00:36.352+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/aiops-config/api/v1.0/situation_configurations/search"
}

Update a situation configuration

Updates an existing situation configuration for the tenant. You can use this endpoint to modify attributes such as name, description, enablement status, and configuration options like policy-based visibility and incident filtering.

PUTPUT PUT situations_configurations/{situation-config-id}

Update situation configuration endpoint details

Request URL

https://<tenant-base-url>/aiops-config/api/v1.0/situation_configurations/{situation-config-id}

Request Header

Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
"name": "string",
"description": "string",
"enable": "boolean",
"configuration": {
   "show_policy_based_situations": "boolean",
   "incident_filter_type": "string",
   "incident_service_key_list": "string"
}
}

Request body (detailed with example)

{
"name": {
   "type": "string",
   "example": "ml_situation_config"
  },
"description": {
   "type": "string",
   "example": "ml_situation_config_description"
  },
"enable": {
   "type": "boolean",
   "example": true
  },
"configuration": {
   "type": "object",
   "properties": {
     "show_policy_based_situations": {
       "type": "boolean",
       "example": true
      },
     "incident_filter_type": {
       "type": "string",
       "example": "include/exclude"
      },
     "incident_service_key_list": {
       "type": "string",
       "example": "l72W0nXzF6ZFWcjiCK8g_cVZLxOauaUG,l72W0nXzF6ZFWcjiCK8g_cVZLxOauaU1"
      }
    }
  }
}

Example request body

{
"name": "ml_situation_config",
"description": "ml_situation_config_description",
"enable": true,
"configuration": {
   "show_policy_based_situations": true,
   "incident_filter_type": "include",
   "incident_service_key_list": "l72W0nXzF6ZFWcjiCK8g_cVZLxOauaUG,l72W0nXzF6ZFWcjiCK8g_cVZLxOauaU1"
  }
}

Successful response

{
"resourceId": "{situation-config-id}",
"name": "ml_situation_config",
"statusMsg": "Situation configuration updated successfully."
}

Unsuccessful responses

Scenario 1: 401 – Unauthorized (invalid or missing token)

{
"timestamp": "2025-08-18T08:00:36.352+00:00",
"status": 401,
"error": "Unauthorized",
"path": "/aiops-config/api/v1.0/situation_configurations/{situation-config-id}"
}

Scenario 2: 404 – Not found (invalid configuration ID)

Situation configuration with Id {situation-config-id} is not proper.