elastic · stefnestor · Oct 9, 2024 · Sep 25, 2024 · Sep 25, 2024 · Oct 4, 2024
diff --git a/docs/reference/cat/alias.asciidoc b/docs/reference/cat/alias.asciidoc
@@ -12,7 +12,7 @@ consumption, use the <<aliases,aliases API>>.
 ====
 
 Retrieves the cluster's <<aliases,index aliases>>, including filter and routing
-information. The API does not return data stream aliases.
+information. The API does not return <<data-streams,data stream>> aliases.
 
 [[cat-alias-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/allocation.asciidoc b/docs/reference/cat/allocation.asciidoc
@@ -7,10 +7,11 @@
 [IMPORTANT]
 ====
 cat APIs are only intended for human consumption using the command line or {kib}
-console. They are _not_ intended for use by applications.
+console. They are _not_ intended for use by applications. For application 
+consumption, use the <<cluster-nodes-stats,node stats API>>.
 ====
 
-Provides a snapshot of the number of shards allocated to each data node
+Provides a snapshot of the number of shards <<shard-allocation-relocation-recovery,allocated>> to each data node
 and their disk space.
 
 

diff --git a/docs/reference/cat/anomaly-detectors.asciidoc b/docs/reference/cat/anomaly-detectors.asciidoc
@@ -13,7 +13,7 @@ consumption, use the
 <<ml-get-job-stats,get anomaly detection job statistics API>>.
 ====
 
-Returns configuration and usage information about {anomaly-jobs}.
+Returns configuration and usage information about {ml-docs}/ml-ad-overview.html[{anomaly-jobs}].
 
 [[cat-anomaly-detectors-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/datafeeds.asciidoc b/docs/reference/cat/datafeeds.asciidoc
@@ -12,7 +12,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<ml-get-datafeed-stats,get datafeed statistics API>>.
 ====
 
-Returns configuration and usage information about {dfeeds}.
+Returns configuration and usage information about {ml-docs}/ml-ad-run-jobs.html#ml-ad-datafeeds[{dfeeds}].
 
 [[cat-datafeeds-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/dataframeanalytics.asciidoc b/docs/reference/cat/dataframeanalytics.asciidoc
@@ -13,7 +13,7 @@ consumption, use the
 <<get-dfanalytics-stats,get data frame analytics jobs statistics API>>.
 ====
 
-Returns configuration and usage information about {dfanalytics-jobs}.
+Returns configuration and usage information about {ml-docs}/ml-dfanalytics.html[{dfanalytics-jobs}].
 
 
 [[cat-dfanalytics-request]]

diff --git a/docs/reference/cat/indices.asciidoc b/docs/reference/cat/indices.asciidoc
@@ -11,8 +11,8 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<indices-get-index,get index API>>.
 ====
 
-Returns high-level information about indices in a cluster, including backing
-indices for data streams.
+Returns high-level information about <<documents-indices,indices>> in a cluster, including backing
+indices for <<data-streams,data streams>>.
 
 
 [[cat-indices-api-request]]

diff --git a/docs/reference/cat/master.asciidoc b/docs/reference/cat/master.asciidoc
@@ -11,7 +11,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<cluster-nodes-info,nodes info API>>.
 ====
 
-Returns information about the master node, including the ID, bound IP address,
+Returns information about the <<cluster-state-publishing,master node>>, including the ID, bound IP address,
 and name.
 
 

diff --git a/docs/reference/cat/nodeattrs.asciidoc b/docs/reference/cat/nodeattrs.asciidoc
@@ -11,7 +11,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<cluster-nodes-info,nodes info API>>.
 ====
 
-Returns information about custom node attributes.
+Returns information about <<shard-allocation-filtering,custom node attributes>>.
 
 [[cat-nodeattrs-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/nodes.asciidoc b/docs/reference/cat/nodes.asciidoc
@@ -13,7 +13,7 @@ They are _not_ intended for use by applications.
 For application consumption, use the <<cluster-nodes-info,nodes info API>>.
 ====
 
-Returns information about a cluster's nodes.
+Returns information about a <<modules-node,cluster's nodes>>.
 
 [[cat-nodes-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/pending_tasks.asciidoc b/docs/reference/cat/pending_tasks.asciidoc
@@ -11,8 +11,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<cluster-pending,pending cluster tasks API>>.
 ====
 
-Returns cluster-level changes that have not yet been executed, similar to the
-<<cluster-pending, pending cluster tasks>> API.
+Returns <<cluster-state-publishing,cluster-level changes>> that have not yet been executed.
 
 [[cat-pending-tasks-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/plugins.asciidoc b/docs/reference/cat/plugins.asciidoc
@@ -12,7 +12,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<cluster-nodes-info,nodes info API>>.
 ====
 
-Returns a list of plugins running on each node of a cluster.
+Returns a list of <<modules-plugins,plugins>> running on each node of a cluster.
 
 
 [[cat-plugins-api-request]]

diff --git a/docs/reference/cat/recovery.asciidoc b/docs/reference/cat/recovery.asciidoc
@@ -11,10 +11,9 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<indices-recovery,index recovery API>>.
 ====
 
-Returns information about ongoing and completed shard recoveries,
-similar to the <<indices-recovery, index recovery>> API.
+Returns information about ongoing and completed <<shard-allocation-relocation-recovery,shard recoveries>>.
 
-For data streams, the API returns information about the stream's backing
+For <<data-streams,data streams>>, the API returns information about the stream's backing
 indices.
 
 [[cat-recovery-api-request]]

diff --git a/docs/reference/cat/segments.asciidoc b/docs/reference/cat/segments.asciidoc
@@ -12,10 +12,9 @@ consumption, use the <<indices-segments,index segments API>>.
 ====
 
 Returns low-level information about the https://lucene.apache.org/core/[Lucene]
-segments in index shards, similar to the <<indices-segments, indices segments>>
-API.
+segments in index shards.
 
-For data streams, the API returns information about the stream's backing
+For <<data-streams,data streams>>, the API returns information about the stream's backing
 indices.
 
 [[cat-segments-api-request]]

diff --git a/docs/reference/cat/shards.asciidoc b/docs/reference/cat/shards.asciidoc
@@ -9,13 +9,16 @@
 ====
 cat APIs are only intended for human consumption using the command line or {kib}
 console.
-They are _not_ intended for use by applications.
+They are _not_ intended for use by applications. For application 
+consumption, use the <<cluster-state,cluster state API>>.
 ====
 
-The `shards` command is the detailed view of what nodes contain which shards.
-It will tell you if it's a primary or replica, the number of docs, the bytes it takes on disk, and the node where it's located.
+The `shards` command is the detailed view of all nodes' shard <<shard-allocation-relocation-recovery,allocation>>.
+It will tell you if the shard is a primary or replica, the number of docs, the 
+bytes it takes on disk, the node where it's located, and if the shard is 
+currently <<shard-allocation-relocation-recovery,recovering>>.
 
-For data streams, the API returns information about the stream's backing indices.
+For <<data-streams,data streams>>, the API returns information about the stream's backing indices.
 
 [[cat-shards-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/cat/trainedmodel.asciidoc b/docs/reference/cat/trainedmodel.asciidoc
@@ -12,7 +12,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<get-trained-models,get trained models API>>.
 ====
 
-Returns configuration and usage information about {infer} trained models.
+Returns configuration and usage information about {ml-docs}/ml-nlp-deploy-models.html[{infer} trained models].
 
 
 [[cat-trained-model-request]]

diff --git a/docs/reference/cat/transforms.asciidoc b/docs/reference/cat/transforms.asciidoc
@@ -12,7 +12,7 @@ console. They are _not_ intended for use by applications. For application
 consumption, use the <<get-transform,get transforms API>>.
 ====
 
-Returns configuration and usage information about {transforms}.
+Returns configuration and usage information about <<transforms,{transforms}>>.
 
 [[cat-transforms-api-request]]
 ==== {api-request-title}

diff --git a/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc b/docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc
@@ -7,7 +7,7 @@
 <titleabbrev>Get {dfeed} statistics</titleabbrev>
 ++++
 
-Retrieves usage information for {dfeeds}.
+Retrieves usage information for {ml-docs}/ml-ad-run-jobs.html#ml-ad-datafeeds[{dfeeds}].
 
 [[ml-get-datafeed-stats-request]]
 == {api-request-title}

diff --git a/docs/reference/ml/anomaly-detection/apis/get-job-stats.asciidoc b/docs/reference/ml/anomaly-detection/apis/get-job-stats.asciidoc
@@ -5,7 +5,7 @@
 <titleabbrev>Get job statistics</titleabbrev>
 ++++
 
-Retrieves usage information for {anomaly-jobs}.
+Retrieves usage information for {ml-docs}/ml-ad-overview.html[{anomaly-jobs}].
 
 [[ml-get-job-stats-request]]
 == {api-request-title}

diff --git a/docs/reference/ml/df-analytics/apis/get-dfanalytics-stats.asciidoc b/docs/reference/ml/df-analytics/apis/get-dfanalytics-stats.asciidoc
@@ -6,7 +6,7 @@
 <titleabbrev>Get {dfanalytics-jobs} stats</titleabbrev>
 ++++
 
-Retrieves usage information for {dfanalytics-jobs}.
+Retrieves usage information for {ml-docs}/ml-dfanalytics.html[{dfanalytics-jobs}].
 
 
 [[ml-get-dfanalytics-stats-request]]

diff --git a/docs/reference/ml/trained-models/apis/get-trained-models.asciidoc b/docs/reference/ml/trained-models/apis/get-trained-models.asciidoc
@@ -6,7 +6,7 @@
 <titleabbrev>Get trained models</titleabbrev>
 ++++
 
-Retrieves configuration information for a trained model.
+Retrieves configuration information about {ml-docs}/ml-nlp-deploy-models.html[{infer} trained models].
 
 
 [[ml-get-trained-models-request]]