Add descriptions for cat APIs

specification/cat/aliases/CatAliasesRequest.ts

@@ -21,13 +21,18 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { ExpandWildcards, Names } from '@_types/common'
 
 /**
+ * Retrieves the cluster’s index aliases, including filter and routing information.
+ * The API does not return data stream aliases.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
  * @rest_spec_name cat.aliases
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id cat-alias
+ * @index_privileges view_index_metadata
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /** A comma-separated list of aliases to retrieve. Supports wildcards (`*`).  To retrieve all aliases, omit this parameter or use `*` or `_all`. */
     name?: Names
   }
   query_parameters: {

specification/cat/allocation/CatAllocationRequest.ts

@@ -21,16 +21,21 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { Bytes, NodeIds } from '@_types/common'
 
 /**
+ * Provides a snapshot of the number of shards allocated to each data node and their disk space.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
  * @rest_spec_name cat.allocation
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id cat-allocation
+ * @cluster_privileges monitor
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /** Comma-separated list of node identifiers or names used to limit the returned information. */
     node_id?: NodeIds
   }
   query_parameters: {
+    /** The unit used to display byte values. */
     bytes?: Bytes
   }
 }

specification/cat/allocation/types.ts

@@ -23,46 +23,52 @@ import { Percentage } from '@_types/Numeric'
 
 export class AllocationRecord {
   /**
-   * number of shards on node
+   * Number of primary and replica shards assigned to the node.
    * @aliases s
    */
   shards?: string
   /**
-   * disk used by ES indices
+   * Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.
+   * IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.
    * @aliases di,diskIndices
    */
   'disk.indices'?: ByteSize | null
   /**
-   * disk used (total, not just ES)
+   * Total disk space in use.
+   * Elasticsearch retrieves this metric from the node’s operating system (OS).
+   * The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node.
+   * Unlike `disk.indices`, this metric does not double-count disk space for hard-linked files.
    * @aliases du,diskUsed
    */
   'disk.used'?: ByteSize | null
   /**
-   * disk available
+   * Free disk space available to Elasticsearch.
+   * Elasticsearch retrieves this metric from the node’s operating system.
+   * Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
    * @aliases da,diskAvail
    */
   'disk.avail'?: ByteSize | null
   /**
-   * total capacity of all volumes
+   * Total disk space for the node, including in-use and available space.
    * @aliases dt,diskTotal
    */
   'disk.total'?: ByteSize | null
   /**
-   * percent disk used
+   * Total percentage of disk space in use. Calculated as `disk.used / disk.total`.
    * @aliases dp,diskPercent
    */
   'disk.percent'?: Percentage | null
   /**
-   * host of node
+   * Network host for the node. Set using the `network.host` setting.
    * @aliases h
    */
   host?: Host | null
   /**
-   * ip of node
+   * IP address and port for the node.
    */
   ip?: Ip | null
   /**
-   * name of node
+   * Name for the node. Set using the `node.name` setting.
    * @aliases n
    */
   node?: string

specification/cat/component_templates/CatComponentTemplatesRequest.ts

@@ -20,12 +20,18 @@
 import { CatRequestBase } from '@cat/_types/CatBase'
 
 /**
+ * Returns information about component templates in a cluster.
+ * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use the get component template API.
  * @rest_spec_name cat.component_templates
  * @availability stack since=5.1.0 stability=stable
  * @availability serverless stability=stable visibility=public
+ * @cluster_privileges monitor
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /** The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned. */
     name?: string
   }
 }

specification/cat/count/CatCountRequest.ts

@@ -21,13 +21,22 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { Indices } from '@_types/common'
 
 /**
+ * Provides quick access to a document count for a data stream, an index, or an entire cluster.
+ * NOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use the count API.
  * @rest_spec_name cat.count
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id cat-count
+ * @index_privileges read
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /**
+     * Comma-separated list of data streams, indices, and aliases used to limit the request.
+     * Supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`.
+     */
     index?: Indices
   }
 }

