[DOCS] Updates ML APIs to use new API template (#43711)

docs/reference/ml/apis/close-job.asciidoc

@@ -22,6 +22,13 @@ operations, but you can still explore and navigate results.
 
 `POST _ml/anomaly_detectors/_all/_close` +
 
+[[ml-close-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-close-job-desc]]
 ==== {api-description-title}
 
@@ -52,27 +59,21 @@ results the job might have recently produced or might produce in the future.
 [[ml-close-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job. It can be a job identifier, a group name, or
   a wildcard expression.
 
 [[ml-close-job-query-parms]]
 ==== {api-query-parms-title}
 
-`force`::
+`force` (Optional)::
   (boolean) Use to close a failed job, or to forcefully close a job which has not
   responded to its initial close request.
 
-`timeout`::
+`timeout` (Optional)::
   (time units) Controls the time to wait until a job has closed.
   The default value is 30 minutes.
 
-[[ml-close-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-close-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/delete-calendar-event.asciidoc

@@ -13,6 +13,13 @@ Deletes scheduled events from a calendar.
 
 `DELETE _ml/calendars/<calendar_id>/events/<event_id>`
 
+[[ml-delete-calendar-event-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-calendar-event-desc]]
 ==== {api-description-title}
 
@@ -23,19 +30,13 @@ events and delete the calendar, see the
 [[ml-delete-calendar-event-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id`(required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
-`event_id` (required)::
+`<event_id>` (Required)::
   (string) Identifier for the scheduled event. You can obtain this identifier
   by using the <<ml-get-calendar-event,get calendar events API>>.
 
-[[ml-delete-calendar-event-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-delete-calendar-event-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/delete-calendar-job.asciidoc

@@ -13,21 +13,22 @@ Deletes jobs from a calendar.
 
 `DELETE _ml/calendars/<calendar_id>/jobs/<job_id>`
 
+[[ml-delete-calendar-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-calendar-job-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id`(required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
-`job_id` (required)::
-  (string) An identifier for the job. It can be a job identifier, a group name, or a
-           comma-separated list of jobs or groups.
-
-[[ml-delete-calendar-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security privileges].
+`<job_id>` (Required)::
+  (string) An identifier for the job. It can be a job identifier, a group name,
+  or a comma-separated list of jobs or groups.
 
 [[ml-delete-calendar-job-example]]
 ==== {api-examples-title}

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

@@ -13,6 +13,13 @@ Deletes a calendar.
 
 `DELETE _ml/calendars/<calendar_id>`
 
+[[ml-delete-calendar-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-calendar-desc]]
 ==== {api-description-title}
 
@@ -22,15 +29,9 @@ calendar.
 [[ml-delete-calendar-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id` (required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
-[[ml-delete-calendar-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-delete-calendar-example]]
 ==== {api-examples-title}
 

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

@@ -15,29 +15,31 @@ Deletes an existing {dfeed}.
 
 `DELETE _ml/datafeeds/<feed_id>`
 
+[[ml-delete-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-datafeed-desc]]
 ==== {api-description-title}
 
-NOTE: Unless the `force` parameter is used, the {dfeed} must be stopped before it can be deleted.
+NOTE: Unless you use the `force` parameter, you must stop the {dfeed} before you
+can delete it.
 
 [[ml-delete-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id` (required)::
-  (string) Identifier for the {dfeed}
+`<feed_id>` (Required)::
+  (string) Identifier for the {dfeed}.
 
 [[ml-delete-datafeed-query-parms]]
 ==== {api-query-parms-title}
 
-`force`::
-  (boolean) Use to forcefully delete a started {dfeed}; this method is quicker than
-  stopping and deleting the {dfeed}.
-
-[[ml-delete-datafeed-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security privileges].
+`force` (Optional)::
+  (boolean) Use to forcefully delete a started {dfeed}; this method is quicker
+  than stopping and deleting the {dfeed}.
 
 [[ml-delete-datafeed-example]]
 ==== {api-examples-title}

docs/reference/ml/apis/delete-expired-data.asciidoc

@@ -13,6 +13,13 @@ Deletes expired and unused machine learning data.
 
 `DELETE _ml/_delete_expired_data`
 
+[[ml-delete-expired-data-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-expired-data-desc]]
 ==== {api-description-title}
 
@@ -20,14 +27,6 @@ Deletes all job results, model snapshots and forecast data that have exceeded
 their `retention days` period. Machine learning state documents that are not
 associated with any job are also deleted.
 
-[[ml-delete-expired-data-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security Privileges] and
-{stack-ov}/built-in-roles.html[Built-in Roles].
-
 [[ml-delete-expired-data-example]]
 ==== {api-examples-title}
 

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

@@ -13,6 +13,13 @@ Deletes a filter.
 
 `DELETE _ml/filters/<filter_id>`
 
+[[ml-delete-filter-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-filter-desc]]
 ==== {api-description-title}
 
@@ -23,15 +30,9 @@ update or delete the job before you can delete the filter.
 [[ml-delete-filter-path-parms]]
 ==== {api-path-parms-title}
 
-`filter_id` (required)::
+`<filter_id>` (Required)::
   (string) Identifier for the filter.
 
-[[ml-delete-filter-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
-
 [[ml-delete-filter-example]]
 ==== {api-examples-title}
 

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

@@ -17,47 +17,51 @@ Deletes forecasts from a {ml} job.
 
 `DELETE _ml/anomaly_detectors/<job_id>/_forecast/_all`
 
+[[ml-delete-forecast-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-forecast-desc]]
 ==== {api-description-title}
 
 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.
+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. 
+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].
+For more information, see
+{stack-ov}/ml-overview.html#ml-forecasting[Forecasting the future].
 
 [[ml-delete-forecast-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
+`<job_id>` (Required)::
   (string) Identifier for the job.
 
-`forecast_id`::
+`forecast_id` (Optional)::
   (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. 
 
-[[ml-delete-forecast-request-body]]
-==== {api-request-body-title}
+[[ml-delete-forecast-query-parms]]
+==== {api-query-parms-title}
 
-`allow_no_forecasts`::
+`allow_no_forecasts` (Optional)::
   (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`::
+`timeout` (Optional)::
   (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>>.
-  
-[[ml-delete-forecast-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security Privileges].
 
 [[ml-delete-forecast-example]]
 ==== {api-examples-title}

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

@@ -13,6 +13,13 @@ Deletes an existing anomaly detection job.
 
 `DELETE _ml/anomaly_detectors/<job_id>`
 
+[[ml-delete-job-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `manage_ml` or `manage`
+cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-job-desc]]
 ==== {api-description-title}
 
@@ -33,27 +40,20 @@ separated list.
 [[ml-delete-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
+`<job_id>` (Required)::
+  (string) Identifier for the job.
 
 [[ml-delete-job-query-parms]]
 ==== {api-query-parms-title}
 
-`force`::
+`force` (Optional)::
   (boolean) Use to forcefully delete an opened job; this method is quicker than
   closing and deleting the job.
 
-`wait_for_completion`::
+`wait_for_completion` (Optional)::
   (boolean) Specifies whether the request should return immediately or wait
   until the job deletion completes. Defaults to `true`.
 
-[[ml-delete-job-prereqs]]
-==== {api-prereq-title}
-
-If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
-cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-delete-job-example]]
 ==== {api-examples-title}
 

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

@@ -13,6 +13,13 @@ Deletes an existing model snapshot.
 
 `DELETE _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
 
+[[ml-delete-snapshot-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-delete-snapshot-desc]]
 ==== {api-description-title}
 
@@ -23,17 +30,11 @@ the `model_snapshot_id` in the results from the get jobs API.
 [[ml-delete-snapshot-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
-
-`snapshot_id` (required)::
-  (string) Identifier for the model snapshot
-
-[[ml-delete-snapshot-prereqs]]
-==== {api-prereq-title}
+`<job_id>` (Required)::
+  (string) Identifier for the job.
 
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
+`<snapshot_id>` (Required)::
+  (string) Identifier for the model snapshot.
 
 [[ml-delete-snapshot-example]]
 ==== {api-examples-title}

docs/reference/ml/apis/find-file-structure.asciidoc

@@ -16,6 +16,13 @@ suitable to be ingested into {es}.
 
 `POST _ml/find_file_structure`
 
+[[ml-find-file-structure-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml` or
+`monitor` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-find-file-structure-desc]]
 ==== {api-description-title}
 
@@ -51,36 +58,36 @@ chosen.
 [[ml-find-file-structure-query-parms]]
 ==== {api-query-parms-title}
 
-`charset`::
+`charset` (Optional)::
   (string) The file's character set. It must be a character set that is supported
   by the JVM that {es} uses. For example, `UTF-8`, `UTF-16LE`, `windows-1252`, or
   `EUC-JP`. If this parameter is not specified, the structure finder chooses an
   appropriate character set.
 
-`column_names`::
+`column_names` (Optional)::
   (string) If you have set `format` to `delimited`, you can specify the column names
   in a comma-separated list. If this parameter is not specified, the structure
   finder uses the column names from the header row of the file. If the file does
   not have a header role, columns are named "column1", "column2", "column3", etc.
 
-`delimiter`::
+`delimiter` (Optional)::
   (string) If you have set `format` to `delimited`, you can specify the character used
   to delimit the values in each row. Only a single character is supported; the
   delimiter cannot have multiple characters. If this parameter is not specified,
   the structure finder considers the following possibilities: comma, tab,
   semi-colon, and pipe (`|`).
 
-`explain`::
+`explain` (Optional)::
   (boolean) If this parameter is set to `true`, the response includes a field
   named `explanation`, which is an array of strings that indicate how the
   structure finder produced its result. The default value is `false`.
 
-`format`::
+`format` (Optional)::
   (string) The high level structure of the file. Valid values are `ndjson`, `xml`,
   `delimited`, and `semi_structured_text`. If this parameter is not specified,
   the structure finder chooses one.
 
-`grok_pattern`::
+`grok_pattern` (Optional)::
   (string) If you have set `format` to `semi_structured_text`, you can specify a Grok
   pattern that is used to extract fields from every message in the file. The
   name of the timestamp field in the Grok pattern must match what is specified
@@ -88,20 +95,20 @@ chosen.
   name of the timestamp field in the Grok pattern must match "timestamp". If
   `grok_pattern` is not specified, the structure finder creates a Grok pattern.
 
-`has_header_row`::
+`has_header_row` (Optional)::
   (boolean) If you have set `format` to `delimited`, you can use this parameter to
   indicate whether the column names are in the first row of the file. If this
   parameter is not specified, the structure finder guesses based on the similarity of
   the first row of the file to other rows.
 
-`line_merge_size_limit`::
+`line_merge_size_limit` (Optional)::
   (unsigned integer) The maximum number of characters in a message when lines are
   merged to form messages while analyzing semi-structured files. The default
   is 10000. If you have extremely long messages you may need to increase this, but
   be aware that this may lead to very long processing times if the way to group
   lines into messages is misdetected.
 
-`lines_to_sample`::
+`lines_to_sample` (Optional)::
   (unsigned integer) The number of lines to include in the structural analysis,
   starting from the beginning of the file. The minimum is 2; the default
   is 1000. If the value of this parameter is greater than the number of lines in
@@ -117,7 +124,7 @@ efficient to upload a sample file with more variety in the first 1000 lines than
 to request analysis of 100000 lines to achieve some variety.
 --
 
-`quote`::
+`quote` (Optional)::
   (string) If you have set `format` to `delimited`, you can specify the character used
   to quote the values in each row if they contain newlines or the delimiter
   character. Only a single character is supported. If this parameter is not
@@ -125,18 +132,18 @@ to request analysis of 100000 lines to achieve some variety.
   format does not use quoting, a workaround is to set this argument to a
   character that does not appear anywhere in the sample.
 
-`should_trim_fields`::
+`should_trim_fields` (Optional)::
   (boolean) If you have set `format` to `delimited`, you can specify whether values
   between delimiters should have whitespace trimmed from them. If this parameter
   is not specified and the delimiter is pipe (`|`), the default value is `true`.
   Otherwise, the default value is `false`.
 
-`timeout`::
+`timeout` (Optional)::
   (time) Sets the maximum amount of time that the structure analysis make take.
   If the analysis is still running when the timeout expires then it will be
   aborted. The default value is 25 seconds.
 
-`timestamp_field`::
+`timestamp_field` (Optional)::
   (string) The name of the field that contains the primary timestamp of each
   record in the file. In particular, if the file were ingested into an index,
   this is the field that would be used to populate the `@timestamp` field. +
@@ -155,7 +162,7 @@ field (if any) is the primary timestamp field. For structured file formats, it
 is not compulsory to have a timestamp in the file.
 --
 
-`timestamp_format`::
+`timestamp_format` (Optional)::
   (string) The Java time format of the timestamp field in the file. +
 +
 --
@@ -207,13 +214,6 @@ be ingested into {es}. It does not need to be in JSON format and it does not
 need to be UTF-8 encoded. The size is limited to the {es} HTTP receive buffer
 size, which defaults to 100 Mb.
 
-[[ml-find-file-structure-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, or `monitor` cluster privileges to use this API.
-For more information, see {stack-ov}/security-privileges.html[Security Privileges].
-
-
 [[ml-find-file-structure-examples]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/flush-job.asciidoc

@@ -13,6 +13,13 @@ Forces any buffered data to be processed by the job.
 
 `POST _ml/anomaly_detectors/<job_id>/_flush`
 
+[[ml-flush-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-flush-job-desc]]
 ==== {api-description-title}
 
@@ -29,39 +36,33 @@ opened again before analyzing further data.
 [[ml-flush-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-(string) Identifier for the job
+`<job_id>` (Required)::
+(string) Identifier for the job.
 
 [[ml-flush-job-query-parms]]
 ==== {api-query-parms-title}
 
-`advance_time`::
+`advance_time` (Optional)::
   (string) Specifies to advance to a particular time value. Results are
   generated and the model is updated for data from the specified time interval.
 
-`calc_interim`::
+`calc_interim` (Optional)::
   (boolean) If true, calculates the interim results for the most recent bucket
   or all buckets within the latency period.
 
-`end`::
+`end` (Optional)::
   (string) When used in conjunction with `calc_interim`, specifies the range
   of buckets on which to calculate interim results.
 
-`skip_time`::
+`skip_time` (Optional)::
   (string) Specifies to skip to a particular time value. Results are not
   generated and the model is not updated for data from the specified time
   interval.
 
-`start`::
+`start` (Optional)::
   (string) When used in conjunction with `calc_interim`, specifies the range of
   buckets on which to calculate interim results.
 
-[[ml-flush-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
-
 [[ml-flush-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/forecast.asciidoc

@@ -13,10 +13,17 @@ Predicts the future behavior of a time series by using its historical behavior.
 
 `POST _ml/anomaly_detectors/<job_id>/_forecast`
 
+[[ml-forecast-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-forecast-desc]]
 ==== {api-description-title}
 
-See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].
+See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the future].
 
 [NOTE]
 ===============================
@@ -29,30 +36,24 @@ forecast. For more information about this property, see <<ml-job-resource>>.
 [[ml-forecast-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job.
 
 [[ml-forecast-request-body]]
 ==== {api-request-body-title}
 
-`duration`::
+`duration` (Optional)::
   (time units) A period of time that indicates how far into the future to
   forecast. For example, `30d` corresponds to 30 days. The default value is 1
   day. The forecast starts at the last record that was processed. For more
   information about time units, see <<time-units>>.
 
-`expires_in`::
+`expires_in` (Optional)::
   (time units) The period of time that forecast results are retained.
   After a forecast expires, the results are deleted. The default value is 14 days.
   If set to a value of `0`, the forecast is never automatically deleted.
   For more information about time units, see <<time-units>>.
 
-[[ml-forecast-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
-
 [[ml-forecast-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-bucket.asciidoc

@@ -15,6 +15,17 @@ Retrieves job results for one or more buckets.
 
 `GET _ml/anomaly_detectors/<job_id>/results/buckets/<timestamp>`
 
+[[ml-get-bucket-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
+need `read` index privilege on the index that stores the results. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. For more information, see
+{stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[ml-get-bucket-desc]]
 ==== {api-description-title}
 
@@ -24,44 +35,44 @@ bucket.
 [[ml-get-bucket-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job
 
-`timestamp`::
+`<timestamp>` (Optional)::
   (string) The timestamp of a single bucket result.
-  If you do not specify this optional parameter, the API returns information
+  If you do not specify this parameter, the API returns information
   about all buckets.
 
 [[ml-get-bucket-request-body]]
 ==== {api-request-body-title}
 
-`anomaly_score`::
+`anomaly_score` (Optional)::
   (double) Returns buckets with anomaly scores greater or equal than this value.
 
-`desc`::
+`desc` (Optional)::
   (boolean) If true, the buckets are sorted in descending order.
 
-`end`::
+`end` (Optional)::
   (string) Returns buckets with timestamps earlier than this time.
 
-`exclude_interim`::
+`exclude_interim` (Optional)::
   (boolean) If true, the output excludes interim results.
   By default, interim results are included.
 
-`expand`::
+`expand` (Optional)::
   (boolean) If true, the output includes anomaly records.
 
-`page`::
+`page` (Optional)::
 `from`:::
   (integer) Skips the specified number of buckets.
 `size`:::
   (integer) Specifies the maximum number of buckets to obtain.
 
-`sort`::
+`sort` (Optional)::
   (string) Specifies the sort field for the requested buckets.
   By default, the buckets are sorted by the `timestamp` field.
 
-`start`::
+`start` (Optional)::
   (string) Returns buckets with timestamps after this time.
 
 [[ml-get-bucket-results]]
@@ -73,16 +84,6 @@ The API returns the following information:
   (array) An array of bucket objects. For more information, see
   <<ml-results-buckets,Buckets>>.
 
-[[ml-get-bucket-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. You also need `read` index privilege on the index
-that stores the results. The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges] and
-{stack-ov}/built-in-roles.html[Built-in Roles].
-
 [[ml-get-bucket-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-calendar-event.asciidoc

@@ -16,6 +16,13 @@ calendars.
 
 `GET _ml/calendars/_all/events`
 
+[[ml-get-calendar-event-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-get-calendar-event-desc]]
 ==== {api-description-title}
 
@@ -25,22 +32,22 @@ calendars by using `_all`.
 [[ml-get-calendar-event-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id` (required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
 [[ml-get-calendar-event-request-body]]
 ==== {api-request-body-title}
 
-`end`::
+`end` (Optional)::
     (string) Specifies to get events with timestamps earlier than this time.
 
-`from`::
+`from` (Optional)::
     (integer) Skips the specified number of events.
 
-`size`::
+`size` (Optional)::
     (integer) Specifies the maximum number of events to obtain.
 
-`start`::
+`start` (Optional)::
     (string) Specifies to get events with timestamps after this time.
 
 [[ml-get-calendar-event-results]]
@@ -52,13 +59,6 @@ The API returns the following information:
   (array) An array of scheduled event resources.
   For more information, see <<ml-event-resource>>.
 
-[[ml-get-calendar-event-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-calendar-event-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-calendar.asciidoc

@@ -15,6 +15,13 @@ Retrieves configuration information for calendars.
 
 `GET _ml/calendars/_all`
 
+[[ml-get-calendar-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-get-calendar-desc]]
 ==== {api-description-title}
 
@@ -24,17 +31,17 @@ You can get information for a single calendar or for all calendars by using
 [[ml-get-calendar-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id`::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
 [[ml-get-calendar-request-body]]
 ==== {api-request-body-title}
 
-`page`::
+`page` (Optional)::
 `from`:::
     (integer) Skips the specified number of calendars.
 
-`size`:::
+`size` (Optional):::
     (integer) Specifies the maximum number of calendars to obtain.
 
 [[ml-get-calendar-results]]
@@ -46,13 +53,6 @@ The API returns the following information:
   (array) An array of calendar resources.
   For more information, see <<ml-calendar-resource>>.
 
-[[ml-get-calendar-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-calendar-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-category.asciidoc

@@ -15,26 +15,36 @@ Retrieves job results for one or more categories.
 
 `GET _ml/anomaly_detectors/<job_id>/results/categories/<category_id>`
 
+[[ml-get-category-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
+need `read` index privilege on the index that stores the results. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. See {stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[ml-get-category-desc]]
 ==== {api-description-title}
 
 For more information about categories, see
-{stack-ov}/ml-configuring-categories.html[Categorizing Log Messages].
+{stack-ov}/ml-configuring-categories.html[Categorizing log messages].
 
 [[ml-get-category-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job.
 
-`category_id`::
-  (long) Identifier for the category. If you do not specify this optional parameter,
+`<category_id>` (Optional)::
+  (long) Identifier for the category. If you do not specify this parameter,
   the API returns information about all categories in the job.
 
 [[ml-get-category-request-body]]
 ==== {api-request-body-title}
 
-`page`::
+`page` (Optional)::
 `from`:::
   (integer) Skips the specified number of categories.
 `size`:::
@@ -49,16 +59,6 @@ The API returns the following information:
   (array) An array of category objects. For more information, see
   <<ml-results-categories,Categories>>.
 
-[[ml-get-category-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. You also need `read` index privilege on the index
-that stores the results. The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges] and
-{stack-ov}/built-in-roles.html[Built-in Roles].
-
 [[ml-get-category-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-datafeed-stats.asciidoc

@@ -19,7 +19,14 @@ Retrieves usage information for {dfeeds}.
 
 `GET _ml/datafeeds/_stats`  +
 
-`GET _ml/datafeeds/_all/_stats` +
+`GET _ml/datafeeds/_all/_stats` 
+
+[[ml-get-datafeed-stats-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
 
 [[ml-get-datafeed-stats-desc]]
 ==== {api-description-title}
@@ -37,7 +44,7 @@ IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
 [[ml-get-datafeed-stats-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id`::
+`<feed_id>` (Optional)::
   (string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
   wildcard expression. If you do not specify one of these options, the API
   returns statistics for all {dfeeds}.
@@ -51,13 +58,6 @@ The API returns the following information:
   (array) An array of {dfeed} count objects.
   For more information, see <<ml-datafeed-counts>>.
 
-[[ml-get-datafeed-stats-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-datafeed-stats-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-datafeed.asciidoc

@@ -19,7 +19,14 @@ Retrieves configuration information for {dfeeds}.
 
 `GET _ml/datafeeds/` +
 
-`GET _ml/datafeeds/_all` +
+`GET _ml/datafeeds/_all` 
+
+[[ml-get-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
 
 [[ml-get-datafeed-desc]]
 ==== {api-description-title}
@@ -34,7 +41,7 @@ IMPORTANT: This API returns a maximum of 10,000 {dfeeds}.
 [[ml-get-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id`::
+`<feed_id>` (Optional)::
   (string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
   wildcard expression. If you do not specify one of these options, the API
   returns information about all {dfeeds}.
@@ -48,13 +55,6 @@ The API returns the following information:
   (array) An array of {dfeed} objects.
   For more information, see <<ml-datafeed-resource>>.
 
-[[ml-get-datafeed-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-datafeed-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-filter.asciidoc

@@ -15,6 +15,13 @@ Retrieves filters.
 
 `GET _ml/filters/`
 
+[[ml-get-filter-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-get-filter-desc]]
 ==== {api-description-title}
 
@@ -24,16 +31,16 @@ You can get a single filter or all filters. For more information, see
 [[ml-get-filter-path-parms]]
 ==== {api-path-parms-title}
 
-`filter_id`::
+`<filter_id>` (Optional)::
   (string) Identifier for the filter.
 
 [[ml-get-filter-query-parms]]
 ==== {api-query-parms-title}
 
-`from`:::
+`from` (Optional):::
     (integer) Skips the specified number of filters.
 
-`size`:::
+`size` (Optional):::
     (integer) Specifies the maximum number of filters to obtain.
 
 [[ml-get-filter-results]]
@@ -45,13 +52,6 @@ The API returns the following information:
   (array) An array of filter resources.
   For more information, see <<ml-filter-resource>>.
 
-[[ml-get-filter-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-filter-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-influencer.asciidoc

@@ -13,39 +13,49 @@ Retrieves job results for one or more influencers.
 
 `GET _ml/anomaly_detectors/<job_id>/results/influencers`
 
+[[ml-get-influencer-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
+need `read` index privilege on the index that stores the results. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. See {stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[ml-get-influencer-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job.
 
 [[ml-get-influencer-request-body]]
 ==== {api-request-body-title}
 
-`desc`::
+`desc` (Optional)::
   (boolean) If true, the results are sorted in descending order.
 
-`end`::
+`end` (Optional)::
   (string) Returns influencers with timestamps earlier than this time.
 
-`exclude_interim`::
+`exclude_interim` (Optional)::
   (boolean) If true, the output excludes interim results.
   By default, interim results are included.
 
-`influencer_score`::
+`influencer_score` (Optional)::
   (double) Returns influencers with anomaly scores greater or equal than this value.
 
-`page`::
+`page` (Optional)::
 `from`:::
     (integer) Skips the specified number of influencers.
 `size`:::
   (integer) Specifies the maximum number of influencers to obtain.
 
-`sort`::
+`sort` (Optional)::
   (string) Specifies the sort field for the requested influencers.
   By default the influencers are sorted by the `influencer_score` value.
 
-`start`::
+`start` (Optional)::
   (string) Returns influencers with timestamps after this time.
 
 [[ml-get-influencer-results]]
@@ -57,16 +67,6 @@ The API returns the following information:
   (array) An array of influencer objects.
   For more information, see <<ml-results-influencers,Influencers>>.
 
-[[ml-get-influencer-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. You also need `read` index privilege on the index
-that stores the results. The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges] and
-{stack-ov}/built-in-roles.html[Built-in Roles].
-
 [[ml-get-influencer-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-job-stats.asciidoc

@@ -17,7 +17,14 @@ Retrieves usage information for jobs.
 
 `GET _ml/anomaly_detectors/_stats` +
 
-`GET _ml/anomaly_detectors/_all/_stats` +
+`GET _ml/anomaly_detectors/_all/_stats` 
+
+[[ml-get-job-stats-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
 
 [[ml-get-job-stats-desc]]
 ==== {api-description-title}
@@ -32,7 +39,7 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 [[ml-get-job-stats-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Optional)::
   (string) An identifier for the job. It can be a job identifier, a group name,
   or a wildcard expression. If you do not specify one of these options, the API
   returns statistics for all jobs.
@@ -46,13 +53,6 @@ The API returns the following information:
   (array) An array of job statistics objects.
   For more information, see <<ml-jobstats,Job Statistics>>.
 
-[[ml-get-job-stats-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-job-stats-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-job.asciidoc

@@ -19,6 +19,13 @@ Retrieves configuration information for jobs.
 
 `GET _ml/anomaly_detectors/_all`
 
+[[ml-get-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-get-job-desc]]
 ==== {api-description-title}
 
@@ -32,7 +39,7 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 [[ml-get-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id> (Optional)`::
   (string) Identifier for the job. It can be a job identifier, a group name,
   or a wildcard expression. If you do not specify one of these options, the API
   returns information for all jobs.
@@ -46,13 +53,6 @@ The API returns the following information:
   (array) An array of job resources.
   For more information, see <<ml-job-resource,Job Resources>>.
 
-[[ml-get-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 [[ml-get-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-ml-info.asciidoc

@@ -15,6 +15,15 @@ Returns defaults and limits used by machine learning.
 
 `GET _ml/info`
 
+[[get-ml-info-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. See {stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[get-ml-info-desc]]
 ==== {api-description-title}
 
@@ -23,15 +32,6 @@ understand machine learning configurations where some options are not specified,
 meaning that the defaults should be used.  This endpoint may be used to find out
 what those defaults are.
 
-[[get-ml-info-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API.  The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security privileges] and
-{stack-ov}/built-in-roles.html[Built-in roles].
-
 [[get-ml-info-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-overall-buckets.asciidoc

@@ -18,6 +18,16 @@ bucket results of multiple jobs.
 
 `GET _ml/anomaly_detectors/_all/results/overall_buckets`
 
+[[ml-get-overall-buckets-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
+need `read` index privilege on the index that stores the results. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. See {stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[ml-get-overall-buckets-desc]]
 ==== {api-description-title}
 
@@ -46,37 +56,38 @@ overall buckets with a span equal to the largest job's `bucket_span`.
 [[ml-get-overall-buckets-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job. It can be a job identifier, a group name, a
   comma-separated list of jobs or groups, or a wildcard expression.
 
 [[ml-get-overall-buckets-request-body]]
 ==== {api-request-body-title}
 
-`allow_no_jobs`::
+`allow_no_jobs` (Optional)::
   (boolean) If `false` and the `job_id` does not match any job an error will
   be returned. The default value is `true`.
 
-`bucket_span`::
+`bucket_span` (Optional)::
   (string) The span of the overall buckets. Must be greater or equal
   to the largest job's `bucket_span`. Defaults to the largest job's `bucket_span`.
 
-`end`::
+`end` (Optional)::
   (string) Returns overall buckets with timestamps earlier than this time.
 
-`exclude_interim`::
+`exclude_interim` (Optional)::
   (boolean) If `true`, the output excludes interim overall buckets.
   Overall buckets are interim if any of the job buckets within
   the overall bucket interval are interim.
   By default, interim results are included.
 
-`overall_score`::
-  (double) Returns overall buckets with overall scores greater or equal than this value.
+`overall_score` (Optional)::
+  (double) Returns overall buckets with overall scores greater or equal than
+  this value.
 
-`start`::
+`start` (Optional)::
   (string) Returns overall buckets with timestamps after this time.
 
-`top_n`::
+`top_n` (Optional)::
   (integer) The number of top job bucket scores to be used in the
   `overall_score` calculation. The default value is `1`.
 
@@ -89,16 +100,6 @@ The API returns the following information:
   (array) An array of overall bucket objects. For more information, see
   <<ml-results-overall-buckets,Overall Buckets>>.
 
-[[ml-get-overall-buckets-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. You also need `read` index privilege on the index
-that stores the results. The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges] and
-{stack-ov}/built-in-roles.html[Built-in Roles].
-
 [[ml-get-overall-buckets-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-record.asciidoc

@@ -13,39 +13,49 @@ Retrieves anomaly records for a job.
 
 `GET _ml/anomaly_detectors/<job_id>/results/records`
 
+[[ml-get-record-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
+need `read` index privilege on the index that stores the results. The
+`machine_learning_admin` and `machine_learning_user` roles provide these
+privileges. See {stack-ov}/security-privileges.html[Security privileges] and
+{stack-ov}/built-in-roles.html[Built-in roles].
+
 [[ml-get-record-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`job_id` (Required)::
   (string) Identifier for the job.
 
 [[ml-get-record-request-body]]
 ==== {api-request-body-title}
 
-`desc`::
+`desc` (Optional)::
   (boolean) If true, the results are sorted in descending order.
 
-`end`::
+`end` (Optional)::
   (string) Returns records with timestamps earlier than this time.
 
-`exclude_interim`::
+`exclude_interim` (Optional)::
   (boolean) If true, the output excludes interim results.
   By default, interim results are included.
 
-`page`::
+`page` (Optional)::
 `from`:::
   (integer) Skips the specified number of records.
 `size`:::
   (integer) Specifies the maximum number of records to obtain.
 
-`record_score`::
+`record_score` (Optional)::
   (double) Returns records with anomaly scores greater or equal than this value.
 
-`sort`::
+`sort` (Optional)::
   (string) Specifies the sort field for the requested records.
   By default, the records are sorted by the `anomaly_score` value.
 
-`start`::
+`start` (Optional)::
   (string) Returns records with timestamps after this time.
 
 [[ml-get-record-results]]
@@ -57,16 +67,6 @@ The API returns the following information:
   (array) An array of record objects. For more information, see
   <<ml-results-records,Records>>.
 
-[[ml-get-record-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. You also need `read` index privilege on the index
-that stores the results. The `machine_learning_admin` and `machine_learning_user`
-roles provide these privileges. For more information, see
-{stack-ov}/security-privileges.html[Security privileges] and
-{stack-ov}/built-in-roles.html[Built-in roles].
-
 [[ml-get-record-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/get-snapshot.asciidoc

@@ -15,36 +15,43 @@ Retrieves information about model snapshots.
 
 `GET _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
 
+[[ml-get-snapshot-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `monitor_ml`,
+`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-get-snapshot-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id`::
+`<job_id>` (Required)::
   (string) Identifier for the job.
 
-`snapshot_id`::
+`<snapshot_id>` (Optional)::
   (string) Identifier for the model snapshot. If you do not specify this
   optional parameter, the API returns information about all model snapshots.
 
 [[ml-get-snapshot-request-body]]
 ==== {api-request-body-title}
 
-`desc`::
+`desc` (Optional)::
   (boolean) If true, the results are sorted in descending order.
 
-`end`::
+`end` (Optional)::
   (date) Returns snapshots with timestamps earlier than this time.
 
-`from`::
+`from` (Optional)::
   (integer) Skips the specified number of snapshots.
 
-`size`::
+`size` (Optional)::
   (integer) Specifies the maximum number of snapshots to obtain.
 
-`sort`::
+`sort` (Optional)::
   (string) Specifies the sort field for the requested snapshots.
   By default, the snapshots are sorted by their timestamp.
 
-`start`::
+`start` (Optional)::
   (string) Returns snapshots with timestamps after this time.
 
 [[ml-get-snapshot-results]]
@@ -56,13 +63,6 @@ The API returns the following information:
   (array) An array of model snapshot objects. For more information, see
   <<ml-snapshot-resource,Model Snapshots>>.
 
-[[ml-get-snapshot-prereqs]]
-==== {api-prereq-title}
-
-You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-get-snapshot-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/open-job.asciidoc

@@ -15,34 +15,35 @@ A job can be opened and closed multiple times throughout its lifecycle.
 
 `POST _ml/anomaly_detectors/{job_id}/_open`
 
+[[ml-open-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-open-job-desc]]
 ==== {api-description-title}
 
 When you open a new job, it starts with an empty model.
 
-When you open an existing job, the most recent model state is automatically loaded.
-The job is ready to resume its analysis from where it left off, once new data is received.
+When you open an existing job, the most recent model state is automatically
+loaded. The job is ready to resume its analysis from where it left off, once new
+data is received.
 
 [[ml-open-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-(string) Identifier for the job
+`<job_id>` (Required)::
+  (string) Identifier for the job
 
 [[ml-open-job-request-body]]
 ==== {api-request-body-title}
 
-`timeout`::
+`timeout` (Optional)::
   (time) Controls the time to wait until a job has opened.
   The default value is 30 minutes.
 
-[[ml-open-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-open-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/post-calendar-event.asciidoc

@@ -13,6 +13,13 @@ Posts scheduled events in a calendar.
 
 `POST _ml/calendars/<calendar_id>/events`
 
+[[ml-post-calendar-event-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-post-calendar-event-desc]]
 ==== {api-description-title}
 
@@ -22,23 +29,16 @@ of which must have a start time, end time, and description.
 [[ml-post-calendar-event-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id` (required)::
+`<calendar_id>` (Required)::
 		(string) Identifier for the calendar.
 
 [[ml-post-calendar-event-request-body]]
 ==== {api-request-body-title}
 
-`events`::
-  (array) A list of one of more scheduled events. The event's start and end times
-  may be specified as integer milliseconds since the epoch or as a string in ISO 8601
-  format. See <<ml-event-resource>>.
-
-[[ml-post-calendar-event-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
+`events` (Required)::
+  (array) A list of one of more scheduled events. The event's start and end
+	times may be specified as integer milliseconds since the epoch or as a string
+	in ISO 8601 format. See <<ml-event-resource>>.
 
 [[ml-post-calendar-event-example]]
 ==== {api-examples-title}

docs/reference/ml/apis/post-data.asciidoc

@@ -13,6 +13,13 @@ Sends data to an anomaly detection job for analysis.
 
 `POST _ml/anomaly_detectors/<job_id>/_data`
 
+[[ml-post-data-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-post-data-desc]]
 ==== {api-description-title}
 
@@ -45,17 +52,17 @@ or a comma-separated list.
 [[ml-post-data-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-		(string) Identifier for the job
+`<job_id>` (Required)::
+		(string) Identifier for the job.
 
 [[ml-post-data-query-parms]]
 ==== {api-query-parms-title}
 
-`reset_start`::
-		(string) Specifies the start of the bucket resetting range
+`reset_start` (Optional)::
+		(string) Specifies the start of the bucket resetting range.
 
-`reset_end`::
-		(string) Specifies the end of the bucket resetting range
+`reset_end` (Optional)::
+		(string) Specifies the end of the bucket resetting range.
 
 [[ml-post-data-request-body]]
 ==== {api-request-body-title}
@@ -63,17 +70,11 @@ or a comma-separated list.
 A sequence of one or more JSON documents containing the data to be analyzed.
 Only whitespace characters are permitted in between the documents.
 
-[[ml-post-data-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-post-data-example]]
 ==== {api-examples-title}
 
-The following example posts data from the it_ops_new_kpi.json file to the `it_ops_new_kpi` job:
+The following example posts data from the `it_ops_new_kpi.json` file to the
+`it_ops_new_kpi` job:
 
 [source,js]
 --------------------------------------------------
@@ -82,8 +83,8 @@ $ curl -s -H "Content-type: application/json"
 --data-binary @it_ops_new_kpi.json
 --------------------------------------------------
 
-When the data is sent, you receive information about the operational progress of the job.
-For example:
+When the data is sent, you receive information about the operational progress of
+the job. For example:
 
 [source,js]
 ----

docs/reference/ml/apis/preview-datafeed.asciidoc

@@ -15,6 +15,13 @@ Previews a {dfeed}.
 
 `GET _ml/datafeeds/<datafeed_id>/_preview`
 
+[[ml-preview-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `monitor_ml`, `monitor`,
+`manage_ml`, or `manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-preview-datafeed-desc]]
 ==== {api-description-title}
 
@@ -22,30 +29,19 @@ The preview {dfeeds} API returns the first "page" of results from the `search`
 that is created by using the current {dfeed} settings. This preview shows the
 structure of the data that will be passed to the anomaly detection engine.
 
+IMPORTANT: When {es} {security-features} are enabled, the {dfeed} query is
+previewed using the credentials of the user calling the preview {dfeed} API.
+When the {dfeed} is started it runs the query using the roles of the last user
+to create or update it.  If the two sets of roles differ then the preview may
+not accurately reflect what the {dfeed} will return when started. To avoid
+such problems, the same user that creates/updates the {dfeed} should preview
+it to ensure it is returning the expected data.
+
 [[ml-preview-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`datafeed_id` (required)::
-  (string) Identifier for the {dfeed}
-
-[[ml-preview-datafeed-prereqs]]
-==== {api-prereq-title}
-
-If {es} {security-features} are enabled, you must have `monitor_ml`, `monitor`,
-`manage_ml`, or `manage` cluster privileges to use this API. For more
-information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
-[[ml-preview-datafeed-security]]
-==== Security Integration
-
-When {es} {security-features} are enabled, the {dfeed} query is previewed using
-the credentials of the user calling the preview {dfeed} API.  When the {dfeed}
-is started it runs the query using the roles of the last user to
-create or update it.  If the two sets of roles differ then the preview may
-not accurately reflect what the {dfeed} will return when started.  To avoid
-such problems, the same user that creates/updates the {dfeed} should preview
-it to ensure it is returning the expected data.
+`<datafeed_id>` (Required)::
+  (string) Identifier for the {dfeed}.
 
 [[ml-preview-datafeed-example]]
 ==== {api-examples-title}

docs/reference/ml/apis/put-calendar-job.asciidoc

@@ -13,22 +13,22 @@ Adds a job to a calendar.
 
 `PUT _ml/calendars/<calendar_id>/jobs/<job_id>`
 
+[[ml-put-calendar-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-put-calendar-job-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id` (required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
-`job_id` (required)::
-  (string) An identifier for the job. It can be a job identifier, a group name, or a
-           comma-separated list of jobs or groups.
-
-[[ml-put-calendar-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
+`<job_id>` (Required)::
+  (string) An identifier for the job. It can be a job identifier, a group name,
+  or a comma-separated list of jobs or groups.
 
 [[ml-put-calendar-job-example]]
 ==== {api-examples-title}

docs/reference/ml/apis/put-calendar.asciidoc

@@ -13,6 +13,13 @@ Instantiates a calendar.
 
 `PUT _ml/calendars/<calendar_id>`
 
+[[ml-put-calendar-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-put-calendar-desc]]
 ==== {api-description-title}
 
@@ -22,22 +29,15 @@ For more information, see
 [[ml-put-calendar-path-parms]]
 ==== {api-path-parms-title}
 
-`calendar_id` (required)::
+`<calendar_id>` (Required)::
   (string) Identifier for the calendar.
 
 [[ml-put-calendar-request-body]]
 ==== {api-request-body-title}
 
-`description`::
+`description` (Optional)::
   (string) A description of the calendar.
 
-[[ml-put-calendar-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-put-calendar-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/put-datafeed.asciidoc

@@ -15,21 +15,34 @@ Instantiates a {dfeed}.
 
 `PUT _ml/datafeeds/<feed_id>`
 
+[[ml-put-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `manage_ml` or `manage`
+cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-put-datafeed-desc]]
 ==== {api-description-title}
 
 You must create a job before you create a {dfeed}.  You can associate only one
 {dfeed} to each job.
 
-IMPORTANT:  You must use {kib} or this API to create a {dfeed}. Do not put a {dfeed}
-            directly to the `.ml-config` index using the Elasticsearch index API.
-            If {es} {security-features} are enabled, do not give users `write`
-            privileges on the `.ml-config` index.
+[IMPORTANT]
+====
+* You must use {kib} or this API to create a {dfeed}. Do not put a
+{dfeed} directly to the `.ml-config` index using the {es} index API. If {es}
+{security-features} are enabled, do not give users `write` privileges on the
+`.ml-config` index.
+* When {es} {security-features} are enabled, your {dfeed} remembers which roles
+the user who created it had at the time of creation and runs the query using
+those same roles.
+====
 
 [[ml-put-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id` (required)::
+`<feed_id>` (Required)::
   (string) A numerical character string that uniquely identifies the {dfeed}.
   This identifier can contain lowercase alphanumeric characters (a-z and 0-9),
   hyphens, and underscores. It must start and end with alphanumeric characters.
@@ -37,73 +50,58 @@ IMPORTANT:  You must use {kib} or this API to create a {dfeed}. Do not put a {df
 [[ml-put-datafeed-request-body]]
 ==== {api-request-body-title}
 
-`aggregations`::
+`aggregations` (Optional)::
   (object) If set, the {dfeed} performs aggregation searches.
   For more information, see <<ml-datafeed-resource>>.
 
-`chunking_config`::
+`chunking_config` (Optional)::
   (object) Specifies how data searches are split into time chunks.
   See <<ml-datafeed-chunking-config>>.
 
-`delayed_data_check_config`::
+`delayed_data_check_config` (Optional)::
   (object) Specifies whether the data feed checks for missing data and 
   the size of the window. See
   <<ml-datafeed-delayed-data-check-config>>.
 
-`frequency`::
+`frequency` (Optional)::
   (time units) The interval at which scheduled queries are made while the {dfeed}
   runs in real time. The default value is either the bucket span for short
   bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
   span. For example: `150s`.
 
-`indices` (required)::
+`indices` (Required)::
   (array) An array of index names. Wildcards are supported. For example:
   `["it_ops_metrics", "server*"]`.
 
-`job_id` (required)::
+`job_id` (Required)::
  (string) A numerical character string that uniquely identifies the job.
 
-`query`::
+`query` (Optional)::
   (object) The {es} query domain-specific language (DSL). This value
   corresponds to the query object in an {es} search POST body. All the
   options that are supported by {Es} can be used, as this object is
   passed verbatim to {es}. By default, this property has the following
   value: `{"match_all": {"boost": 1}}`.
 
-`query_delay`::
+`query_delay` (Optional)::
   (time units) The number of seconds behind real time that data is queried. For
   example, if data from 10:04 a.m. might not be searchable in {es} until
   10:06 a.m., set this property to 120 seconds. The default value is `60s`.
 
-`script_fields`::
+`script_fields` (Optional)::
   (object) Specifies scripts that evaluate custom expressions and returns
   script fields to the {dfeed}.
   The <<ml-detectorconfig,detector configuration objects>> in a job can contain
-  functions that use these script fields.
-  For more information,
+  functions that use these script fields. For more information,
   see {ref}/search-request-script-fields.html[Script Fields].
 
-`scroll_size`::
+`scroll_size` (Optional)::
   (unsigned integer) The `size` parameter that is used in {es} searches.
   The default value is `1000`.
 
 For more information about these properties,
 see <<ml-datafeed-resource>>.
 
-[[ml-put-datafeed-prereqs]]
-==== {api-prereq-title}
-
-If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
-cluster privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
-[[ml-put-datafeed-security]]
-==== Security integration
-
-When {es} {security-features} are enabled, your {dfeed} remembers which roles the
-user who created it had at the time of creation and runs the query using those
-same roles.
-
 [[ml-put-datafeed-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/put-filter.asciidoc

@@ -13,6 +13,13 @@ Instantiates a filter.
 
 `PUT _ml/filters/<filter_id>`
 
+[[ml-put-filter-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-put-filter-desc]]
 ==== {api-description-title}
 
@@ -23,28 +30,21 @@ the `custom_rules` property of <<ml-detectorconfig,detector configuration object
 [[ml-put-filter-path-parms]]
 ==== {api-path-parms-title}
 
-`filter_id` (required)::
+`<filter_id>` (Required)::
   (string) Identifier for the filter.
 
 [[ml-put-filter-request-body]]
 ==== {api-request-body-title}
 
-`description`::
+`description` (Optional)::
   (string) A description of the filter.
   
-`items`::
+`items` (Required)::
   (array of strings) The items of the filter.
   A wildcard `*` can be used at the beginning
   or the end of an item. Up to 10000 items
   are allowed in each filter.
 
-[[ml-put-filter-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-put-filter-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/put-job.asciidoc

@@ -13,6 +13,13 @@ Instantiates a job.
 
 `PUT _ml/anomaly_detectors/<job_id>`
 
+[[ml-put-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-put-job-desc]]
 ==== {api-description-title}
 
@@ -24,7 +31,7 @@ IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
 [[ml-put-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
+`<job_id>` (Required)::
   (string) Identifier for the job. This identifier can contain lowercase
   alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must
   start and end with alphanumeric characters.
@@ -32,61 +39,54 @@ IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
 [[ml-put-job-request-body]]
 ==== {api-request-body-title}
 
-`analysis_config`::
+`analysis_config` (Required)::
   (object) The analysis configuration, which specifies how to analyze the data.
   See <<ml-analysisconfig, analysis configuration objects>>.
 
-`analysis_limits`::
+`analysis_limits` (Optional)::
   (object) Specifies runtime limits for the job. See
   <<ml-apilimits,analysis limits>>.
 
-`background_persist_interval`::
+`background_persist_interval` (Optional)::
   (time units) Advanced configuration option. The time between each periodic
   persistence of the model. See <<ml-job-resource>>.
 
-`custom_settings`::
+`custom_settings` (Optional)::
   (object) Advanced configuration option. Contains custom meta data about the
   job. See <<ml-job-resource>>.
 
-`data_description` (required)::
+`data_description` (Required)::
   (object) Describes the format of the input data. This object is required, but
   it can be empty (`{}`). See <<ml-datadescription,data description objects>>.
 
-`description`::
+`description` (Optional)::
   (string) A description of the job.
 
-`groups`::
+`groups` (Optional)::
   (array of strings) A list of job groups. See <<ml-job-resource>>.
 
-`model_plot_config`::
+`model_plot_config` (Optional)::
   (object) Advanced configuration option. Specifies to store model information
   along with the results. This adds overhead to the performance of the system
   and is not feasible for jobs with many entities, see <<ml-apimodelplotconfig>>.
 
-`model_snapshot_retention_days`::
+`model_snapshot_retention_days` (Optional)::
   (long) The time in days that model snapshots are retained for the job.
   Older snapshots are deleted. The default value is `1`, which means snapshots
   are retained for one day (twenty-four hours). 
 
-`renormalization_window_days`::
+`renormalization_window_days` (Optional)::
   (long) Advanced configuration option. The period over which adjustments to the
   score are applied, as new data is seen. See <<ml-job-resource>>.
 
-`results_index_name`::
+`results_index_name` (Optional)::
   (string) A text string that affects the name of the {ml} results index. The 
   default value is `shared`, which generates an index named `.ml-anomalies-shared`. 
 
-`results_retention_days`::
+`results_retention_days` (Optional)::
   (long) Advanced configuration option. The number of days for which job results
   are retained. See <<ml-job-resource>>.
 
-[[ml-put-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-put-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/revert-snapshot.asciidoc

@@ -13,6 +13,13 @@ Reverts to a specific snapshot.
 
 `POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_revert`
 
+[[ml-revert-snapshot-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-revert-snapshot-desc]]
 ==== {api-description-title}
 
@@ -29,16 +36,16 @@ IMPORTANT: Before you revert to a saved snapshot, you must close the job.
 [[ml-revert-snapshot-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
+`<job_id>` (Required)::
+  (string) Identifier for the job.
 
-`snapshot_id` (required)::
-  (string) Identifier for the model snapshot
+`<snapshot_id>` (Required)::
+  (string) Identifier for the model snapshot.
 
 [[ml-revert-snapshot-request-body]]
 ==== {api-request-body-title}
 
-`delete_intervening_results`::
+`delete_intervening_results` (Optional)::
   (boolean) If true, deletes the results in the time period between the
   latest results and the time of the reverted snapshot. It also resets the
   model to accept records for this time period. The default value is false.
@@ -47,13 +54,6 @@ NOTE: If you choose not to delete intervening results when reverting a snapshot,
 the job will not accept input data that is older than the current time.
 If you want to resend data, then delete the intervening results.
 
-[[ml-revert-snapshot-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-revert-snapshot-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/set-upgrade-mode.asciidoc

@@ -26,6 +26,13 @@ POST /_ml/set_upgrade_mode?enabled=false&timeout=10m
 
 `POST _ml/set_upgrade_mode`
 
+[[ml-set-upgrade-mode-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-set-upgrade-mode-desc]]
 ==== {api-description-title}
 
@@ -54,20 +61,13 @@ IMPORTANT:  No new {ml} jobs can be opened while the `upgrade_mode` setting is
 [[ml-set-upgrade-mode-query-parms]]
 ==== {api-query-parms-title}
 
-`enabled`::
+`enabled` (Optional)::
   (boolean) When `true`, this enables `upgrade_mode`. Defaults to `false`
 
-`timeout`::
+`timeout` (Optional)::
   (time) The time to wait for the request to be completed.
   The default value is 30 seconds.
 
-[[ml-set-upgrade-mode-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-set-upgrade-mode-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/start-datafeed.asciidoc

@@ -17,6 +17,13 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
 
 `POST _ml/datafeeds/<feed_id>/_start`
 
+[[ml-start-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `manage_ml` or `manage`
+cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-start-datafeed-desc]]
 ==== {api-description-title}
 
@@ -58,41 +65,31 @@ If you specify a `start` value that is earlier than the timestamp of the latest
 processed record, the {dfeed} continues from 1 millisecond after the timestamp
 of the latest processed record.
 
+IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
+which roles the last user to create or update it had at the time of
+creation/update and runs the query using those same roles.
+
 [[ml-start-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id` (required)::
-(string) Identifier for the {dfeed}
+`<feed_id>` (Required)::
+  (string) Identifier for the {dfeed}.
 
 [[ml-start-datafeed-request-body]]
 ==== {api-request-body-title}
 
-`end`::
+`end` (Optional)::
   (string) The time that the {dfeed} should end. This value is exclusive.
   The default value is an empty string.
 
-`start`::
+`start` (Optional)::
   (string) The time that the {dfeed} should begin. This value is inclusive.
   The default value is an empty string.
 
-`timeout`::
+`timeout` (Optional)::
   (time) Controls the amount of time to wait until a {dfeed} starts.
   The default value is 20 seconds.
 
-[[ml-start-datafeed-prereqs]]
-==== {api-prereq-title}
-
-If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
-cluster privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
-[[ml-start-datafeed-security]]
-==== Security integration
-
-When {es} {security-features} are enabled, your {dfeed} remembers which roles the
-last user to create or update it had at the time of creation/update and runs the
-query using those same roles.
-
 [[ml-start-datafeed-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/stop-datafeed.asciidoc

@@ -10,9 +10,6 @@
 
 Stops one or more {dfeeds}.
 
-A {dfeed} that is stopped ceases to retrieve data from {es}.
-A {dfeed} can be started and stopped multiple times throughout its lifecycle.
-
 [[ml-stop-datafeed-request]]
 ==== {api-request-title}
 
@@ -22,9 +19,19 @@ A {dfeed} can be started and stopped multiple times throughout its lifecycle.
 
 `POST _ml/datafeeds/_all/_stop`
 
+[[ml-stop-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-stop-datafeed-desc]]
 ==== {api-description-title}
 
+A {dfeed} that is stopped ceases to retrieve data from {es}.
+A {dfeed} can be started and stopped multiple times throughout its lifecycle.
+
 You can stop multiple {dfeeds} in a single API request by using a
 comma-separated list of {dfeeds} or a wildcard expression. You can close all
 {dfeeds} by using `_all` or by specifying `*` as the `<feed_id>`.
@@ -32,27 +39,20 @@ comma-separated list of {dfeeds} or a wildcard expression. You can close all
 [[ml-stop-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id`::
+`<feed_id>` (Required)::
   (string) Identifier for the {dfeed}. It can be a {dfeed} identifier or a
   wildcard expression.
 
 [[ml-stop-datafeed-request-body]]
 ==== {api-request-body-title}
 
-`force`::
+`force` (Optional)::
   (boolean) If true, the {dfeed} is stopped forcefully.
 
-`timeout`::
+`timeout` (Optional)::
   (time) Controls the amount of time to wait until a {dfeed} stops.
   The default value is 20 seconds.
 
-[[ml-stop-datafeed-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-stop-datafeed-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/update-datafeed.asciidoc

@@ -15,61 +15,72 @@ Updates certain properties of a {dfeed}.
 
 `POST _ml/datafeeds/<feed_id>/_update`
 
+[[ml-update-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
+cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-update-datafeed-desc]]
 ==== {api-description-title}
 
-NOTE: If you update the `delayed_data_check_config` property, you must stop and
+If you update the `delayed_data_check_config` property, you must stop and
 start the {dfeed} for the change to be applied.
 
+IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
+which roles the user who updated it had at the time of update and runs the query
+using those same roles.
+
 [[ml-update-datafeed-path-parms]]
 ==== {api-path-parms-title}
 
-`feed_id` (required)::
-  (string) Identifier for the {dfeed}
+`<feed_id>` (Required)::
+  (string) Identifier for the {dfeed}.
 
 [[ml-update-datafeed-request-body]]
 ==== {api-request-body-title}
 
 The following properties can be updated after the {dfeed} is created:
 
-`aggregations`::
+`aggregations` (Optional)::
   (object) If set, the {dfeed} performs aggregation searches.
   For more information, see <<ml-datafeed-resource>>.
 
-`chunking_config`::
+`chunking_config` (Optional)::
   (object) Specifies how data searches are split into time chunks.
   See <<ml-datafeed-chunking-config>>.
   
-`delayed_data_check_config`::
+`delayed_data_check_config` (Optional)::
   (object) Specifies whether the data feed checks for missing data and 
   the size of the window. See <<ml-datafeed-delayed-data-check-config>>.  
 
-`frequency`::
+`frequency` (Optional)::
   (time units) The interval at which scheduled queries are made while the
   {dfeed} runs in real time. The default value is either the bucket span for short
   bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
   span. For example: `150s`.
 
-`indices`::
+`indices` (Optional)::
   (array) An array of index names. Wildcards are supported. For example:
   `["it_ops_metrics", "server*"]`.
 
-`job_id`::
+`job_id` (Optional)::
  (string) A numerical character string that uniquely identifies the job.
 
-`query`::
+`query` (Optional)::
   (object) The {es} query domain-specific language (DSL). This value
   corresponds to the query object in an {es} search POST body. All the
   options that are supported by {es} can be used, as this object is
   passed verbatim to {es}. By default, this property has the following
   value: `{"match_all": {"boost": 1}}`.
 
-`query_delay`::
+`query_delay` (Optional)::
   (time units) The number of seconds behind real-time that data is queried. For
   example, if data from 10:04 a.m. might not be searchable in {es} until
   10:06 a.m., set this property to 120 seconds. The default value is `60s`.
 
-`script_fields`::
+`script_fields` (Optional)::
   (object) Specifies scripts that evaluate custom expressions and returns
   script fields to the {dfeed}.
   The <<ml-detectorconfig,detector configuration objects>> in a job can contain
@@ -77,27 +88,13 @@ The following properties can be updated after the {dfeed} is created:
   For more information,
   see {ref}/search-request-script-fields.html[Script Fields].
 
-`scroll_size`::
+`scroll_size` (Optional)::
   (unsigned integer) The `size` parameter that is used in {es} searches.
   The default value is `1000`.
 
 For more information about these properties,
 see <<ml-datafeed-resource>>.
 
-[[ml-update-datafeed-prereqs]]
-==== {api-prereq-title}
-
-If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
-cluster privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
-[[ml-update-datafeed-security]]
-==== Security Integration
-
-When {es} {security-features} are enabled, your {dfeed} remembers which roles the
-user who updated it had at the time of update and runs the query using those
-same roles.
-
 [[ml-update-datafeed-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/update-filter.asciidoc

@@ -13,35 +13,36 @@ Updates the description of a filter, adds items, or removes items.
 
 `POST _ml/filters/<filter_id>/_update`
 
+[[ml-update-filter-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-update-filter-path-parms]]
 ==== {api-path-parms-title}
 
-`filter_id` (required)::
+`<filter_id>` (Required)::
 		(string) Identifier for the filter.
 
 [[ml-update-filter-request-body]]
-==== Request Body
+==== {api-request-body-title}
 
-`description`::
+`description` (Optional)::
   (string) A description for the filter. See <<ml-filter-resource>>.
 	
-`add_items`::
+`add_items` (Optional)::
   (array of strings) The items to add to the filter.
 	
-`remove_items`::
+`remove_items` (Optional)::
   (array of strings) The items to remove from the filter.
 
-[[ml-update-filter-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-update-filter-example]]
 ==== {api-examples-title}
 
-You can change the description, add and remove items to the `safe_domains` filter as follows:
+You can change the description, add and remove items to the `safe_domains`
+filter as follows:
 
 [source,js]
 --------------------------------------------------

docs/reference/ml/apis/update-job.asciidoc

@@ -13,11 +13,19 @@ Updates certain properties of a job.
 
 `POST _ml/anomaly_detectors/<job_id>/_update`
 
+[[ml-update-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
+
 [[ml-update-job-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
+`<job_id>` (Required)::
+  (string) Identifier for the job.
 
 [[ml-update-job-request-body]]
 ==== {api-request-body-title}
@@ -88,13 +96,6 @@ A detector update object has the following properties:
 
 No other detector property can be updated.
 
-[[ml-update-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-update-job-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/update-snapshot.asciidoc

@@ -13,37 +13,38 @@ Updates certain properties of a snapshot.
 
 `POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_update`
 
+[[ml-update-snapshot-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
+
 [[ml-update-snapshot-path-parms]]
 ==== {api-path-parms-title}
 
-`job_id` (required)::
-  (string) Identifier for the job
+`<job_id>` (Required)::
+  (string) Identifier for the job.
 
-`snapshot_id` (required)::
-  (string) Identifier for the model snapshot
+`<snapshot_id>` (Required)::
+  (string) Identifier for the model snapshot.
 
 [[ml-update-snapshot-request-body]]
 ==== {api-request-body-title}
 
 The following properties can be updated after the model snapshot is created:
 
-`description`::
-  (string) An optional description of the model snapshot. For example,
+`description` (Optional)::
+  (string) A description of the model snapshot. For example,
   "Before black friday".
 
-`retain`::
+`retain` (Optional)::
   (boolean) If true, this snapshot will not be deleted during automatic cleanup
   of snapshots older than `model_snapshot_retention_days`.
   Note that this snapshot will still be deleted when the job is deleted.
   The default value is false.
 
-[[ml-update-snapshot-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-update-snapshot-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/validate-detector.asciidoc

@@ -13,6 +13,13 @@ Validates detector configuration information.
 
 `POST _ml/anomaly_detectors/_validate/detector`
 
+[[ml-valid-detector-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-valid-detector-desc]]
 ==== {api-description-title}
 
@@ -25,13 +32,6 @@ before you create a job.
 For a list of the properties that you can specify in the body of this API,
 see <<ml-detectorconfig,detector configuration objects>>.
 
-[[ml-valid-detector-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-valid-detector-example]]
 ==== {api-examples-title}
 

docs/reference/ml/apis/validate-job.asciidoc

@@ -13,6 +13,13 @@ Validates job configuration information.
 
 `POST _ml/anomaly_detectors/_validate`
 
+[[ml-valid-job-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have `manage_ml` or
+`manage` cluster privileges to use this API. See
+{stack-ov}/security-privileges.html[Security privileges].
+
 [[ml-valid-job-desc]]
 ==== {api-description-title}
 
@@ -25,13 +32,6 @@ create the job.
 For a list of the properties that you can specify in the body of this API,
 see <<ml-job-resource,Job Resources>>.
 
-[[ml-valid-job-prereqs]]
-==== {api-prereq-title}
-
-You must have `manage_ml`, or `manage` cluster privileges to use this API.
-For more information, see
-{stack-ov}/security-privileges.html[Security privileges].
-
 [[ml-valid-job-example]]
 ==== {api-examples-title}