Add explain filtering functionality for ISM docs (#11462) (#11487)

Author: opensearch-trigger-bot[bot]

_im-plugin/ism/api.md

@@ -653,6 +653,192 @@ GET _plugins/_ism/explain/index_1?show_policy=true
 
 The `plugins.index_state_management.policy_id` setting is deprecated starting from ODFE version 1.13.0. We retain this field in the response API for consistency.
 
+## Explain index with filtering
+**Introduced 2.12**
+{: .label .label-purple }
+
+You can use the `POST` method with the Explain API to filter the results based on specific criteria. This allows you to query indexes based on their policy ID, current state, or action type.
+
+#### Endpoints
+
+```
+POST _plugins/_ism/explain/<index>
+```
+
+#### Request body
+
+The request body supports the following optional filters.
+
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `policy_id` | String | Filter results to show only indexes managed by the specified policy ID. |
+| `state` | String | Filter results to show only indexes currently in the specified state. |
+| `action_type` | String | Filter results to show only indexes currently executing the specified action type. |
+| `failed` | Boolean | Filter results to show only failed managed indexes. |
+All filters are optional. If a filter is not specified, indexes with any value for that parameter will be included in the results. The API returns only indexes that match all specified filters.
+
+#### Example request: Filter by policy ID
+
+```json
+POST _plugins/_ism/explain/log-*
+{
+  "filter": {
+    "policy_id": "hot-warm-delete-policy"
+  }
+}
+```
+{% include copy-curl.html %}
+
+#### Example request: Filter by state and action type
+
+```json
+POST _plugins/_ism/explain/app-*
+{
+  "filter": {
+    "state": "warm",
+    "action_type": "allocation"
+  }
+}
+```
+{% include copy-curl.html %}
+
+#### Example request: Filter by all criteria
+
+```json
+POST _plugins/_ism/explain/data-*
+{
+  "filter": {
+    "policy_id": "data-lifecycle-policy",
+    "state": "hot",
+    "action_type": "rollover"
+  }
+}
+```
+{% include copy-curl.html %}
+
+#### Example response
+
+<details markdown="block">
+  <summary>
+    Response
+  </summary>
+  {: .text-delta}
+
+```json
+{
+  "test-logs-001": {
+    "index.plugins.index_state_management.policy_id": "test-lifecycle-policy",
+    "index": "test-logs-001",
+    "index_uuid": "LmJgKNatQZWHQu-qIHlcJw",
+    "policy_id": "test-lifecycle-policy",
+    "enabled": true,
+    "policy": {
+      "policy_id": "test-lifecycle-policy",
+      "description": "Lifecycle policy for log data: hot -> warm -> cold -> delete",
+      "last_updated_time": 1730308440926,
+      "schema_version": 18,
+      "error_notification": null,
+      "default_state": "hot",
+      "states": [
+        {
+          "name": "hot",
+          "actions": [
+            {
+              "rollover": {
+                "min_doc_count": 10000,
+                "min_size": "1gb",
+                "min_index_age": "1d"
+              }
+            }
+          ],
+          "transitions": [
+            {
+              "state_name": "warm",
+              "conditions": {
+                "min_index_age": "7d"
+              }
+            }
+          ]
+        },
+        {
+          "name": "warm",
+          "actions": [
+            {
+              "replica_count": {
+                "number_of_replicas": 0
+              }
+            }
+          ],
+          "transitions": [
+            {
+              "state_name": "cold",
+              "conditions": {
+                "min_index_age": "30d"
+              }
+            }
+          ]
+        },
+        {
+          "name": "cold",
+          "actions": [],
+          "transitions": [
+            {
+              "state_name": "delete",
+              "conditions": {
+                "min_index_age": "90d"
+              }
+            }
+          ]
+        },
+        {
+          "name": "delete",
+          "actions": [
+            {
+              "delete": {}
+            }
+          ],
+          "transitions": []
+        }
+      ],
+      "ism_template": null
+    },
+    "policy_seq_no": 0,
+    "policy_primary_term": 1,
+    "rolled_over": false,
+    "index_creation_date": 1730308447399,
+    "state": {
+      "name": "hot",
+      "start_time": 1730308447644
+    },
+    "action": {
+      "name": "rollover",
+      "start_time": 1730308447644,
+      "index": 0,
+      "failed": false,
+      "consumed_retries": 0,
+      "last_retry_time": 0
+    },
+    "step": {
+      "name": "attempt_rollover",
+      "start_time": 1730308447644,
+      "step_status": "starting"
+    },
+    "retry_info": {
+      "failed": false,
+      "consumed_retries": 0
+    },
+    "info": {
+      "message": "Currently checking rollover conditions"
+    },
+    "enabled": true,
+    "enabled_time": 1730308447644
+  },
+  "total_managed_indices": 1
+}
+```
+
+</details>
+
 ---
 
 ## Delete policy