[DOCS] Reformats Watcher APIs using template (#46152)

x-pack/docs/en/rest-api/watcher/ack-watch.asciidoc

@@ -6,40 +6,55 @@
 ++++
 
 {stack-ov}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you
-to manually throttle execution of the watch's actions. An action's
+to manually throttle execution of the watch's actions.
-_acknowledgement state_ is stored in the `status.actions.<id>.ack.state`
-structure.
 
-IMPORTANT: If the specified watch is currently being executed, this API will return
+[[watcher-api-ack-watch-request]]
-an error. The reason for this is to prevent overwriting of the watch status from a watch
+==== {api-request-title}
-execution.
-
-[float]
-==== Request
 
 `PUT _watcher/watch/<watch_id>/_ack` +
 
 `PUT _watcher/watch/<watch_id>/_ack/<action_id>`
 
-[float]
+[[watcher-api-ack-watch-prereqs]]
-==== Path Parameters
+==== {api-prereq-title}
 
-`action_id`::
+* You must have `manage_watcher` cluster privileges to use this API. For more
-  (list) A comma-separated list of the action IDs to acknowledge. If you omit
+information, see {stack-ov}/security-privileges.html[Security privileges].
+
+[[watcher-api-ack-watch-desc]]
+==== {api-description-title}
+
+An action's _acknowledgement state_ is stored in the
+`status.actions.<id>.ack.state` structure.
+
+IMPORTANT: If the specified watch is currently being executed, this API will
+return an error. The reason for this is to prevent overwriting of the watch
+status from a watch execution.
+
+[[watcher-api-ack-watch-path-params]]
+==== {api-path-parms-title}
+
+`<action_id>`::
+  (Optional, list) A comma-separated list of the action IDs to acknowledge. If you omit
   this parameter, all of the actions of the watch are acknowledged.
 
-`watch_id` (required)::
+`<watch_id>`::
-  (string) Identifier for the watch.
+  (Required, string) Identifier for the watch.
 
-[float]
+//[[watcher-api-ack-watch-query-params]]
-==== Authorization
+//==== {api-query-parms-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+//[[watcher-api-ack-watch-request-body]]
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
+//==== {api-request-body-title}
 
+//[[watcher-api-ack-watch-response-body]]
+//==== {api-response-body-title}
 
-[float]
+//[[watcher-api-ack-watch-response-codes]]
-==== Examples
+//==== {api-response-codes-title}
+
+[[watcher-api-ack-watch-example]]
+==== {api-examples-title}
 
 To demonstrate let's create a new watch:
 

x-pack/docs/en/rest-api/watcher/activate-watch.asciidoc

@@ -9,28 +9,43 @@ A watch can be either
 {stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This
 API enables you to activate a currently inactive watch.
 
-[float]
+[[watcher-api-activate-watch-request]]
-==== Request
+==== {api-request-title}
 
 `PUT _watcher/watch/<watch_id>/_activate`
 
-[float]
+[[watcher-api-activate-watch-prereqs]]
-==== Path Parameters
+==== {api-prereq-title}
 
-`watch_id` (required)::
+* You must have `manage_watcher` cluster privileges to use this API. For more
-  (string) Identifier for the watch.
+information, see {stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-activate-watch-desc]]
-==== Authorization
+//==== {api-description-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+[[watcher-api-activate-watch-path-params]]
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
+==== {api-path-parms-title}
 
-[float]
+`<watch_id>`::
-==== Examples
+  (Required, string) Identifier for the watch.
+
+//[[watcher-api-activate-watch-query-params]]
+//==== {api-query-parms-title}
+
+//[[watcher-api-activate-watch-request-body]]
+//==== {api-request-body-title}
+
+//[[watcher-api-activate-watch-response-body]]
+//==== {api-response-body-title}
+
+//[[watcher-api-activate-watch-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-activate-watch-example]]
+==== {api-examples-title}
 
 The status of an inactive watch is returned with the watch definition when you
-call the <<watcher-api-get-watch, Get Watch API>>:
+call the <<watcher-api-get-watch,get watch API>>:
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/watcher/deactivate-watch.asciidoc

@@ -9,27 +9,43 @@ A watch can be either
 {stack-ov}/how-watcher-works.html#watch-active-state[active or inactive]. This
 API enables you to deactivate a currently active watch.
 
-[float]
+[[watcher-api-deactivate-watch-request]]
-==== Request
+==== {api-request-title}
 
 `PUT _watcher/watch/<watch_id>/_deactivate`
 
-[float]
+[[watcher-api-deactivate-watch-prereqs]]
-==== Path Parameters
+==== {api-prereq-title}
 
-`watch_id` (required)::
+* You must have `manage_watcher` cluster privileges to use this API. For more
-  (string) Identifier for the watch.
+information, see {stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-deactivate-watch-desc]]
-==== Authorization
+//==== {api-description-title}
-You must have `manage_watcher` cluster privileges to use this API. For more
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
 
