elastic · szabosteve · Jul 5, 2019 · Jul 2, 2019 · Jul 2, 2019 · Jul 2, 2019
diff --git a/docs/reference/ml/apis/delete-dfanalytics.asciidoc b/docs/reference/ml/apis/delete-dfanalytics.asciidoc
@@ -7,7 +7,7 @@
 <titleabbrev>Delete {dfanalytics-jobs}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Deletes an existing {dfanalytics-job}.
 

diff --git a/docs/reference/ml/apis/evaluate-dfanalytics.asciidoc b/docs/reference/ml/apis/evaluate-dfanalytics.asciidoc
@@ -8,10 +8,15 @@
 <titleabbrev>Evaluate {dfanalytics}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Evaluates the executed analysis on an index that is already annotated with a 
-field that marks each {dataframe} row with the results of the analytics.
+field that contains the results of the analytics (the `ground truth`) for each 
+{dataframe} row. Evaluation is typically done via calculating a set of metrics 
+that capture various aspects of the quality of the results over the data for 
+which we have the `ground truth`. For different types of analyses different 
+metrics are suitable. This API packages together commonly used metrics for 
+various analyses.
 
 [[ml-evaluate-dataframe-request]]
 ==== {api-request-title}

diff --git a/docs/reference/ml/apis/get-dfanalytics-stats.asciidoc b/docs/reference/ml/apis/get-dfanalytics-stats.asciidoc
@@ -7,7 +7,7 @@
 <titleabbrev>Get {dfanalytics-jobs} stats</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Retrieves usage information for {dfanalytics-jobs}.
 
@@ -38,6 +38,10 @@ information, see {stack-ov}/security-privileges.html[Security privileges] and
   (string) Identifier for the {dfanalytics-job}. If you do not specify one of 
   these options, the API returns information for the first hundred
   {dfanalytics-jobs}.
+
+`allow_no_match` (Optional)
+  (boolean) If `false` and the `data_frame_analytics_id` does not match any 
+  {dfanalytics-job} an error will be returned. The default value is `true`.
 
 [[ml-get-dfanalytics-stats-query-params]]
 ==== {api-query-parms-title}

diff --git a/docs/reference/ml/apis/get-dfanalytics.asciidoc b/docs/reference/ml/apis/get-dfanalytics.asciidoc
@@ -7,7 +7,7 @@
 <titleabbrev>Get {dfanalytics-jobs}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Retrieves configuration information for {dfanalytics-jobs}.
 
@@ -45,6 +45,10 @@ You can get information for all {dfanalytics-jobs} by using _all, by specifying
   (string) Identifier for the {dfanalytics-job}. If you do not specify one of 
   these options, the API returns information for the first hundred
   {dfanalytics-jobs}.
+
+`allow_no_match` (Optional)
+  (boolean) If `false` and the `data_frame_analytics_id` does not match any 
+  {dfanalytics-job} an error will be returned. The default value is `true`.
 
 [[ml-get-dfanalytics-query-params]]
 ==== {api-query-parms-title}

diff --git a/docs/reference/ml/apis/put-dfanalytics.asciidoc b/docs/reference/ml/apis/put-dfanalytics.asciidoc
@@ -7,7 +7,7 @@
 <titleabbrev>Create {dfanalytics-jobs}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Instantiates a {dfanalytics-job}.
 
@@ -43,7 +43,18 @@ and {stack-ov}/built-in-roles.html[Built-in roles].
 
 `dest` (Required)::
   (object) The destination configuration, consisting of `index` and optionally 
-  `results_field` (`ml` by default).
+  `results_field` (`ml` by default). The destination index will be automatically 
+  created if it does not exist. The `index.number_of_shards` and 
+  `index.number_of_replicas` settings of the source index will be copied over the 
+  destination index. When the source index matches multiple indices, these 
+  settings will be set to the maximum values found in the source indices.
+
+  The mappings of the source indicies are also attempted to being copied over
+  `dest`, however, if the mappings of any of the fields don't match among the 
+  source indicies, the attempt will fail with an error message.
+
+  If `dest` already exists, then it will be use as is. This makes it possible to 
+  set up the destination index in advance with custom settings and mappings.
 
 `analysis` (Required)::
   (object) Defines the type of {dfanalytics} you want to perform on your source 

diff --git a/docs/reference/ml/apis/start-dfanalytics.asciidoc b/docs/reference/ml/apis/start-dfanalytics.asciidoc
@@ -8,9 +8,9 @@
 <titleabbrev>Start {dfanalytics-jobs}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
-Starts one or more {dfanalytics-jobs}.
+Starts a {dfanalytics-job}.
 
 [[ml-start-dfanalytics-request]]
 ==== {api-request-title}
@@ -33,6 +33,10 @@ and {stack-ov}/built-in-roles.html[Built-in roles].
   (string) Identifier for the {dfanalytics-job}. This identifier can contain
   lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It
   must start and end with alphanumeric characters.
+
+`timeout` (Optional)::
+  (time) Controls the amount of time to wait until the {dfanalytics-job} starts. 
+  The default value is 20 seconds.
 
 [[ml-start-dfanalytics-example]]
 ==== {api-examples-title}

diff --git a/docs/reference/ml/apis/stop-dfanalytics.asciidoc b/docs/reference/ml/apis/stop-dfanalytics.asciidoc
@@ -8,7 +8,7 @@
 <titleabbrev>Stop {dfanalytics-jobs}</titleabbrev>
 ++++
 
-beta[]
+experimental[]
 
 Stops one or more {dfanalytics-jobs}.
 
@@ -28,13 +28,35 @@ Stops one or more {dfanalytics-jobs}.
 information, see {stack-ov}/security-privileges.html[Security privileges] and 
 {stack-ov}/built-in-roles.html[Built-in roles].
 
+[[ml-stop-dfanalytics-desc]]
+==== {api-description-title}
+
+A {dfanalytics-job} can be started and stopped multiple times throughout its 
+lifecycle.
+
+You can stop multiple {dfanalytics-jobs} in a single API request by using a 
+comma-separated list of {dfanalytics-jobs} or a wildcard expression. You can 
+stop all {dfanalytics-job} by using _all or by specifying * as the 
+<data_frame_analytics_id>.
+
 [[ml-stop-dfanalytics-path-params]]
 ==== {api-path-parms-title}
 
 `<data_frame_analytics_id>` (Required)::
   (string) Identifier for the {dfanalytics-job}. This identifier can contain
   lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It
   must start and end with alphanumeric characters.
+
+`timeout` (Optional)::
+  Controls the amount of time to wait until the {dfanalytics-job} stops. 
+  The default value is 20 seconds.
+
+`force` (Optional)::
+  (boolean) If true, the {dfanalytics-job} is stopped forcefully.
+
+`allow_no_match` (Optional)
+  (boolean) If `false` and the `data_frame_analytics_id` does not match any 
+  {dfanalytics-job} an error will be returned. The default value is `true`.
 
 [[ml-stop-dfanalytics-example]]
 ==== {api-examples-title}