ILM API ref edits (#35112)

* [DOCS] ILM API Ref edits

* [DOCS] Fixed endpoint for DELETE policy.

* [DOCS] Removed comparison to setting index.lifecycle.name to null.

* [DOCS] Fixed xrefs to explain API.

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

@@ -6,15 +6,17 @@
 <titleabbrev>Delete Policy</titleabbrev>
 ++++
 
-Deletes an existing lifecycle policy
+Deletes a lifecycle policy.
 
 ==== Request
 
-`DELETE _ilm/policy/<policy>`
+`DELETE _ilm/policy/<policy_id>`
 
 ==== Description
 
-Deletes an existing lifecycle policy
+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
 
@@ -23,21 +25,15 @@ Deletes an existing lifecycle policy
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  DELETE operation. When this period of time elapses, the API fails and returns
-  an error. The default value is `30s`. For more information about time units, 
-  see <<time-units>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example deletes an existing policy named `my_policy`:
+The following example deletes `my_policy`:
 
 //////////////////////////
 
@@ -77,7 +73,7 @@ DELETE _ilm/policy/my_policy
 // CONSOLE
 // TEST[continued]
 
-If the request does not encounter errors, you receive the following result:
+When the policy is successfully deleted, you receive the following result:
 
 [source,js]
 --------------------------------------------------

docs/reference/ilm/apis/explain.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
-[[ilm-explain]]
+[[ilm-explain-lifecycle]]
 === Explain Lifecycle API
 ++++
 <titleabbrev>Explain Lifecycle</titleabbrev>
 ++++
 
-Shows the current lifecycle status for an index.
+Shows an index's current lifecycle status.
 
 ==== Request
 
@@ -14,11 +14,10 @@ Shows the current lifecycle status for an index.
 
 ==== Description
 
-This API returns information relating to the current lifecycle state of an
-index. This includes information such as the currently executing phase, action,
-and step and the timestamp when the index entered them. It also shows the
-definition of the current phase that is being run and in the event that there
-has been a failure, information regarding the failure.
+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
 
@@ -27,21 +26,15 @@ has been a failure, information regarding the failure.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  GET 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-index-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example retrieves the lifecycle state for the index `my_index`:
+The following example retrieves the lifecycle state of `my_index`:
 
 //////////////////////////
 
@@ -91,7 +84,8 @@ GET my_index/_ilm/explain
 // CONSOLE
 // TEST[continued]
 
-When the index is first taken over by ILM you will see a response like the following:
+When management of the index is first taken over by ILM, `explain` shows
+that the index is managed and in the `new` phase:
 
 [source,js]
 --------------------------------------------------
@@ -102,12 +96,12 @@ When the index is first taken over by ILM you will see a response like the follo
       "managed": true, <1>
       "policy": "my_policy", <2>
       "lifecycle_date_millis": 1538475653281, <3>
-      "phase": "new", <4>
-      "phase_time_millis": 1538475653317, <5>
-      "action": "complete", <6>
-      "action_time_millis": 1538475653317, <7>
-      "step": "complete", <8>
-      "step_time_millis": 1538475653317 <9>
+      "phase": "new",
+      "phase_time_millis": 1538475653317, <4>
+      "action": "complete",
+      "action_time_millis": 1538475653317, <5>
+      "step": "complete",
+      "step_time_millis": 1538475653317 <6>
     }
   }
 }
@@ -121,17 +115,14 @@ When the index is first taken over by ILM you will see a response like the follo
 ILM the other fields will not be shown
 <2> The name of the policy which ILM is using for this index
 <3> The timestamp used for the `min_age`
-<4> The current phase
-<5> The timestamp for when the index entered the current phase
-<6> The current action
-<7> The timestamp for when the index entered the current action
-<8> The current step
-<9> The timestamp for when the index entered the current step
+<4> When the index entered the current phase
+<5> When the index entered the current action
+<6> When the index entered the current step
 
-When the policy is running on the index the response will contain a
-`phase_execution` object that describes the exact phase that is being run.
+Once the policy is running on the index, the response includes a
+`phase_execution` object that shows the definition of the current phase.
 Changes to the underlying policy will not affect this index until the current
-phase definition has been completely executed.
+phase completes.
 
 [source,js]
 --------------------------------------------------
@@ -152,9 +143,9 @@ phase definition has been completely executed.
       "step": "attempt_rollover",
       "step_time_millis": 1538475653317,
       "step_time": "2018-10-15T13:45:22.577Z",