-[float]
+[[watcher-api-deactivate-watch-path-params]]
-==== Examples
+==== {api-path-parms-title}
+
+`<watch_id>`::
+  (Required, string) Identifier for the watch.
+
+//[[watcher-api-deactivate-watch-query-params]]
+//==== {api-query-parms-title}
+
+//[[watcher-api-deactivate-watch-request-body]]
+//==== {api-request-body-title}
+
+//[[watcher-api-deactivate-watch-response-body]]
+//==== {api-response-body-title}
+
+//[[watcher-api-deactivate-watch-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-deactivate-watch-example]]
+==== {api-examples-title}
 
 The status of an active watch is returned with the watch definition when you
-call the <<watcher-api-get-watch, Get Watch API>>:
+call the <<watcher-api-get-watch,get watch API>>:
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/watcher/delete-watch.asciidoc

@@ -5,15 +5,21 @@
 <titleabbrev>Delete watch</titleabbrev>
 ++++
 
-The delete watch API removes a watch from {watcher}.
+Removes a watch from {watcher}.
 
-[float]
+[[watcher-api-delete-watch-request]]
-==== Request
+==== {api-request-title}
 
 `DELETE _watcher/watch/<watch_id>`
 
-[float]
+[[watcher-api-delete-watch-prereqs]]
-==== Description
+==== {api-prereq-title}
+
+* You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {stack-ov}/security-privileges.html[Security privileges].
+
+[[watcher-api-delete-watch-desc]]
+==== {api-description-title}
 
 When the watch is removed, the document representing the watch in the `.watches`
 index is gone and it will never be run again.
@@ -27,20 +33,26 @@ IMPORTANT:  Deleting a watch must be done via this API only. Do not delete the
             sure no `write` privileges are granted to anyone over the `.watches`
             index.
 
-[float]
+[[watcher-api-delete-watch-path-params]]
-==== Path Parameters
+==== {api-path-parms-title}
 
-`watch_id` (required)::
+`<watch_id>`::
-  (string) Identifier for the watch.
+  (Required, string) Identifier for the watch.
 
-[float]
+//[[watcher-api-delete-watch-query-params]]
-==== Authorization
+//==== {api-query-parms-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+//[[watcher-api-delete-watch-request-body]]
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
+//==== {api-request-body-title}
 
-[float]
+//[[watcher-api-delete-watch-response-body]]
-==== Examples
+//==== {api-response-body-title}
+
+//[[watcher-api-delete-watch-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-delete-watch-example]]
+==== {api-examples-title}
 
 The following example deletes a watch with the `my-watch` id:
 

x-pack/docs/en/rest-api/watcher/execute-watch.asciidoc

@@ -5,19 +5,26 @@
 <titleabbrev>Execute watch</titleabbrev>
 ++++
 
-The execute watch API forces the execution of a stored watch. It can be used to
+Forces the execution of a stored watch. 
-force execution of the watch outside of its triggering logic, or to simulate the
-watch execution for debugging purposes.
 
-[float]
+[[watcher-api-execute-watch-request]]
-==== Request
+==== {api-request-title}
 
 `POST _watcher/watch/<watch_id>/_execute` +
 
 `POST _watcher/watch/_execute`
 
-[float]
+[[watcher-api-execute-watch-prereqs]]
-==== Description
+==== {api-prereq-title}
+
+* You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {stack-ov}/security-privileges.html[Security privileges].
+
+[[watcher-api-execute-watch-desc]]
+==== {api-description-title}
+
+This API can be used to force execution of the watch outside of its triggering
+logic or to simulate the watch execution for debugging purposes.
 
 For testing and debugging purposes, you also have fine-grained control on how
 the watch runs. You can execute the watch without executing all of its actions
@@ -25,29 +32,28 @@ or alternatively by simulating them. You can also force execution by ignoring
 the watch condition and control whether a watch record would be written to the
 watch history after execution.
 
-[float]
 [[watcher-api-execute-inline-watch]]
