[8.8][DOCS] Fix create rule open API specification (#157950) (#160547)

docs/api-generated/rules/rule-apis-passthru.asciidoc

@@ -103,7 +103,7 @@ Any modifications made to this file will be overwritten.
   "api_key_created_by_user" : false,
   "enabled" : true,
   "running" : true,
-  "notify_when" : "onActiveAlert",
+  "notify_when" : "notify_when",
   "next_run" : "2022-12-06T00:14:43.818Z",
   "updated_at" : "2022-12-05T23:36:58.284Z",
   "execution_status" : {
@@ -500,7 +500,7 @@ Any modifications made to this file will be overwritten.
     "api_key_created_by_user" : false,
     "enabled" : true,
     "running" : true,
-    "notify_when" : "onActiveAlert",
+    "notify_when" : "notify_when",
     "next_run" : "2022-12-06T00:14:43.818Z",
     "updated_at" : "2022-12-05T23:36:58.284Z",
     "execution_status" : {
@@ -667,7 +667,7 @@ Any modifications made to this file will be overwritten.
     "api_key_created_by_user" : false,
     "enabled" : true,
     "running" : true,
-    "notify_when" : "onActiveAlert",
+    "notify_when" : "notify_when",
     "next_run" : "2022-12-06T00:14:43.818Z",
     "updated_at" : "2022-12-05T23:36:58.284Z",
     "execution_status" : {
@@ -949,7 +949,7 @@ Any modifications made to this file will be overwritten.
   "api_key_created_by_user" : false,
   "enabled" : true,
   "running" : true,
-  "notify_when" : "onActiveAlert",
+  "notify_when" : "notify_when",
   "next_run" : "2022-12-06T00:14:43.818Z",
   "updated_at" : "2022-12-05T23:36:58.284Z",
   "execution_status" : {
@@ -2408,7 +2408,7 @@ Any modifications made to this file will be overwritten.
   "api_key_created_by_user" : false,
   "enabled" : true,
   "running" : true,
-  "notify_when" : "onActiveAlert",
+  "notify_when" : "notify_when",
   "next_run" : "2022-12-06T00:14:43.818Z",
   "updated_at" : "2022-12-05T23:36:58.284Z",
   "execution_status" : {
@@ -2812,7 +2812,7 @@ Any modifications made to this file will be overwritten.
     <div class="field-items">
       <div class="param">notify_when </div><div class="param-desc"><span class="param-type"><a href="#notify_when">notify_when</a></span>  </div>
 <div class="param">summary </div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span> Indicates whether the action is a summary. </div>
-<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. It is specified in seconds, minutes, hours, or days. </div>
+<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values. </div>
     </div>  <!-- field-items -->
   </div>
   <div class="model">
@@ -2868,7 +2868,7 @@ Any modifications made to this file will be overwritten.
 <div class="param">rule_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The ID of the rule type that you want to call when the rule is scheduled to run. For example, <code>.es-query</code>, <code>.index-threshold</code>, <code>logs.alert.document.count</code>, <code>monitoring_alert_cluster_health</code>, <code>siem.thresholdRule</code>, or <code>xpack.ml.anomaly_detection_alert</code>. </div>
 <div class="param">schedule </div><div class="param-desc"><span class="param-type"><a href="#schedule">schedule</a></span>  </div>
 <div class="param">tags (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> The tags for the rule. </div>
-<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. It is specified in seconds, minutes, hours, or days. </div>
+<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values. </div>
     </div>  <!-- field-items -->
   </div>
   <div class="model">
@@ -3130,7 +3130,7 @@ Any modifications made to this file will be overwritten.
   </div>
   <div class="model">
     <h3><a name="notify_when"><code>notify_when</code> - </a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'>Indicates how often alerts generate actions. Valid values include: <code>onActionGroupChange</code>: Actions run when the alert status changes; <code>onActiveAlert</code>: Actions run when the alert becomes active and at each check interval while the rule conditions are met; <code>onThrottleInterval</code>: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met.</div>
+    <div class='model-description'>Indicates how often alerts generate actions. Valid values include: <code>onActionGroupChange</code>: Actions run when the alert status changes; <code>onActiveAlert</code>: Actions run when the alert becomes active and at each check interval while the rule conditions are met; <code>onThrottleInterval</code>: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify <code>notify_when</code> at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.</div>
     <div class="field-items">
           </div>  <!-- field-items -->
   </div>
@@ -3152,7 +3152,7 @@ Any modifications made to this file will be overwritten.
 <div class="param">mute_all </div><div class="param-desc"><span class="param-type"><a href="#boolean">Boolean</a></span>  </div>
 <div class="param">name </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The name of the rule. </div>
 <div class="param">next_run (optional)</div><div class="param-desc"><span class="param-type"><a href="#DateTime">Date</a></span>  format: date-time</div>
-<div class="param">notify_when (optional)</div><div class="param-desc"><span class="param-type"><a href="#notify_when">notify_when</a></span>  </div>
+<div class="param">notify_when (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> Indicates how often alerts generate actions. </div>
 <div class="param">params </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the rule. </div>
 <div class="param">revision (optional)</div><div class="param-desc"><span class="param-type"><a href="#integer">Integer</a></span> The rule revision number. </div>
 <div class="param">rule_type_id </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The identifier for the type of rule. For example, <code>.es-query</code>, <code>.index-threshold</code>, <code>logs.alert.document.count</code>, <code>monitoring_alert_cluster_health</code>, <code>siem.thresholdRule</code>, or <code>xpack.ml.anomaly_detection_alert</code>. </div>
@@ -3160,7 +3160,7 @@ Any modifications made to this file will be overwritten.
 <div class="param">schedule </div><div class="param-desc"><span class="param-type"><a href="#schedule">schedule</a></span>  </div>
 <div class="param">scheduled_task_id (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span>  </div>
 <div class="param">tags </div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> The tags for the rule. </div>
-<div class="param">throttle </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. It is specified in seconds, minutes, hours, or days. </div>
+<div class="param">throttle </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values. </div>
 <div class="param">updated_at </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The date and time that the rule was updated most recently. </div>
 <div class="param">updated_by </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The identifier for the user that updated this rule most recently. </div>
     </div>  <!-- field-items -->
@@ -3212,7 +3212,7 @@ Any modifications made to this file will be overwritten.
 <div class="param">params </div><div class="param-desc"><span class="param-type"><a href="#AnyType">map[String, oas_any_type_not_mapped]</a></span> The parameters for the rule. </div>
 <div class="param">schedule </div><div class="param-desc"><span class="param-type"><a href="#schedule">schedule</a></span>  </div>
 <div class="param">tags (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">array[String]</a></span> The tags for the rule. </div>
-<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. It is specified in seconds, minutes, hours, or days. </div>
+<div class="param">throttle (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if <code>notify_when</code> is set to <code>onThrottleInterval</code>. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values. </div>
     </div>  <!-- field-items -->
   </div>
 </div>

x-pack/plugins/alerting/docs/openapi/bundled.json

@@ -2452,7 +2452,7 @@
     "schemas": {
       "notify_when": {
         "type": "string",
-        "description": "Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met.\n",
+        "description": "Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify `notify_when` at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.\n",
         "enum": [
           "onActionGroupChange",
           "onActiveAlert",
@@ -2462,7 +2462,7 @@
       },
       "throttle": {
         "type": "string",
-        "description": "The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if `notify_when` is set to `onThrottleInterval`. It is specified in seconds, minutes, hours, or days.",
+        "description": "The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if `notify_when` is set to `onThrottleInterval`. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.\n",
         "nullable": true,
         "default": null,
         "example": "10m"
@@ -2807,7 +2807,9 @@
             "example": "2022-12-06T00:14:43.818Z"
           },
           "notify_when": {
-            "$ref": "#/components/schemas/notify_when"
+            "type": "string",
+            "description": "Indicates how often alerts generate actions.",
+            "nullable": true
           },
           "params": {
             "type": "object",
@@ -2901,7 +2903,7 @@
       },
       "update_rule_request": {
         "title": "Update rule request",
-        "description": "The update rule API request body varies depending on the type of rule and actions.",
+        "description": "The update rule API request body varies depending on the type of rule and actions.\n",
         "type": "object",
         "required": [
           "name",
@@ -3139,7 +3141,7 @@
           "created_at": "2022-12-13T22:33:41.163Z",
           "updated_at": "2022-12-13T22:33:41.163Z",
           "api_key_owner": "elastic",
-          "notify_when": "onActionGroupChange",
+          "notify_when": null,
           "muted_alert_ids": [],
           "mute_all": false,
           "scheduled_task_id": "31697a40-7b36-11ed-aa79-f742c05329b2",
@@ -3157,6 +3159,12 @@
                 "level": "info",
                 "message": "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}",
                 "connector_type_id": ".server-log"
+              },
+              "connector_type_id": ".server-log",
+              "frequency": {
+                "throttle": null,
+                "summary": false,
+                "notify_when": "onActionGroupChange"
               }
             }
           ],
@@ -3299,7 +3307,7 @@
         "value": {
           "actions": [
             {
-              "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
+              "id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
               "frequency": {
                 "notify_when": "onActionGroupChange",
                 "summary": false
@@ -3347,6 +3355,7 @@
               "group": "threshold met",
               "id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
               "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
+              "connector_type_id": ".server-log",
               "frequency": {
                 "notify_when": "onActionGroupChange",
                 "summary": false,
@@ -3372,7 +3381,7 @@
           "muted_alert_ids": [],
           "mute_all": false,
           "name": "my rule",
-          "notify_when": "onActionGroupChange",
+          "notify_when": null,
           "params": {
             "aggType": "avg",
             "termSize": 6,
@@ -3448,7 +3457,6 @@
               "created_at": "2022-12-05T23:40:33.132Z",
               "updated_at": "2022-12-05T23:40:33.132Z",
               "api_key_owner": "elastic",
-              "notify_when": "onActionGroupChange",
               "mute_all": false,
               "muted_alert_ids": [],
               "scheduled_task_id": "3583a470-74f6-11ed-9801-35303b735aef",
@@ -3466,6 +3474,11 @@
                     "level": "info",
                     "message": "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}",
                     "connector_type_id": ".server-log"
+                  },
+                  "frequency": {
+                    "summary": false,
+                    "notify_when": "onActionGroupChange",
+                    "throttle": null
                   }
                 }
               ],

x-pack/plugins/alerting/docs/openapi/bundled.yaml

@@ -1550,7 +1550,7 @@ components:
     notify_when:
       type: string
       description: |
-        Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met.
+        Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify `notify_when` at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
       enum:
         - onActionGroupChange
         - onActiveAlert
@@ -1558,7 +1558,8 @@ components:
       example: onActiveAlert
     throttle:
       type: string
-      description: The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if `notify_when` is set to `onThrottleInterval`. It is specified in seconds, minutes, hours, or days.
+      description: |
+        The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if `notify_when` is set to `onThrottleInterval`. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
       nullable: true
       default: null
       example: 10m
@@ -1821,7 +1822,9 @@ components:
           nullable: true
           example: '2022-12-06T00:14:43.818Z'
         notify_when:
-          $ref: '#/components/schemas/notify_when'
+          type: string
+          description: Indicates how often alerts generate actions.
+          nullable: true
         params:
           type: object
           description: The parameters for the rule.
@@ -1889,7 +1892,8 @@ components:
             - 404
     update_rule_request:
       title: Update rule request
-      description: The update rule API request body varies depending on the type of rule and actions.
+      description: |
+        The update rule API request body varies depending on the type of rule and actions.
       type: object
       required:
         - name
@@ -2071,7 +2075,7 @@ components:
         created_at: '2022-12-13T22:33:41.163Z'
         updated_at: '2022-12-13T22:33:41.163Z'
         api_key_owner: elastic
-        notify_when: onActionGroupChange
+        notify_when: null
         muted_alert_ids: []
         mute_all: false
         scheduled_task_id: 31697a40-7b36-11ed-aa79-f742c05329b2
@@ -2092,6 +2096,11 @@ components:
                 - Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}
                 - Timestamp: {{context.date}
               connector_type_id: .server-log
+            connector_type_id: .server-log
+            frequency:
+              throttle: null
+              summary: false
+              notify_when: onActionGroupChange
         last_run:
           alerts_count:
             new: 0
@@ -2211,7 +2220,7 @@ components:
       summary: Create an index threshold rule.
       value:
         actions:
-          - id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
+          - id: 48de3460-f401-11ed-9f8e-399c75a2deeb
             frequency:
               notify_when: onActionGroupChange
               summary: false
@@ -2252,6 +2261,7 @@ components:
           - group: threshold met
             id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
             uuid: 07aef2a0-9eed-4ef9-94ec-39ba58eb609d
+            connector_type_id: .server-log
             frequency:
               notify_when: onActionGroupChange
               summary: false
@@ -2277,7 +2287,7 @@ components:
         muted_alert_ids: []
         mute_all: false
         name: my rule
-        notify_when: onActionGroupChange
+        notify_when: null
         params:
           aggType: avg
           termSize: 6
@@ -2340,7 +2350,6 @@ components:
             created_at: '2022-12-05T23:40:33.132Z'
             updated_at: '2022-12-05T23:40:33.132Z'
             api_key_owner: elastic
-            notify_when: onActionGroupChange
             mute_all: false
             muted_alert_ids: []
             scheduled_task_id: 3583a470-74f6-11ed-9801-35303b735aef
@@ -2361,6 +2370,10 @@ components:
                     - Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}
                     - Timestamp: {{context.date}}
                   connector_type_id: .server-log
+                frequency:
+                  summary: false
+                  notify_when: onActionGroupChange
+                  throttle: null
             last_run:
               alerts_count:
                 new: 0

x-pack/plugins/alerting/docs/openapi/components/examples/create_rule_request.yaml

@@ -1,7 +1,7 @@
 summary: Create an index threshold rule.
 value:
   actions:
-    - id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
+    - id: 48de3460-f401-11ed-9f8e-399c75a2deeb
       frequency:
         notify_when: onActionGroupChange
         summary: false

x-pack/plugins/alerting/docs/openapi/components/examples/create_rule_response.yaml

@@ -4,6 +4,7 @@ value:
     - group: threshold met
       id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
       uuid: 07aef2a0-9eed-4ef9-94ec-39ba58eb609d
+      connector_type_id: .server-log
       frequency:
         notify_when: onActionGroupChange
         summary: false
@@ -24,7 +25,7 @@ value:
   muted_alert_ids: []
   mute_all: false
   name: my rule
-  notify_when: onActionGroupChange
+  notify_when: null
   params:
     aggType: avg
     termSize: 6

x-pack/plugins/alerting/docs/openapi/components/examples/find_rules_response.yaml

@@ -34,7 +34,6 @@ value:
       created_at: '2022-12-05T23:40:33.132Z'
       updated_at: '2022-12-05T23:40:33.132Z'
       api_key_owner: elastic
-      notify_when: onActionGroupChange
       mute_all: false
       muted_alert_ids: []
       scheduled_task_id: 3583a470-74f6-11ed-9801-35303b735aef
@@ -50,6 +49,10 @@ value:
             level: info
             message: "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
             connector_type_id: .server-log
+          frequency:
+            summary: false
+            notify_when: onActionGroupChange
+            throttle: null
       last_run:
         alerts_count:
           new: 0

x-pack/plugins/alerting/docs/openapi/components/examples/get_rule_response.yaml

@@ -30,7 +30,7 @@ value:
   created_at: '2022-12-13T22:33:41.163Z'
   updated_at: '2022-12-13T22:33:41.163Z'
   api_key_owner: elastic
-  notify_when: onActionGroupChange
+  notify_when: null
   muted_alert_ids: []
   mute_all: false
   scheduled_task_id: 31697a40-7b36-11ed-aa79-f742c05329b2
@@ -46,6 +46,11 @@ value:
         level: info
         message: "alert {{alertName}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{params.timeWindowSize}}{{params.timeWindowUnit}}\n- Timestamp: {{context.date}"
         connector_type_id: .server-log
+      connector_type_id: .server-log
+      frequency:
+        throttle: null
+        summary: false
+        notify_when: onActionGroupChange
   last_run:
     alerts_count:
       new: 0

x-pack/plugins/alerting/docs/openapi/components/schemas/create_rule_request.yaml

@@ -41,4 +41,4 @@ properties:
   tags:
     $ref: 'tags.yaml'
   throttle:
-    $ref: 'throttle.yaml'
+    $ref: 'throttle.yaml'

x-pack/plugins/alerting/docs/openapi/components/schemas/notify_when.yaml

@@ -1,6 +1,9 @@
 type: string
 description: >
-  Indicates how often alerts generate actions. Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met.
+  Indicates how often alerts generate actions.
+  Valid values include: `onActionGroupChange`: Actions run when the alert status changes; `onActiveAlert`: Actions run when the alert becomes active and at each check interval while the rule conditions are met; `onThrottleInterval`: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met.
+  NOTE: You cannot specify `notify_when` at both the rule and action level. The recommended method is to set it for each action.
+  If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
 enum:
   - onActionGroupChange
   - onActiveAlert

x-pack/plugins/alerting/docs/openapi/components/schemas/rule_response_properties.yaml

@@ -113,7 +113,9 @@ properties:
     nullable: true
     example: '2022-12-06T00:14:43.818Z'
   notify_when:
-    $ref: 'notify_when.yaml'
+    type: string
+    description: Indicates how often alerts generate actions.
+    nullable: true
   params:
     type: object
     description: The parameters for the rule.

x-pack/plugins/alerting/docs/openapi/components/schemas/throttle.yaml

@@ -1,5 +1,9 @@
 type: string
-description: The throttle interval, which defines how often an alert generates repeated actions. It is applicable only if `notify_when` is set to `onThrottleInterval`. It is specified in seconds, minutes, hours, or days.
+description: >
+  The throttle interval, which defines how often an alert generates repeated actions.
+  It is specified in seconds, minutes, hours, or days and is applicable only if `notify_when` is set to `onThrottleInterval`.
+  NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action.
+  If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.
 nullable: true
 default: null
 example: 10m

x-pack/plugins/alerting/docs/openapi/components/schemas/update_rule_request.yaml

@@ -1,5 +1,5 @@
 title: Update rule request
-description: >-
+description: >
   The update rule API request body varies depending on the type of rule and actions.
 type: object
 required: