diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index a786c03d3b..d58c078cd2 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -895,6 +895,7 @@ test-grok-pattern,https://www.elastic.co/docs/api/doc/elasticsearch/operation/op
 time-value,https://github.com/elastic/elasticsearch/blob/current/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java,
 time-zone-id,https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html,
 trim-processor,https://www.elastic.co/docs/reference/enrich-processor/trim-processor,
+update-by-query,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/update-by-query-api,
 update-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-update-data-frame-analytics,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/update-dfanalytics.html
 update-desired-nodes,https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-cluster,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cluster.html
 update-license,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-license-post,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/update-license.html
diff --git a/specification/_global/update_by_query/UpdateByQueryRequest.ts b/specification/_global/update_by_query/UpdateByQueryRequest.ts
index 2f24aecf2c..8bfa106785 100644
--- a/specification/_global/update_by_query/UpdateByQueryRequest.ts
+++ b/specification/_global/update_by_query/UpdateByQueryRequest.ts
@@ -59,6 +59,30 @@ import { Duration } from '@_types/Time'
  * Any query or update failures cause the update by query request to fail and the failures are shown in the response.
  * Any update requests that completed successfully still stick, they are not rolled back.
  *
+ * **Refreshing shards**
+ *
+ * Specifying the `refresh` parameter refreshes all shards once the request completes.
+ * This is different to the update API's `refresh` parameter, which causes only the shard
+ * that received the request to be refreshed. Unlike the update API, it does not support
+ * `wait_for`.
+ *
+ * **Running update by query asynchronously**
+ *
+ * If the request contains `wait_for_completion=false`, Elasticsearch
+ * performs some preflight checks, launches the request, and returns a
+ * [task](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-tasks) you can use to cancel or get the status of the task.
+ * Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`.
+ *
+ * **Waiting for active shards**
+ *
+ * `wait_for_active_shards` controls how many copies of a shard must be active
+ * before proceeding with the request. See [`wait_for_active_shards`](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-create#operation-create-wait_for_active_shards)
+ * for details. `timeout` controls how long each write request waits for unavailable
+ * shards to become available. Both work exactly the way they work in the
+ * [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk). Update by query uses scrolled searches, so you can also
+ * specify the `scroll` parameter to control how long it keeps the search context
+ * alive, for example `?scroll=10m`. The default is 5 minutes.
+ *
  * **Throttling update requests**
  *
  * To control the rate at which update by query issues batches of update operations, you can set `requests_per_second` to any positive decimal number.
@@ -103,28 +127,14 @@ import { Duration } from '@_types/Time'
  * * Update performance scales linearly across available resources with the number of slices.
  *
  * Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.
- *
- * **Update the document source**
- *
- * Update by query supports scripts to update the document source.
- * As with the update API, you can set `ctx.op` to change the operation that is performed.
- *
- * Set `ctx.op = "noop"` if your script decides that it doesn't have to make any changes.
- * The update by query operation skips updating the document and increments the `noop` counter.
- *
- * Set `ctx.op = "delete"` if your script decides that the document should be deleted.
- * The update by query operation deletes the document and increments the `deleted` counter.
- *
- * Update by query supports only `index`, `noop`, and `delete`.
- * Setting `ctx.op` to anything else is an error.
- * Setting any other field in `ctx` is an error.
- * This API enables you to only modify the source of matching documents; you cannot move them.
+ * Refer to the linked documentation for examples of how to update documents using the `_update_by_query` API:
  * @rest_spec_name update_by_query
  * @availability stack since=2.4.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @index_privileges read,write
  * @doc_tag document
  * @doc_id docs-update-by-query
+ * @ext_doc_id update-by-query
  */
 export interface Request extends RequestBase {
   urls: [