-      "phase_execution": { <1>
-        "policy": "my_lifecycle3", <2>
-        "phase_definition": { <3>
+      "phase_execution": {
+        "policy": "my_lifecycle3",
+        "phase_definition": { <1>
           "min_age": "0ms",
           "actions": {
             "rollover": {
@@ -162,9 +153,9 @@ phase definition has been completely executed.
             }
           }
         },
-        "version": 3, <4>
-        "modified_date": "2018-10-15T13:21:41.576Z", <5>
-        "modified_date_in_millis": 1539609701576 <6>
+        "version": 3, <2>
+        "modified_date": "2018-10-15T13:21:41.576Z", <3>
+        "modified_date_in_millis": 1539609701576 <4>
       }
     }
   }
@@ -172,16 +163,14 @@ phase definition has been completely executed.
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
-<1> The phase execution information for this index in its current phase
-<2> The policy that this phase definition was loaded from
-<3> The phase definition itself. This is the JSON for the phase loaded from the
-policy at the time the index entered the current phase
-<4> The version of the policy at the time the phase definition was loaded
-<5> The last modified date of the policy at the time the phase definition was loaded 
-<6> The last modified epoch time of the policy at the time the phase definition was loaded
-
+<1> The JSON phase definition loaded from the specified policy when the index
+entered this phase
+<2> The version of the policy that was loaded
+<3> The date the loaded policy was last modified
+<4> The epoch time when the loaded policy was last modified
 
-If the policy is waiting for a step to complete for the index, the response will contain step information such as:
+If {ILM} is waiting for a step to complete, the response includes status
+information for the step that's being performed on the index.
 
 [source,js]
 --------------------------------------------------
@@ -236,14 +225,12 @@ If the policy is waiting for a step to complete for the index, the response will
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
-<1> `step_info` shows information about what ILM is waiting for on this index.
-In this case we are waiting for all shard copies of the index to be active.
+<1> Status of the step that's in progress.
 
-If the index is in the ERROR step, something has gone wrong when executing a
-step in the policy and will need to be investigated and resolved for the index
-to make progress. TO help determine how to resolve the error the explain response 
-will show the step that failed in `failed_step`, and the information on the error
-that occurred in `step_info`.
+If the index is in the ERROR step, something went wrong while executing a
+step in the policy and and you will need to take action for the index to proceed
+to the next step. To help you diagnose the problem, the explain response shows
+the step that failed and the step info provides information about the error.
 
 [source,js]
 --------------------------------------------------
@@ -291,6 +278,5 @@ that occurred in `step_info`.
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test]
-<1> The step that caused an error
-<2> Information on the error that occurred. In this case the next index already
-existed when the rollover operation was performed
+<1> The step that caused the error
+<2> What went wrong

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

@@ -6,18 +6,17 @@
 <titleabbrev>Get Policy</titleabbrev>
 ++++
 
-Retrieves an existing policy
+Retrieves a lifecycle policy.
 
 ==== Request
 
 `GET _ilm/policy`
-`GET _ilm/policy/<policy>`
+`GET _ilm/policy/<policy_id>`
 
 ==== Description
 
-This API returns a policy definition along with some of its metadata like
-its last modified date and version. If no path parameters are provided, then
-all the policies defined will be returned.
+Returns the specified policy definition. Includes the policy version and last
+modified date. If no policy is specified, returns all defined policies.
 
 ==== Path Parameters
 
@@ -26,21 +25,15 @@ all the policies defined will be returned.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  GET 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example retrieves the policy named `my_policy`:
+The following example retrieves `my_policy`:
 
 //////////////////////////
 
@@ -80,7 +73,8 @@ GET _ilm/policy
 // CONSOLE
 // TEST[continued]
 
-If the request does not encounter errors, you receive the following result:
+
+If the request succeeds, the body of the response contains the policy definition:
 
 [source,js]
 --------------------------------------------------
@@ -111,5 +105,5 @@ If the request does not encounter errors, you receive the following result:
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[s/"modified_date": 82392349/"modified_date": $body.my_policy.modified_date/]
-<1> The version of the policy. This is increased whenever the policy is updated
-<2> The timestamp when this policy was last modified
+<1> The policy version is incremented whenever the policy is updated
+<2> When this policy was last modified

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

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
 [[ilm-get-status]]
-=== Get ILM Status API
+=== Get {ILM} Status API
 ++++
