[DOCS] Adds delete forecast API (#33401)

docs/reference/ml/apis/delete-forecast.asciidoc

@@ -0,0 +1,78 @@
+[role="xpack"]
+[testenv="platinum"]
+[[ml-delete-forecast]]
+=== Delete Forecast API
+++++
+<titleabbrev>Delete Forecast</titleabbrev>
+++++
+
+Deletes forecasts from a {ml} job.  
+
+==== Request
+
+`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast` +
+
+`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast/<forecast_id>` +
+
+`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast/_all` 
+
+
+==== Description
+
+By default, forecasts are retained for 14 days. You can specify a different 
+retention period with the `expires_in` parameter in the <<ml-forecast,forecast jobs API>>. The delete forecast API enables you to delete one or more forecasts before they expire.
+
+NOTE: When you delete a job its associated forecasts are deleted. 
+
+For more information, see {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].
+
+
+==== Path Parameters
+
+`job_id` (required)::
+  (string) Identifier for the job.
+
+`forecast_id`::
+  (string) A comma-separated list of forecast identifiers. 
+  If you do not specify this optional parameter or if you specify `_all`, the 
+  API deletes all forecasts from the job. 
+
+==== Request Parameters
+
+`allow_no_forecasts`::
+  (boolean) Specifies whether an error occurs when there are no forecasts. In 
+  particular, if this parameter is set to `false` and there are no forecasts 
+  associated with the job, attempts to delete all forecasts return an error. 
+  The default value is `true`.
+
+`timeout`::
+  (time units) Specifies the period of time to wait for the completion of the 
+  delete operation. When this period of time elapses, the API fails and returns 
+  an error. The default value is `30s`. For more information about time units, 
+  see <<time-units>>.
+
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see {stack-ov}/security-privileges.html[Security Privileges].
+
+==== Examples
+
+The following example deletes all forecasts from the `total-requests` job:
+
+[source,js]
+--------------------------------------------------
+DELETE _xpack/ml/anomaly_detectors/total-requests/_forecast/_all
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:setup:server_metrics_openjob]
+
+If the request does not encounter errors, you receive the following result:
+[source,js]
+----
+{
+  "acknowledged": true
+}
+----
+// NOTCONSOLE

docs/reference/ml/apis/ml-api.asciidoc

@@ -48,7 +48,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>>
+* <<ml-forecast,Forecast job behavior>>, <<ml-delete-forecast,Delete forecasts>>
 
 [float]
 [[ml-api-snapshot-endpoint]]
@@ -85,6 +85,7 @@ include::delete-calendar.asciidoc[]
 include::delete-datafeed.asciidoc[]
 include::delete-calendar-event.asciidoc[]
 include::delete-filter.asciidoc[]
+include::delete-forecast.asciidoc[]
 include::delete-job.asciidoc[]
 include::delete-calendar-job.asciidoc[]
 include::delete-snapshot.asciidoc[]