[DOCS] Reformat ILM API docs (#49348)

docs/reference/ilm/apis/delete-lifecycle.asciidoc

@@ -8,31 +8,38 @@
 
 Deletes a lifecycle policy.
 
-==== Request
+[[ilm-delete-lifecycle-request]]
+==== {api-request-title}
 
 `DELETE _ilm/policy/<policy_id>`
 
-==== Description
+[[ilm-delete-lifecycle-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+cluster privilege to use this API. For more information, see
+<<security-privileges>>.
+
+[[ilm-delete-lifecycle-desc]]
+==== {api-description-title}
 
 Deletes the specified lifecycle policy definition. You cannot delete policies
 that are currently in use. If the policy is being used to manage any indices,
 the request fails and returns an error.
 
-==== Path Parameters
+[[ilm-delete-lifecycle-path-params]]
+==== {api-path-parms-title}
 
-`policy` (required)::
+`<policy_id>`::
-  (string) Identifier for the policy.
+  (Required, string) Identifier for the policy.
 
-==== Request Parameters
+[[ilm-delete-lifecycle-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-delete-lifecycle-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` cluster privilege to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example deletes `my_policy`:
 

docs/reference/ilm/apis/explain.asciidoc

@@ -8,42 +8,48 @@
 
 Shows an index's current lifecycle status.
 
-==== Request
+[[ilm-explain-lifecycle-request]]
+==== {api-request-title}
 
 `GET <index>/_ilm/explain`
 
-==== Description
+[[ilm-explain-lifecycle-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage_ilm` or both privileges on the indices being
+managed to use this API. For more information, see <<security-privileges>>.
+
+[[ilm-explain-lifecycle-desc]]
+==== {api-description-title}
 
 Retrieves information about the index's current lifecycle state, such as
 the currently executing phase, action, and step. Shows when the index entered
 each one, the definition of the running phase, and information
 about any failures.
 
-==== Path Parameters
+[[ilm-explain-lifecycle-path-params]]
+==== {api-path-parms-title}
 
-`index` (required)::
+`<index>`::
-  (string) Identifier for the index.
+  (Required, string) Identifier for the index.
 
-==== Request Parameters
+[[ilm-explain-lifecycle-query-params]]
+==== {api-query-parms-title}
 
 `only_managed`::
-  (boolean) Filters the returned indices to only indices that are managed by
+  (Optional, boolean) Filters the returned indices to only indices that are managed by
   ILM.
 
 `only_errors`::
-  (boolean) Filters the returned indices to only indices that are managed by
+  (Optional, boolean) Filters the returned indices to only indices that are managed by
   ILM and are in an error state, either due to an encountering an error while
   executing the policy, or attempting to use a policy that does not exist.
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-explain-lifecycle-example]]
-
+==== {api-examples-title}
-You must have the `view_index_metadata` or `manage_ilm` or both privileges on the indices
-being managed to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example retrieves the lifecycle state of `my_index`:
 

docs/reference/ilm/apis/get-lifecycle.asciidoc

@@ -8,31 +8,38 @@
 
 Retrieves a lifecycle policy.
 
-==== Request
+[[ilm-get-lifecycle-request]]
+==== {api-request-title}
 
 `GET _ilm/policy`
 `GET _ilm/policy/<policy_id>`
 
-==== Description
+[[ilm-get-lifecycle-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm` or
+`read_ilm` or both cluster privileges to use this API. For more information, see
+<<security-privileges>>.
+
+[[ilm-get-lifecycle-desc]]
+==== {api-description-title}
 
 Returns the specified policy definition. Includes the policy version and last
 modified date. If no policy is specified, returns all defined policies.
 
-==== Path Parameters
+[[ilm-get-lifecycle-path-params]]
+==== {api-path-parms-title}
 
-`policy` (optional)::
+`<policy_id>`::
-  (string) Identifier for the policy.
+  (Optional, string) Identifier for the policy.
 
-==== Request Parameters
+[[ilm-get-lifecycle-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-get-lifecycle-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` or `read_ilm` or both cluster privileges to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example retrieves `my_policy`:
 

docs/reference/ilm/apis/get-status.asciidoc

@@ -10,27 +10,33 @@
 
 Retrieves the current {ilm} ({ilm-init}) status.
 
-==== Request
+[[ilm-get-status-request]]
+==== {api-request-title}
 
 `GET /_ilm/status`
 
-==== Description
+[[ilm-get-status-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm` or
+`read_ilm` or both cluster privileges to use this API. For more information, see
+<<security-privileges>>.
+
+[[ilm-get-status-desc]]
+==== {api-description-title}
 
 Returns the status of the {ilm-init} plugin. The `operation_mode` field in the
 response shows one of three states: `STARTED`, `STOPPING`,
 or `STOPPED`. You can change the status of the {ilm-init} plugin with the
-<<ilm-start, Start ILM>> and <<ilm-stop, Stop ILM>> APIs.
+<<ilm-start,start ILM>> and <<ilm-stop,stop ILM>> APIs.
 
-==== Request Parameters
+[[ilm-get-status-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-get-status-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` or `read_ilm` or both cluster privileges to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example gets the {ilm-init} plugin status.
 

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

@@ -1,9 +1,8 @@
 [[index-lifecycle-management-api]]
 == {ilm-cap} API
 
-You can use the following APIs to manage policies on indices. See
+You can use the following APIs to manage policies on indices. For more
-<<index-lifecycle-management,Managing the index lifecycle>> for more information
+information, see <<index-lifecycle-management>>.
-about Index Lifecycle Management.
 
 [float]
 [[ilm-api-policy-endpoint]]

docs/reference/ilm/apis/move-to-step.asciidoc

@@ -8,11 +8,20 @@
 
 Triggers execution of a specific step in the lifecycle policy.
 
-==== Request
+[[ilm-move-to-step-request]]
+==== {api-request-title}
 
 `POST _ilm/move/<index>`
 
-==== Description
+[[ilm-move-to-step-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+privileges on the indices being managed to use this API. For more information,
+see <<security-privileges>>.
+
+[[ilm-move-to-step-desc]]
+==== {api-description-title}
 
 WARNING: This operation can result in the loss of data. Manually moving an index
 into a specific step executes that step even if it has already been performed.
@@ -27,21 +36,19 @@ The request will fail if the current step does not match the step currently
 being executed for the index. This is to prevent the index from being moved from
 an unexpected step into the next step.
 
-==== Path Parameters
+[[ilm-move-to-step-path-params]]
+==== {api-path-parms-title}
 
-`index` (required)::
+`<index>`::
-  (string) Identifier for the index.
+  (Required, string) Identifier for the index.
 
-==== Request Parameters
+[[ilm-move-to-step-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-move-to-step-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` privileges on the indices being managed to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example moves `my_index` from the initial step to the
 `forcemerge` step:

docs/reference/ilm/apis/put-lifecycle.asciidoc

@@ -6,14 +6,25 @@
 <titleabbrev>Create policy</titleabbrev>
 ++++
 
-Creates or updates lifecycle policy. See <<ilm-policy-definition,Policy phases and actions>>
+Creates or updates lifecycle policy. See <<ilm-policy-definition>> for
-for definitions of policy components.
+definitions of policy components.
 
-==== Request
+[[ilm-put-lifecycle-request]]
+==== {api-request-title}
 
 `PUT _ilm/policy/<policy_id>`
 
-==== Description
+[[ilm-put-lifecycle-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+cluster privilege to use this API. You must also have the `manage` index
+privilege on all indices being managed by `policy`. All operations executed by
+{ilm} for a policy are executed as the user that put the latest version of a
+policy. For more information, see <<security-privileges>>.
+
+[[ilm-put-lifecycle-desc]]
+==== {api-description-title}
 
 Creates a lifecycle policy. If the specified policy exists, the policy is
 replaced and the policy version is incremented.
@@ -21,24 +32,19 @@ replaced and the policy version is incremented.
 NOTE: Only the latest version of the policy is stored, you cannot revert to
 previous versions.
 
-==== Path Parameters
+[[ilm-put-lifecycle-path-params]]
+==== {api-path-parms-title}
 
-`policy` (required)::
+`<policy_id>`::
-  (string) Identifier for the policy.
+  (Required, string) Identifier for the policy.
 
-==== Request Parameters
+[[ilm-put-lifecycle-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-put-lifecycle-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` cluster privilege to use this API. You must
-also have the `manage` index privilege on all indices being managed by `policy`.
-All operations executed by {ilm} for a policy are executed as the user that
-put the latest version of a policy.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example creates a new policy named `my_policy`:
 

docs/reference/ilm/apis/remove-policy-from-index.asciidoc

@@ -8,31 +8,38 @@
 
 Removes the assigned lifecycle policy from an index.
 
-==== Request
+[[ilm-remove-policy-request]]
+==== {api-request-title}
 
 `POST <index>/_ilm/remove`
 
-==== Description
+[[ilm-remove-policy-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+privileges on the indices being managed to use this API. For more information,
+see <<security-privileges>>.
+
+[[ilm-remove-policy-desc]]
+==== {api-description-title}
 
 Removes the assigned lifecycle policy and stops managing the specified index.
 If an index pattern is specified, removes the assigned policies from all matching
 indices.
 
-==== Path Parameters
+[[ilm-remove-policy-path-params]]
+==== {api-path-parms-title}
 
-`index` (required)::
+`<index>`::
-  (string) Identifier for the index.
+  (Required, string) Identifier for the index.
 
-==== Request Parameters
+[[ilm-remove-policy-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-remove-policy-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` privileges on the indices being managed to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example removes the assigned policy from `my_index`.
 

docs/reference/ilm/apis/retry-policy.asciidoc

@@ -8,31 +8,38 @@
 
 Retry executing the policy for an index that is in the ERROR step.
 
-==== Request
+[[ilm-retry-policy-request]]
+==== {api-request-title}
 
 `POST <index>/_ilm/retry`
 
-==== Description
+[[ilm-retry-policy-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+privileges on the indices being managed to use this API. For more information,
+see <<security-privileges>>.
+
+[[ilm-retry-policy-desc]]
+==== {api-description-title}
 
 Sets the policy back to the step where the error occurred and executes the step.
 Use the <<ilm-explain-lifecycle, ILM Explain API>> to determine if an index is in the ERROR
 step.
 
-==== Path Parameters
+[[ilm-retry-policy-path-params]]
+==== {api-path-parms-title}
 
-`index` (required)::
+`<index>`::
-  (string) Identifier for the indices to retry in comma-separated format.
+  (Required, string) Identifier for the indices to retry in comma-separated format.
 
-==== Request Parameters
+[[ilm-retry-policy-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-retry-policy-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` privileges on the indices being managed to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example retries the policy for `my_index`.
 

docs/reference/ilm/apis/start.asciidoc

@@ -10,26 +10,32 @@
 
 Start the {ilm} ({ilm-init}) plugin.
 
-==== Request
+[[ilm-start-request]]
+==== {api-request-title}
 
 `POST /_ilm/start`
 
-==== Description
+[[ilm-start-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+cluster privilege to use this API. For more information, see
+<<security-privileges>>.
+
+[[ilm-start-desc]]
+==== {api-description-title}
 
 Starts the {ilm-init} plugin if it is currently stopped. {ilm-init} is started
 automatically when the cluster is formed. Restarting {ilm-init} is only
 necessary if it has been stopped using the <<ilm-stop, Stop {ilm-init} API>>.
 
-==== Request Parameters
+[[ilm-start-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-start-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` cluster privilege to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example starts the ILM plugin.
 

docs/reference/ilm/apis/stop.asciidoc

@@ -10,11 +10,20 @@
 
 Stop the {ilm} ({ilm-init}) plugin.
 
-==== Request
+[[ilm-stop-request]]
+==== {api-request-title}
 
 `POST /_ilm/stop`
 
-==== Description
+[[ilm-stop-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage_ilm`
+cluster privilege to use this API. For more information, see
+<<security-privileges>>.
+
+[[ilm-stop-desc]]
+==== {api-description-title}
 
 Halts all lifecycle management operations and stops the {ilm-init} plugin. This
 is useful when you are performing maintenance on the cluster and need to prevent
@@ -25,16 +34,13 @@ plugin might continue to run until in-progress operations complete and the plugi
 can be safely stopped. Use the  <<ilm-get-status, Get ILM Status>> API to see
 if {ilm-init} is running.
 
-==== Request Parameters
+[[ilm-stop-query-params]]
+==== {api-query-parms-title}
 
 include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-==== Authorization
+[[ilm-stop-example]]
-
+==== {api-examples-title}
-You must have the `manage_ilm` cluster privilege to use this API.
-For more information, see <<security-privileges>>.
-
-==== Examples
 
 The following example stops the ILM plugin.