[DOCS] Add prereqs to mute unmute alert APIs (#141337)

docs/api/alerting.asciidoc

@@ -40,8 +40,8 @@ include::alerting/health.asciidoc[leveloffset=+1]
 include::alerting/get_rules.asciidoc[leveloffset=+1]
 include::alerting/list_rule_types.asciidoc[leveloffset=+1]
 include::alerting/update_rule.asciidoc[leveloffset=+1]
-include::alerting/mute_all_alerts.asciidoc[]
+include::alerting/mute_all_alerts.asciidoc[leveloffset=+1]
-include::alerting/mute_alert.asciidoc[]
+include::alerting/mute_alert.asciidoc[leveloffset=+1]
-include::alerting/unmute_all_alerts.asciidoc[]
+include::alerting/unmute_all_alerts.asciidoc[leveloffset=+1]
-include::alerting/unmute_alert.asciidoc[]
+include::alerting/unmute_alert.asciidoc[leveloffset=+1]
 include::alerting/legacy/index.asciidoc[]

docs/api/alerting/mute_alert.asciidoc

@@ -1,5 +1,5 @@
 [[mute-alert-api]]
-=== Mute alert API
+== Mute alert API
 ++++
 <titleabbrev>Mute alert</titleabbrev>
 ++++
@@ -7,36 +7,44 @@
 Mute an alert.
 
 [[mute-alert-api-request]]
-==== Request
+=== {api-request-title}
 
 `POST <kibana host>:<port>/api/alerting/rule/<rule_id>/alert/<alert_id>/_mute`
 
 `POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<rule_id>/alert/<alert_id>/_mute`
 
-[[mute-alert-api-path-params]]
+=== {api-prereq-title}
-==== Path parameters
 
-`rule_id`::
+You must have `all` privileges for the appropriate {kib} features, depending on
-  (Required, string) The ID of the rule whose alert you want to mute.
+the `consumer` and `rule_type_id` of the rules you're creating. For example, the
+*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
+features, *{observability}*, and *Security* features. If the rule has `actions`,
+you must also have `read` privileges for the *Management* >
+*Actions and Connectors* feature. For more details, refer to
+<<kibana-feature-privileges>>.
+
+[[mute-alert-api-path-params]]
+=== {api-path-parms-title}
 
 `alert_id`::
   (Required, string) The ID of the alert that you want to mute. The `alert_id` is generated by the rule and might be any arbitrary string.
 
+`rule_id`::
+  (Required, string) The ID of the rule whose alert you want to mute.
+
 `space_id`::
   (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
 
 [[mute-alert-api-response-codes]]
-==== Response code
+=== {api-response-codes-title}
 
 `200`::
   Indicates a successful call.
 
-==== Example
+=== {api-examples-title}
-
-Mute alert with ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/alert/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_mute
+POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/alert/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_mute
 --------------------------------------------------
 // KIBANA

docs/api/alerting/mute_all_alerts.asciidoc

@@ -1,5 +1,5 @@
 [[mute-all-alerts-api]]
-=== Mute all alerts API
+== Mute all alerts API
 ++++
 <titleabbrev>Mute all alerts</titleabbrev>
 ++++
@@ -7,14 +7,29 @@
 Mute all alerts.
 
 [[mute-all-alerts-api-request]]
-==== Request
+=== {api-request-title}
 
 `POST <kibana host>:<port>/api/alerting/rule/<id>/_mute_all`
 
 `POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>/_mute_all`
 
+=== {api-prereq-title}
+
+You must have `all` privileges for the appropriate {kib} features, depending on
+the `consumer` and `rule_type_id` of the rules you're creating. For example, the
+*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
+features, *{observability}*, and *Security* features. If the rule has `actions`,
+you must also have `read` privileges for the *Management* >
+*Actions and Connectors* feature. For more details, refer to
+<<kibana-feature-privileges>>.
+
+=== {api-description-title}
+
+This API snoozes the notifications for the rule indefinitely. The rule checks
+continue to occur but alerts will not trigger any actions.
+
 [[mute-all-alerts-api-path-params]]
-==== Path parameters
+=== {api-path-parms-title}
 
 `id`::
   (Required, string) The ID of the rule whose alerts you want to mute.
@@ -23,17 +38,15 @@ Mute all alerts.
   (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
 
 [[mute-all-alerts-api-response-codes]]
-==== Response code
+=== {api-response-codes-title}
 
 `200`::
   Indicates a successful call.
 
-==== Example
+=== {api-examples-title}
-
-Mute all alerts with ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/_mute_all
+POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/_mute_all
 --------------------------------------------------
 // KIBANA

docs/api/alerting/unmute_alert.asciidoc

@@ -1,5 +1,5 @@
 [[unmute-alert-api]]
-=== Unmute alert API
+== Unmute alert API
 ++++
 <titleabbrev>Unmute alert</titleabbrev>
 ++++
@@ -7,36 +7,44 @@
 Unmute an alert.
 
 [[unmute-alert-api-request]]
-==== Request
+=== {api-request-title}
 
 `POST <kibana host>:<port>/api/alerting/rule/<rule_id>/alert/<alert_id>/_unmute`
 
 `POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<rule_id>/alert/<alert_id>/_unmute`
 
-[[unmute-alert-api-path-params]]
+=== {api-prereq-title}
-==== Path parameters
 
-`rule_id`::
+You must have `all` privileges for the appropriate {kib} features, depending on
-  (Required, string) The ID of the rule whose alert you want to mute.
+the `consumer` and `rule_type_id` of the rules you're creating. For example, the
+*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
+features, *{observability}*, and *Security* features. If the rule has `actions`,
+you must also have `read` privileges for the *Management* >
+*Actions and Connectors* feature. For more details, refer to
+<<kibana-feature-privileges>>.
+
+[[unmute-alert-api-path-params]]
+=== {api-path-parms-title}
 
 `alert_id`::
   (Required, string) The ID of the alert that you want to unmute. The `alert_id` is generated by the rule and might be any arbitrary string.
 
+`rule_id`::
+  (Required, string) The ID of the rule whose alert you want to mute.
+
 `space_id`::
   (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
 
 [[unmute-alert-api-response-codes]]
-==== Response code
+=== {api-response-codes-title}
 
 `200`::
   Indicates a successful call.
 
-==== Example
+=== {api-examples-title}
-
-Unmute alert with ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/alert/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_unmute
+POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/alert/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_unmute
 --------------------------------------------------
 // KIBANA

docs/api/alerting/unmute_all_alerts.asciidoc

@@ -1,5 +1,5 @@
 [[unmute-all-alerts-api]]
-=== Unmute all alerts API
+== Unmute all alerts API
 ++++
 <titleabbrev>Unmute all alerts</titleabbrev>
 ++++
@@ -7,14 +7,29 @@
 Unmute all alerts.
 
 [[unmute-all-alerts-api-all-request]]
-==== Request
+=== {api-request-title}
 
 `POST <kibana host>:<port>/api/alerting/rule/<id>/_unmute_all`
 
 `POST <kibana host>:<port>/s/<space_id>/api/alerting/rule/<id>/_unmute_all`
 
+=== {api-prereq-title}
+
+You must have `all` privileges for the appropriate {kib} features, depending on
+the `consumer` and `rule_type_id` of the rules you're creating. For example, the
+*Management* > *Stack Rules* feature, *Analytics* > *Discover* and *{ml-app}*
+features, *{observability}*, and *Security* features. If the rule has `actions`,
+you must also have `read` privileges for the *Management* >
+*Actions and Connectors* feature. For more details, refer to
+<<kibana-feature-privileges>>.
+
+=== {api-description-title}
+
+If the rule has its notifications snoozed indefinitely, this API cancels the
+snooze.
+
 [[unmute-all-alerts-api-path-params]]
-==== Path parameters
+=== {api-path-parms-title}
 
 `id`::
   (Required, string) The ID of the rule whose alerts you want to unmute.
@@ -23,17 +38,15 @@ Unmute all alerts.
   (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
 
 [[unmute-all-alerts-api-response-codes]]
-==== Response code
+=== {api-response-codes-title}
 
 `200`::
   Indicates a successful call.
 
-==== Example
+=== {api-examples-title}
-
-Unmute all alerts with ID:
 
 [source,sh]
 --------------------------------------------------
-$ curl -X POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/_unmute_all
+POST api/alerting/rule/41893910-6bca-11eb-9e0d-85d233e3ee35/_unmute_all
 --------------------------------------------------
 // KIBANA