-<titleabbrev>Get ILM Status</titleabbrev>
+<titleabbrev>Get {ILM} Status</titleabbrev>
 ++++
 
-Gets the current status for ILM.
+Retrieves the current {ilm} status.
 
 ==== Request
 
@@ -14,28 +14,22 @@ Gets the current status for ILM.
 
 ==== Description
 
-This API will return the current status of the ILM plugin. The response contains
-a `operation_mode` field which shows whether the ILM plugin is `STARTED`, `STOPPING`
-or `STOPPED`. This `operation_mode` is controlled by the <<ilm-start, Start ILM>>
-and <<ilm-stop, Stop ILM>> APIs.
+Returns the status of the {ILM} 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} plugin with the
+<<ilm-start, Start ILM>> and <<ilm-stop, Stop ILM>> APIs.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  get 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example stops the ILM plugin.
+The following example gets the {ILM} plugin status.
 
 [source,js]
 --------------------------------------------------
@@ -43,7 +37,7 @@ GET _ilm/status
 --------------------------------------------------
 // CONSOLE
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, the body of the response shows the operation mode:
 
 [source,js]
 --------------------------------------------------

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

@@ -25,7 +25,7 @@ You can use the following APIs to manage policies on indices.
 * <<ilm-get-status,Get ILM Operation Mode>>
 * <<ilm-start,Start ILM>>
 * <<ilm-stop,Stop ILM>>
-* <<ilm-explain,Explain API>>
+* <<ilm-explain-lifecycle,Explain API>>
 
 
 include::put-lifecycle.asciidoc[]

docs/reference/ilm/apis/ilm-cluster-mgt-privilege.asciidoc

@@ -0,0 +1,2 @@
+You must have the cluster `manage` privilege to use this API.
+For more information, see {stack-ov}/security-privileges.html[Security Privileges].

docs/reference/ilm/apis/ilm-index-mgt-privilege.asciidoc

@@ -0,0 +1,2 @@
+You must have the `manage` privilege on the indices being managed to use this API.
+For more information, see {stack-ov}/security-privileges.html[Security Privileges].

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

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
 [[ilm-move-to-step]]
-=== Move To Step API
+=== Move to Lifecycle Step API
 ++++
-<titleabbrev>Move To Step</titleabbrev>
+<titleabbrev>Move to Step</titleabbrev>
 ++++
 
-Moves a managed index into a specific execution step its policy
+Triggers execution of a specific step in the lifecycle policy.
 
 ==== Request
 
@@ -14,13 +14,18 @@ Moves a managed index into a specific execution step its policy
 
 ==== Description
 
-WARNING: This is an expert API that may lead to unintended data loss. When used,
-an index's policy will begin executing at the specified step. It will execute
-the step specified even if it has already executed it. Since this is a, potentionally,
-dangerous action, specifying both the current step and next step to move to is
-required in the body of the request.
+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.
+This is a potentially destructive action and this should be considered an expert
+level API.
 
-This API changes the current step for the specified index to the step supplied in the body of the request
+Manually moves an index into the specified step and executes that step.
+You must specify both the current step and the step to be executed in the
+body of the request.
+
+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
 
@@ -29,22 +34,16 @@ This API changes the current step for the specified index to the step supplied i
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  move 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-index-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example moves the index `my_index` from the initial step to the
-forcemerge step:
+The following example moves `my_index` from the initial step to the
+`forcemerge` step:
 
 //////////////////////////
 
@@ -102,10 +101,10 @@ POST _ilm/move/my_index
 --------------------------------------------------
 // CONSOLE
 // TEST[continued]
-<1> The step that the index is currently expected to be executing
-<2> The step that the index should move to when executing this request
+<1> The step that the index is expected to be in
+<2> The step that you want to execute
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, you receive the following result:
 
 [source,js]
 --------------------------------------------------
@@ -116,6 +115,5 @@ If the request does not encounter errors, you receive the following result:
 // CONSOLE
 // TESTRESPONSE
 
-NOTE: An error will be returned if the index is now longer executing the step
-specified in `current_step`. This is so the index is not moved from an
-unexpected step into the `next_step`.
+The request will fail if the index is not in the `new` phase as specified
+by the `current_step`.

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

@@ -1,25 +1,24 @@
 [role="xpack"]
 [testenv="basic"]
 [[ilm-put-lifecycle]]
-=== Put Lifecycle Policy API
+=== Create Lifecycle Policy API
 ++++