-===== Inline Watch Execution
+===== Inline watch execution
 
 You can use the Execute API to execute watches that are not yet registered by
 specifying the watch definition inline. This serves as great tool for testing
 and debugging your watches prior to adding them to {watcher}.
 
-[float]
+[[watcher-api-execute-watch-path-params]]
-==== Path Parameters
+==== {api-path-parms-title}
 
-`watch_id`::
+`<watch_id>`::
-  (string) Identifier for the watch.
+  (Optional, string) Identifier for the watch.
 
-[float]
+[[watcher-api-execute-watch-query-params]]
-==== Query Parameters
+==== {api-query-parms-title}
 
 `debug`::
-  (boolean) Defines whether the watch runs in debug mode. The default value is
+  (Optional, boolean) Defines whether the watch runs in debug mode. The default
-  `false`.
+  value is `false`.
 
-[float]
+[[watcher-api-execute-watch-request-body]]
-==== Request Body
+==== {api-request-body-title}
 
 This API supports the following fields:
 
@@ -59,7 +65,7 @@ This API supports the following fields:
                                               that will be used during the watch execution
 
 | `ignore_condition`  | no       | false    | When set to `true`, the watch execution uses the
-                                              {stack-ov}/condition-always.html[Always Condition].
+                                              {stack-ov}/condition-always.html[Always condition].
                                               This can also be specified as an HTTP parameter.
 
 | `alternative_input` | no       | null     | When present, the watch uses this object as a payload
@@ -81,9 +87,8 @@ This API supports the following fields:
                                               not persisted to the index and record_execution cannot be set.
 |======
 
-[float]
 [[watcher-api-execute-watch-action-mode]]
-===== Action Execution Modes
+===== Action execution modes
 
 Action modes define how actions are handled during the watch execution. There
 are five possible modes an action can be associated with:
@@ -116,13 +121,8 @@ are five possible modes an action can be associated with:
                       Effectively forces the action to be throttled.
 |======
 
-[float]
+[[watcher-api-execute-watch-security]]
-==== Authorization
+===== Security integration
-You must have `manage_watcher` cluster privileges to use this API. For more
-information, see {stack-ov}/security-privileges.html[Security Privileges].
-
-[float]
-==== Security Integration
 
 When {es} {security-features} are enabled on your cluster, watches
 are executed with the privileges of the user that stored the watches. If your
@@ -133,8 +133,14 @@ When using the execute watch API, the authorization data of the user that
 called the API will be used as a base, instead of of the information who stored
 the watch.
 
-[float]
+//[[watcher-api-execute-watch-response-body]]
-==== Examples
+//==== {api-response-body-title}
+
+//[[watcher-api-execute-watch-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-execute-watch-example]]
+==== {api-examples-title}
 
 The following example executes the `my_watch` watch:
 

x-pack/docs/en/rest-api/watcher/get-watch.asciidoc

@@ -5,28 +5,43 @@
 <titleabbrev>Get watch</titleabbrev>
 ++++
 
-This API retrieves a watch by its ID.
+Retrieves a watch by its ID.
 
-[float]
+[[watcher-api-get-watch-request]]
-==== Request
+==== {api-request-title}
 
 `GET _watcher/watch/<watch_id>`
 
-[float]
+[[watcher-api-get-watch-prereqs]]
-==== Path Parameters
+==== {api-prereq-title}
 
-`watch_id` (required)::
+* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
-  (string) Identifier for the watch.
-
-[float]
-==== Authorization
-
-You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
 this API. For more information, see
-{xpack-ref}/security-privileges.html[Security Privileges].
+{stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-get-watch-desc]]
-==== Examples
+//==== {api-description-title}
+
+[[watcher-api-get-watch-path-params]]
+==== {api-path-parms-title}
+
+`<watch_id>`::
+  (Required, string) Identifier for the watch.
+
+//[[watcher-api-get-watch-query-params]]
+//==== {api-query-parms-title}
+
+//[[watcher-api-get-watch-request-body]]
+//==== {api-request-body-title}
+
+//[[watcher-api-get-watch-response-body]]
+//==== {api-response-body-title}
+
+//[[watcher-api-get-watch-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-get-watch-example]]
+==== {api-examples-title}
 
 The following example gets a watch with `my-watch` id:
 

x-pack/docs/en/rest-api/watcher/put-watch.asciidoc

@@ -5,16 +5,21 @@
 <titleabbrev>Put watch</titleabbrev>
 ++++
 
-The PUT watch API either registers a new watch in {watcher} or updates an
+Either registers a new watch in {watcher} or updates an existing one.
-existing one.
 
