[DOCS] Added ML forecast API (elastic/x-pack-elasticsearch#2745)

* [DOCS] Added ML forecast API

* [DOCS] Added forecast API to build.gradle

* [DOCS] Added forecast API example

* [DOCS] Fixed forecast API intro

* [DOCS] Addressed feedback on forecast API

* [DOCS] Added duration to forecast API

* [DOCS] Removed end time from forecast API

* [DOCS] Fixed gradle errors for forecast API

Original commit: elastic/x-pack-elasticsearch@db79e3d5bb

docs/build.gradle

@@ -68,6 +68,7 @@ buildRestTests.expectedUnconvertedCandidates = [
         'en/rest-api/ml/delete-datafeed.asciidoc',
         'en/rest-api/ml/delete-snapshot.asciidoc',
         'en/rest-api/ml/flush-job.asciidoc',
+        'en/rest-api/ml/forecast.asciidoc',
         'en/rest-api/ml/get-bucket.asciidoc',
         'en/rest-api/ml/get-overall-buckets.asciidoc',
         'en/rest-api/ml/get-category.asciidoc',

docs/en/ml/api-quickref.asciidoc

@@ -28,6 +28,7 @@ The main {ml} resources can be accessed with a variety of endpoints:
 * {ref}/ml-get-job-stats.html[GET /anomaly_detectors/<job_id>/_stats]: Get job statistics
 * {ref}/ml-update-job.html[POST /anomaly_detectors/<job_id>/_update]: Update certain properties of the job configuration
 * {ref}/ml-flush-job.html[POST anomaly_detectors/<job_id>/_flush]: Force a job to analyze buffered data
+* {ref}/forecast.html[POST anomaly_detectors/<job_id>/_forecast]: Forecast future job behavior
 * {ref}/ml-close-job.html[POST /anomaly_detectors/<job_id>/_close]: Close a job
 * {ref}/ml-delete-job.html[DELETE /anomaly_detectors/<job_id+++>+++]: Delete a job
 

docs/en/rest-api/ml-api.asciidoc

@@ -29,7 +29,7 @@ machine learning APIs and in advanced job configuration options in Kibana.
 * <<ml-flush-job,Flush job>>
 * <<ml-post-data,Post data to job>>
 * <<ml-update-job,Update job>>
-
+* <<ml-forecast,Forecast job behavior>>
 
 [float]
 [[ml-api-snapshot-endpoint]]
@@ -63,6 +63,8 @@ include::ml/delete-job.asciidoc[]
 include::ml/delete-snapshot.asciidoc[]
 //FLUSH
 include::ml/flush-job.asciidoc[]
+//FORECAST
+include::ml/forecast.asciidoc[]
 //GET
 include::ml/get-bucket.asciidoc[]
 include::ml/get-overall-buckets.asciidoc[]

docs/en/rest-api/ml/forecast.asciidoc

@@ -0,0 +1,89 @@
+[role="xpack"]
+[[ml-forecast]]
+=== Forecast Jobs
+
+The forecast jobs API uses historical behavior to predict the future behavior of
+a time series.
+
+==== Request
+
+`POST _xpack/ml/anomaly_detectors/<job_id>/_forecast`
+
+
+==== Description
+
+You can use the API to estimate a time series value at a specific future date.
+For example, you might want to determine how many users you can expect to visit
+your website next Sunday at 0900.
+
+You can also use it to estimate the probability of a time series value occurring
+at a future date. For example, you might want to determine how likely it is that
+your disk utilization will reach 100% before the end of next week.
+
+Each time you call the API, it generates a new forecast and returns a unique ID.
+Existing forecasts for the same job are not overwritten. You can use the forecast
+ID to distinguish between forecasts that you generated at different times.
+
+NOTE: If you use an `over_field_name` property in your job, you cannot create a
+forecast. For more information about this property, see <<ml-job-resource>>.
+
+==== Path Parameters
+
+`job_id`::
+  (string) Identifier for the job.
+
+
+==== Query Parameters
+
+`duration`::
+  (time units) A period of time that indicates how far into the future to
+  forecast. For example, `2w` corresponds to 2 weeks. The forecast starts at the
+  last record that was processed. For more information about time units, see
+  <<time-units>>.
+
+////
+//Not a supported feature:
+`end`::
+  (string) The time that the forecast should end. The string can contain
+  formatted dates, a number representing milliseconds since the epoch, or a
+  number representing seconds since the epoch. It can also contain
+  <<date-math,date math expressions>>. The default value is one day after
+  the last record that was processed.
+
+NOTE: You can specify either the `duration` or `end` parameter; if you specify
+both, an error occurs.
+
+////
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+
+==== Examples
+
+The following example requests a 10 day forecast for the `total-requests` job:
+
+[source,js]
+--------------------------------------------------
+POST _xpack/ml/anomaly_detectors/total-requests/_forecast
+{
+  "duration": "10d"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:todo]
+
+When the forecast is created, you receive the following results:
+[source,js]
+----
+{
+  "acknowledged": true,
+  "forecast_id": 1507824469268
+}
+----
+
+You can subsequently see the forecast in the *Single Metric Viewer* in {kib}
+and in the results that you retrieve by using {ml} APIs such as the
+<<ml-get-bucket,get bucket API>> and <<ml-get-record,get records API>>.