diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/WatcherDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/WatcherDocumentationIT.java
index 17cf66867304a..4f41b723943ad 100644
--- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/WatcherDocumentationIT.java
+++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/WatcherDocumentationIT.java
@@ -162,9 +162,12 @@ public void testAckWatch() throws Exception {
         }
 
         {
-            //tag::ack-watch-execute
+            //tag::ack-watch-request
             AckWatchRequest request = new AckWatchRequest("my_watch_id", // <1>
                 "logme", "emailme"); // <2>
+            //end::ack-watch-request
+
+            //tag::ack-watch-execute
             AckWatchResponse response = client.watcher().ackWatch(request, RequestOptions.DEFAULT);
             //end::ack-watch-execute
 
diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc
index 3bc5905a46fe5..2aaac272e8455 100644
--- a/docs/java-rest/high-level/supported-apis.asciidoc
+++ b/docs/java-rest/high-level/supported-apis.asciidoc
@@ -306,14 +306,14 @@ include::security/change-password.asciidoc[]
 
 == Watcher APIs
 
-:upid: {mainid}-document
+:upid: {mainid}-watcher
 :doc-tests-file: {doc-tests}/WatcherDocumentationIT.java
 
 The Java High Level REST Client supports the following Watcher APIs:
 
 * <<java-rest-high-x-pack-watcher-put-watch>>
 * <<java-rest-high-x-pack-watcher-delete-watch>>
-* <<java-rest-high-watcher-ack-watch>>
+* <<{upid}-ack-watch>>
 * <<{upid}-activate-watch>>
 
 include::watcher/put-watch.asciidoc[]
diff --git a/docs/java-rest/high-level/watcher/ack-watch.asciidoc b/docs/java-rest/high-level/watcher/ack-watch.asciidoc
index 13b62ba3be816..46a516798594b 100644
--- a/docs/java-rest/high-level/watcher/ack-watch.asciidoc
+++ b/docs/java-rest/high-level/watcher/ack-watch.asciidoc
@@ -1,7 +1,13 @@
-[[java-rest-high-watcher-ack-watch]]
+--
+:api: ack-watch
+:request: AckWatchRequest
+:response: AckWatchResponse
+--
+
+[id="{upid}-{api}"]
 === Ack Watch API
 
-[[java-rest-high-watcher-ack-watch-execution]]
+[id="{upid}-{api}-request"]
 ==== Execution
 
 {xpack-ref}/actions.html#actions-ack-throttle[Acknowledging a watch] enables you
@@ -10,48 +16,23 @@ through the following request:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> The ID of the watch to ack.
 <2> An optional list of IDs representing the watch actions that should be acked.
 If no action IDs are provided, then all of the watch's actions will be acked.
 
-[[java-rest-high-watcher-ack-watch-response]]
+[id="{upid}-{api}-response"]
 ==== Response
 
-The returned `AckWatchResponse` contains the new status of the requested watch:
+The returned +{response}+ contains the new status of the requested watch:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> The status of a specific action that was acked.
 <2> The acknowledgement state of the action. If the action was successfully
 acked, this state will be equal to `AckStatus.State.ACKED`.
 
-[[java-rest-high-watcher-ack-watch-async]]
-==== Asynchronous Execution
-
-This request can be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute-async]
---------------------------------------------------
-<1> The `AckWatchRequest` to execute and the `ActionListener` to use when
-the execution completes.
-
-The asynchronous method does not block and returns immediately. Once the request
-completes, the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A listener for `AckWatchResponse` can be constructed as follows:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/WatcherDocumentationIT.java[ack-watch-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument.
-<2> Called in case of failure. The raised exception is provided as an argument.
+include::../execution.asciidoc[]