-[float]
+[[watcher-api-put-watch-request]]
-==== Request
+==== {api-request-title}
 
 `PUT _watcher/watch/<watch_id>`
 
-[float]
+[[watcher-api-put-watch-prereqs]]
-==== Description
+==== {api-prereq-title}
+
+* You must have `manage_watcher` cluster privileges to use this API. For more
+information, see {stack-ov}/security-privileges.html[Security privileges].
+
+[[watcher-api-put-watch-desc]]
+==== {api-description-title}
 
 When a watch is registered, a new document that represents the watch is added to
 the `.watches` index and its trigger is immediately registered with the relevant
@@ -30,21 +35,29 @@ When adding a watch you can also define its initial
 {stack-ov}/how-watcher-works.html#watch-active-state[active state]. You do that
 by setting the `active` parameter.
 
-[float]
+[[watcher-api-put-watch-security]]
-==== Path Parameters
+===== Security integration
 
-`watch_id` (required)::
+When {es} {security-features} are enabled, your watch can index or search only
-  (string) Identifier for the watch.
+on indices for which the user that stored the watch has privileges. If the user
+is able to read index `a`, but not index `b`, the same will apply, when the watch
+is executed.
 
-[float]
+[[watcher-api-put-watch-path-params]]
-==== Query Parameters
+==== {api-path-parms-title}
+
+`<watch_id>`::
+  (Required, string) Identifier for the watch.
+
+[[watcher-api-put-watch-query-params]]
+==== {api-query-parms-title}
 
 `active`::
-  (boolean) Defines whether the watch is active or inactive by default. The
+  (Optional, boolean) Defines whether the watch is active or inactive by default.
-  default value is `true`, which means the watch is active by default.
+  The default value is `true`, which means the watch is active by default.
 
-[float]
+[[watcher-api-put-watch-request-body]]
-==== Request Body
+==== {api-request-body-title}
 
 A watch has the following fields:
 
@@ -82,22 +95,14 @@ A watch has the following fields:
 
 |======
 
-[float]
+//[[watcher-api-put-watch-response-body]]
-==== Authorization
+//==== {api-response-body-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+//[[watcher-api-put-watch-response-codes]]
-information, see {stack-ov}/security-privileges.html[Security Privileges].
+//==== {api-response-codes-title}
 
-[float]
+[[watcher-api-put-watch-example]]
-==== Security Integration
+==== {api-examples-title}
-
-When {es} {security-features} are enabled, your watch can index or search only
-on indices for which the user that stored the watch has privileges. If the user
-is able to read index `a`, but not index `b`, the same will apply, when the watch
-is executed.
-
-[float]
-==== Examples
 
 The following example adds a watch with the `my-watch` id that has the following
 characteristics:

x-pack/docs/en/rest-api/watcher/start.asciidoc

@@ -7,18 +7,37 @@
 
 Starts the {watcher} service if it is not already running.
 
-[float]
+[[watcher-api-start-request]]
-==== Request
+==== {api-request-title}
 
 `POST _watcher/_start`
 
-==== Authorization
+[[watcher-api-start-prereqs]]
+==== {api-prereq-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+* You must have `manage_watcher` cluster privileges to use this API. For more
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
+information, see {stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-start-desc]]
-==== Examples
+//==== {api-description-title}
+
+//[[watcher-api-start-path-params]]
+//==== {api-path-parms-title}
+
+//[[watcher-api-start-query-params]]
+//==== {api-query-parms-title}
+
+//[[watcher-api-start-request-body]]
+//==== {api-request-body-title}
+
+//[[watcher-api-start-response-body]]
+//==== {api-response-body-title}
+
+//[[watcher-api-start-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-start-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/watcher/stats.asciidoc

@@ -8,66 +8,75 @@
 
 Retrieves the current {watcher} metrics.
 
-[float]
+[[watcher-api-stats-request]]
-==== Request
+==== {api-request-title}
 
 `GET _watcher/stats` +
 
 `GET _watcher/stats/<metric>`
 
-[float]
+[[watcher-api-stats-prereqs]]
-==== Description
+==== {api-prereq-title}
 
-This API always returns basic metrics. You retrieve more metrics by using
+* You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
-the `metric` parameter.
+this API. For more information, see
+{stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-stats-desc]]
-===== Current executing watches metric
+//==== {api-description-title}
 