-<titleabbrev>Put Policy</titleabbrev>
+<titleabbrev>Create Policy</titleabbrev>
 ++++
 
-Creates or updates an ILM Policy
+Creates or updates lifecycle policy.
 
 ==== Request
 
-`PUT _ilm/policy/<policy>`
+`PUT _ilm/policy/<policy_id>`
 
 ==== Description
 
-This API creates a new Lifecycle Policy, or updates an existing one with the same
-identifier. Each call will replace the existing policy and increment the `version`
-associated with the policy.
+Creates a lifecycle policy. If the specified policy exists, the policy is
+replaced and the policy version is incremented.
 
-NOTE: The `version` is only for informational purposes. Only the latest version
-of the policy is stored.
+NOTE: Only the latest version of the policy is stored, you cannot revert to
+previous versions.
 
 ==== Path Parameters
 
@@ -28,17 +27,11 @@ of the policy is stored.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  PUT 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
@@ -71,7 +64,7 @@ PUT _ilm/policy/my_policy
 // CONSOLE
 // TEST
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, you receive the following result:
 [source,js]
 ----
 {

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

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
-[[ilm-remove-policy]]
-=== Remove Policy On Index API
+[[ilm-delete-policy]]
+=== Delete Policy from Index API
 ++++
-<titleabbrev>Remove Policy From Index</titleabbrev>
+<titleabbrev>Delete Policy</titleabbrev>
 ++++
 
-Unassigns a policy from a specified index pattern
+Removes the assigned lifecycle policy from an index.
 
 ==== Request
 
@@ -14,8 +14,9 @@ Unassigns a policy from a specified index pattern
 
 ==== Description
 
-This action removes a policy from managing an index. It is effectively the same as setting an index's
-`index.lifecycle.name` setting to null.
+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
 
@@ -24,21 +25,15 @@ This action removes a policy from managing an index. It is effectively the same
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example removes a policy `my_policy` from an index `my_index`.
+The following example removes the assigned policy from `my_index`.
 
 //////////////////////////
 
@@ -85,7 +80,7 @@ POST my_index/_ilm/remove
 // CONSOLE
 // TEST[continued]
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, you receive the following result:
 
 [source,js]
 --------------------------------------------------

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

@@ -3,10 +3,10 @@
 [[ilm-retry-policy]]
 === Retry Policy Execution API
 ++++
-<titleabbrev>Retry Policy Execution</titleabbrev>
+<titleabbrev>Retry Policy</titleabbrev>
 ++++
 
-Retry executing the policy for an index which has errored.
+Retry executing the policy for an index that is in the ERROR step.
 
 ==== Request
 
@@ -14,10 +14,9 @@ Retry executing the policy for an index which has errored.
 
 ==== Description
 
-This API will re-run a policy is currently in the ERROR step. It will set the
-policy back to the step where the error occurred and attempt to re-execute it.
-Information on whether an index is in the ERROR step can be obtained from the 
-<<ilm-explain, ILM Explain API>>
+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
 
@@ -26,21 +25,15 @@ Information on whether an index is in the ERROR step can be obtained from the
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  retry 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-index-mgt-privilege.asciidoc[]
 
 ==== Examples
 
-The following example retries the policy for index `my_index`.
+The following example retries the policy for `my_index`.
 
 [source,js]
 --------------------------------------------------
@@ -48,7 +41,7 @@ POST my_index/_ilm/retry
 --------------------------------------------------
 // NOTCONSOLE
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, you receive the following result:
 
 [source,js]
 --------------------------------------------------

docs/reference/ilm/apis/start.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
 [[ilm-start]]
-=== Start ILM API
+=== Start {ILM} API
 ++++
-<titleabbrev>Start ILM</titleabbrev>
+<titleabbrev>Start {ILM}</titleabbrev>
 ++++
 
-Start the ILM plugin
+Start the {ILM} plugin.
 
 ==== Request
 
@@ -14,23 +14,17 @@ Start the ILM plugin
 
 ==== Description
 
-This API will start the ILM plugin if it is currently stopped. ILM is started
-by default when the cluster is formed so this API is only needed if ILM has
-been stopped using the <<ilm-stop, Stop ILM API>>.
+Starts the {ILM} plugin if it is currently stopped. {ILM} is started
+automatically when the cluster is formed. Restarting {ILM} is only
+necessary if it has been stopped using the <<ilm-stop, Stop {ILM} API>>.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the completion of the 
-  start 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 
@@ -78,7 +72,7 @@ POST _ilm/start
 // CONSOLE
 // TEST[continued]
 
-If the request does not encounter errors, you receive the following result:
+If the request succeeds, you receive the following result:
 
 [source,js]
 --------------------------------------------------

docs/reference/ilm/apis/stop.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
 [[ilm-stop]]
-=== Stop ILM API
+=== Stop {ILM} API
 ++++
-<titleabbrev>Stop ILM</titleabbrev>
+<titleabbrev>Stop {ILM}</titleabbrev>
 ++++
 
-Stop the ILM plugin.
+Stop the {ILM} plugin.
 
 ==== Request
 
@@ -14,25 +14,22 @@ Stop the ILM plugin.
 
 ==== Description
 
-This API will stop the ILM plugin. This can be used for period where 
-maintenance is required and ILM should not perform any actions on any indices.
-The API will return as soon as the stop request has been acknowledged but the 
-plugin may not immediately stop but rather need to wait for some operations
-to finish before it's stopped. Progress can be seen using the 
-<<ilm-get-status, Get ILM Status>> API.
+Halts all lifecycle management operations and stops the {ILM} plugin. This is
+useful when you are performing maintenance on the cluster and need to prevent
+{ILM} from performing any actions on your indices.
+
+The API returns as soon as the stop request has been acknowledged, but the
+plugin might continue to run until in-progress operations complete and the plugin
+can be safely stopped. Use the  <<ilm-get-status, Get ILM Status>> API to see
+if {ILM} is running.
 
 ==== Request Parameters
 
-`timeout`::
-  (time units) Specifies the period of time to wait for the response. 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>>.
+include::{docdir}/rest-api/timeoutparms.asciidoc[]
 
-`master_timeout`::
-  (time units) Specifies the period of time to wait for the connection with master.
-  When this period of time elapses, the API fails and returns an error.
-  The default value is `30s`. For more information about time units, see <<time-units>>.
+==== Authorization
 
+include::ilm-cluster-mgt-privilege.asciidoc[]
 
 ==== Examples
 

docs/reference/ilm/index.asciidoc

@@ -1,13 +1,14 @@
 [role="xpack"]
 [testenv="basic"]
 [[index-lifecycle-management]]
-= Managing Indices
+= Managing the index lifecycle
 
 :ilm:             index lifecycle management
-:ILM:             Index lifecycle management
+:Ilm:             Index lifecycle management
+:ILM:             ILM
 [partintro]
 --
-The <<index-lifecycle-management-api, {ilm} APIs>> enable you to automate how you
+The <<index-lifecycle-management-api, {ilm} (ILM) APIs>> enable you to automate how you
 want to manage your indices over time. Rather than simply performing management
 actions on your indices on a set schedule, you can base actions on other factors
 such as shard size and performance requirements.

docs/reference/ilm/update-lifecycle-policy.asciidoc

@@ -1,9 +1,12 @@
 [role="xpack"]
 [testenv="basic"]
 [[update-lifecycle-policy]]
-== Update lifecycle policy
+== Update Lifecycle Policy
+++++
+<titleabbrev>Update Policy</titleabbrev>
+++++
 
-Updating existing ILM policies is useful to fix mistakes or change
+You can update an existing lifecycle policy to fix mistakes or change
 strategies for newly created indices. It is possible to update policy definitions
 and an index's `index.lifecycle.name` settings independently. To prevent the situation
 that phase definitions are modified while currently being executed on an index, each index
@@ -173,7 +176,7 @@ PUT my_index
 // TEST[continued]
 ////
 
-The <<ilm-explain,Explain API>> is useful to introspect managed indices to see which phase definition they are currently executing.
+The <<ilm-explain-lifecycle,Explain API>> is useful to introspect managed indices to see which phase definition they are currently executing.
 Using this API, we can find out that `my_index` is currently attempting to be rolled over.
 
 [source,js]

docs/reference/rest-api/timeoutparms.asciidoc

@@ -0,0 +1,11 @@
+`timeout`::
+  (time units) Specifies the period of time to wait for a response. If no
+  response is received before the timeout expires, the request fails and
+  returns an error. Defaults to `30s`. For more information about
+  time units, see <<time-units>>.
+
+`master_timeout`::
+  (time units) Specifies the period of time to wait for a connection to the
+  master node. If no response is received before the timeout expires, the request
+  fails and returns an error. Defaults to `30s`. For more information about
+  time units, see <<time-units>>.