From 4a33352a948581b289e2241e3ecb708536e2954b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?=
 <istvan.szabo@elastic.co>
Date: Thu, 27 Feb 2020 12:50:11 +0100
Subject: [PATCH] [DOCS] Adds cat trained model API documentation (#52824)

---
 docs/reference/cat.asciidoc                   |   2 +
 docs/reference/cat/trainedmodel.asciidoc      | 126 ++++++++++++++++++
 .../api/cat.ml_trained_models.json            |   2 +-
 3 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/cat/trainedmodel.asciidoc

diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc
index 6f12302b30ec0..4c30d21693d99 100644
--- a/docs/reference/cat.asciidoc
+++ b/docs/reference/cat.asciidoc
@@ -257,6 +257,8 @@ include::cat/tasks.asciidoc[]
 
 include::cat/thread_pool.asciidoc[]
 
+include::cat/trainedmodel.asciidoc[]
+
 include::cat/shards.asciidoc[]
 
 include::cat/segments.asciidoc[]
diff --git a/docs/reference/cat/trainedmodel.asciidoc b/docs/reference/cat/trainedmodel.asciidoc
new file mode 100644
index 0000000000000..679133157cd4d
--- /dev/null
+++ b/docs/reference/cat/trainedmodel.asciidoc
@@ -0,0 +1,126 @@
+[role="xpack"]
+[testenv="platinum"]
+[[cat-trained-model]]
+=== cat trained model API
+++++
+<titleabbrev>cat trained model</titleabbrev>
+++++
+
+Returns configuration and usage information about {infer} trained models.
+
+
+[[cat-trained-model-request]]
+==== {api-request-title}
+
+`GET /_cat/ml/trained_models`
+
+
+[[cat-trained-model-prereqs]]
+==== {api-prereq-title}
+
+If the {es} {security-features} are enabled, you must have the following 
+privileges:
+
+* cluster: `monitor_ml`
+
+For more information, see <<security-privileges>> and 
+{ml-docs}/setup.html[Set up {ml-features}].
+
+
+////
+[[cat-trained-model-desc]]
+==== {api-description-title}
+////
+
+
+[[cat-trained-model-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
++
+If you do not specify which columns to include, the API returns the default
+columns. If you explicitly specify one or more columns, it returns only the
+specified columns.
++
+Valid columns are:
+
+`create_time`, `ct`:::
+The time when the trained model was created.
+
+`created_by`, `c`, `createdBy`:::
+Information on the creator of the trained model.
+
+`data_frame_analytics_id`, `df`, `dataFrameAnalytics`:::
+Identifier for the {dfanalytics-job} that created the model. Only displayed if 
+it is still available.
+
+`description`, `d`:::
+The description of the trained model.
+
+`heap_size`, `hs`, `modelHeapSize`:::
+(Default)
+The estimated heap size to keep the trained model in memory.
+
+`id`:::
+(Default)
+Idetifier for the trained model.
+
+`ingest.count`, `ic`, `ingestCount`:::
+The total number of documents that are processed by the model.
+
+`ingest.current`, `icurr`, `ingestCurrent`:::
+The total number of document that are currently being handled by the trained 
+model.
+
+`ingest.failed`, `if`, `ingestFailed`:::
+The total number of failed ingest attempts with the trained model.
+
+`ingest.pipelines`, `ip`, `ingestPipelines`:::
+(Default)
+The total number of ingest pipelines that are referencing the trained model.
+
+`ingest.time`, `it`, `ingestTime`:::
+The total time that is spent processing documents with the trained model.
+
+`license`, `l`:::
+The license level of the trained model.
+
+`operations`, `o`, `modelOperations`:::
+(Default)
+The estimated number of operations to use the trained model. This number helps 
+measuring the computational complexity of the model.
+
+`version`, `v`:::
+The {es} version number in which the trained model was created.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+
+[[cat-trained-model-example]]
+==== {api-examples-title}
+
+[source,console]
+--------------------------------------------------
+GET _cat/ml/trained_models?h=c,o,l,ct,v&v
+--------------------------------------------------
+// TEST[skip:kibana sample data]
+
+
+[source,console-result]
+----
+id                           created_by operations license  create_time              version
+ddddd-1580216177138              _xpack 196        PLATINUM 2020-01-28T12:56:17.138Z 8.0.0
+flight-regress-1580215685537     _xpack 102        PLATINUM 2020-01-28T12:48:05.537Z 8.0.0
+lang_ident_model_1               _xpack 39629      BASIC    2019-12-05T12:28:34.594Z 7.6.0
+----
+// TESTRESPONSE[skip:kibana sample data]
diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
index c22ea1e095e87..77875d03a2f78 100644
--- a/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
+++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_trained_models.json
@@ -1,7 +1,7 @@
 {
   "cat.ml_trained_models":{
     "documentation":{
-      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/get-inference-stats.html"
+      "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/cat-trained-model.html"
     },
     "stability":"stable",
     "url":{