-The current executing watches metric gives insight into the watches that are
+[[watcher-api-stats-path-params]]
-currently being executed by {watcher}. Additional information is shared per
+==== {api-path-parms-title}
-watch that is currently executing. This information includes the `watch_id`,
-the time its execution started and its current execution phase.
-
-To include this metric, the `metric` option should be set to `current_watches`
-or `_all`. In addition you can also specify the `emit_stacktraces=true`
-parameter, which adds stack traces for each watch that is being executed. These
-stack traces can give you more insight into an execution of a watch.
-
-[float]
-===== Queued watches metric
-
-{watcher} moderates the execution of watches such that their execution won't put
-too much pressure on the node and its resources. If too many watches trigger
-concurrently and there isn't enough capacity to execute them all, some of the
-watches are queued, waiting for the current executing watches to finish their
-execution. The queued watches metric gives insight on these queued watches.
-
-To include this metric, the `metric` option should include `queued_watches` or
-`_all`.
-
-[float]
-==== Path Parameters
 
 `emit_stacktraces`::
-  (boolean) Defines whether stack traces are generated for each watch that is
+  (Optional, boolean) Defines whether stack traces are generated for each watch
-  running. The default value is `false`.
+  that is running. The default value is `false`.
 
-`metric`::
+`<metric>`::
-  (enum) Defines which additional metrics are included in the response.
+  (Optional, enum) Defines which additional metrics are included in the response.
   `current_watches`::: Includes the current executing watches in the response.
   `queued_watches`::: Includes the watches queued for execution in the response.
   `_all`::: Includes all metrics in the response.
 
-[float]
+//[[watcher-api-stats-query-params]]
-==== Authorization
+//==== {api-query-parms-title}
 
-You must have `manage_watcher` or `monitor_watcher` cluster privileges to use
+//[[watcher-api-stats-request-body]]
-this API. For more information, see
+//==== {api-request-body-title}
-{xpack-ref}/security-privileges.html[Security Privileges].
 
-[float]
+[[watcher-api-stats-response-body]]
-==== Examples
+==== {api-response-body-title}
+
+This API always returns basic metrics. You retrieve more metrics by using
+the `metric` parameter.
+
+`current_watches`::
+  (list) The current executing watches metric gives insight into the watches
+  that are currently being executed by {watcher}. Additional information is
+  shared per watch that is currently executing. This information includes the
+  `watch_id`, the time its execution started and its current execution phase.
+  
+  To include this metric, the `metric` option should be set to `current_watches`
+  or `_all`. In addition you can also specify the `emit_stacktraces=true`
+  parameter, which adds stack traces for each watch that is being executed. These
+  stack traces can give you more insight into an execution of a watch.
+
+`queued_watches`::
+  (list) {watcher} moderates the execution of watches such that their execution
+  won't put too much pressure on the node and its resources. If too many watches
+  trigger concurrently and there isn't enough capacity to execute them all, some
+  of the watches are queued, waiting for the current executing watches to finish
+  their execution. The queued watches metric gives insight on these queued
+  watches.
+  
+  To include this metric, the `metric` option should include `queued_watches` or
+  `_all`.
+
+//[[watcher-api-stats-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-stats-example]]
+==== {api-examples-title}
 
 The following example calls the `stats` API to retrieve basic metrics:
 

x-pack/docs/en/rest-api/watcher/stop.asciidoc

@@ -7,19 +7,37 @@
 
 Stops the {watcher} service if it is running.
 
-[float]
+[[watcher-api-stop-request]]
-==== Request
+==== {api-request-title}
 
 `POST _watcher/_stop`
 
-[float]
+[[watcher-api-stop-prereqs]]
-==== Authorization
+==== {api-prereq-title}
 
-You must have `manage_watcher` cluster privileges to use this API. For more
+* You must have `manage_watcher` cluster privileges to use this API. For more
-information, see {xpack-ref}/security-privileges.html[Security Privileges].
+information, see {stack-ov}/security-privileges.html[Security privileges].
 
-[float]
+//[[watcher-api-stop-desc]]
-==== Examples
+//==== {api-description-title}
+
+//[[watcher-api-stop-path-params]]
+//==== {api-path-parms-title}
+
+//[[watcher-api-stop-query-params]]
+//==== {api-query-parms-title}
+
+//[[watcher-api-stop-request-body]]
+//==== {api-request-body-title}
+
+//[[watcher-api-stop-response-body]]
+//==== {api-response-body-title}
+
+//[[watcher-api-stop-response-codes]]
+//==== {api-response-codes-title}
+
+[[watcher-api-stop-example]]
+==== {api-examples-title}
 
 [source,js]
 --------------------------------------------------