specification/cat/fielddata/CatFielddataRequest.ts

@@ -21,16 +21,27 @@ import { CatRequestBase } from '@cat/_types/CatBase'
 import { Bytes, Fields } from '@_types/common'
 
 /**
+ * Returns the amount of heap memory currently used by the field data cache on every data node in the cluster.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use the nodes stats API.
  * @rest_spec_name cat.fielddata
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @doc_id cat-fielddata
+ * @cluster_privileges monitor
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /**
+     * Comma-separated list of fields used to limit returned information.
+     * To retrieve all fields, omit this parameter.
+     */
     fields?: Fields
   }
   query_parameters: {
+    /** The unit used to display byte values. */
     bytes?: Bytes
+    /** Comma-separated list of fields used to limit returned information. */
+    fields?: Fields
   }
 }

specification/cat/health/CatHealthRequest.ts

@@ -18,14 +18,34 @@
  */
 
 import { CatRequestBase } from '@cat/_types/CatBase'
+import { TimeUnit } from '@_types/Time'
 
 /**
+ * Returns the health status of a cluster, similar to the cluster health API.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use the cluster health API.
+ * This API is often used to check malfunctioning clusters.
+ * To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats:
+ * `HH:MM:SS`, which is human-readable but includes no date information;
+ * `Unix epoch time`, which is machine-sortable and includes date information.
+ * The latter format is useful for cluster recoveries that take multiple days.
+ * You can use the cat health API to verify cluster health across multiple nodes.
+ * You also can use the API to track the recovery of a large cluster over a longer period of time.
  * @rest_spec_name cat.health
  * @availability stack since=0.0.0 stability=stable
  * @doc_id cat-health
+ * @cluster_privileges monitor
  */
 export interface Request extends CatRequestBase {
   query_parameters: {
+    /**
+     * The unit used to display time values.
+     */
+    time?: TimeUnit
+    /**
+     * If true, returns `HH:MM:SS` and Unix epoch timestamps.
+     * @server_default true
+     */
     ts?: boolean
   }
 }

specification/cat/indices/CatIndicesRequest.ts

@@ -22,21 +22,47 @@ import { Bytes, ExpandWildcards, HealthStatus, Indices } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Returns high-level information about indices in a cluster, including backing indices for data streams.
+ * IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+ * They are not intended for use by applications. For application consumption, use the get index API.
+ * Use the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas.
+ * These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.
+ * To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
  * @rest_spec_name cat.indices
  * @availability stack since=0.0.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id cat-indices
+ * @cluster_privileges monitor
+ * @index_privileges monitor
  */
 export interface Request extends CatRequestBase {
   path_parts: {
+    /**
+     * Comma-separated list of data streams, indices, and aliases used to limit the request.
+     * Supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`.
+     */
     index?: Indices
   }
   query_parameters: {
+    /** The unit used to display byte values. */
     bytes?: Bytes
+    /**
+     * The type of index that wildcard patterns can match.
+     */
     expand_wildcards?: ExpandWildcards
+    /** The health status used to limit returned indices. By default, the response includes indices of any health status. */
     health?: HealthStatus
+    /**
+     * If true, the response includes information from segments that are not loaded into memory.
+     * @server_default false
+     */
     include_unloaded_segments?: boolean
+    /**
+     * If true, the response only includes information from primary shards.
+     * @server_default false
+     */
     pri?: boolean
+    /** The unit used to display time values. */
     time?: TimeUnit
   }
 }

specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts

@@ -32,6 +32,7 @@ import { Duration } from '@_types/Time'
  * @availability stack since=7.7.0 stability=stable
  * @availability serverless stability=stable visibility=public
  * @doc_id cat-dfanalytics
+ * @cluster_privileges monitor_ml
  */
 export interface Request extends CatRequestBase {
   path_parts: {