diff --git a/docs/reference/ilm/apis/slm-api.asciidoc b/docs/reference/ilm/apis/slm-api.asciidoc
index 9522ccb7b76..1e34a0f9b54 100644
--- a/docs/reference/ilm/apis/slm-api.asciidoc
+++ b/docs/reference/ilm/apis/slm-api.asciidoc
@@ -21,36 +21,166 @@ by a different enable setting. To disable SLM's functionality, set the cluster
setting `xpack.slm.enabled` to `false` in elasticsearch.yml.
[[slm-api-put]]
-=== Put Snapshot Lifecycle Policy API
+=== Put snapshot lifecycle policy API
+++++
+Put snapshot lifecycle policy
+++++
-Creates or updates a snapshot policy. If the policy already exists, the version
-is incremented. Only the latest version of a policy is stored.
+Creates or updates a snapshot lifecycle policy.
-When a policy is created it is immediately scheduled based on the schedule of
-the policy, when a policy is updated its schedule changes are immediately
-applied.
-==== Path Parameters
+[[slm-api-put-request]]
+==== {api-request-title}
-`policy_id` (required)::
- (string) Identifier (id) for the policy.
+`PUT /_slm/policy/`
-==== Request Parameters
+
+[[slm-api-put-prereqs]]
+==== {api-prereq-title}
+
+If you use {es} {security-features},
+you must have:
+
+* `manage_slm` <>
+* `manage` <> for any included indices
+
+{slm-cap} operations are executed
+as the user that last created or updated the policy.
+
+For more information,
+see <>.
+
+
+[[slm-api-put-desc]]
+==== {api-description-title}
+
+Use the put snapshot lifecycle policy API
+to create or update a snapshot lifecycle policy.
+
+If the policy already exists,
+this request increments the policy's version.
+Only the latest version of the policy is stored.
+
+
+
+[[slm-api-put-path-params]]
+==== {api-path-parms-title}
+
+``::
+(Required, string)
+ID for the snapshot lifecycle policy
+you want to create or update.
+
+
+[[slm-api-put-query-params]]
+==== {api-query-parms-title}
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
-==== Authorization
-You must have the `manage_slm` 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 {slm} for a policy are executed as the user that put the
-latest version of a policy. For more information, see
-<>.
+[[slm-api-put-request-body]]
+==== {api-request-body-title}
-==== Example
+`schedule`::
+(Required, <>)
+Periodic or absolute schedule
+at which the policy creates snapshots
+and deletes expired snapshots.
++
+Schedule changes to existing policies
+are applied immediately.
-The following creates a snapshot lifecycle policy with an id of
-`daily-snapshots`:
+`name`::
++
+--
+(Required, string)
+Name automatically assigned to each snapshot
+created by the policy.
+
+This value supports the same <>
+supported in index names.
+
+To prevent conflicting snapshot names,
+a UUID is automatically appended to each snapshot name.
+--
+
+`repository`::
++
+--
+(Required, string)
+Repository used to store snapshots
+created by this policy.
+
+This repository must exist prior to the policy's creation.
+You can create a repository
+using the <>.
+--
+
+`config`::
++
+--
+(Required, object)
+Configuration for each snapshot
+created by the policy.
+
+Parameters include:
+
+`indices`::
+(Optional, array of strings)
+Array of index names or wildcard pattern of index names
+included in snapshots.
+
+`ignore_unavailable`::
+(Optional, boolean)
+If `true`,
+missing indices do *not* cause snapshot creation to fail
+and return an error.
+Defaults to `false`.
+
+`include_global_state`::
+(Optional, boolean)
+If `true`,
+cluster states are included in snapshots.
+Defaults to `false`.
+--
+
+`retention`::
++
+--
+(Optional, object)
+Retention rules used to retain
+and delete snapshots
+created by the policy.
+
+Parameters include:
+
+`expire_after`::
+(Optional, <>)
+Time period after which
+a snapshot is considered expired
+and eligible for deletion.
+
+`max_count`::
+(Optional, integer)
+Maximum number of snapshots to retain,
+even if the snapshots have not yet expired.
++
+If the number of snapshots in the repository exceeds this limit,
+the policy retains the most recent snapshots
+and deletes older snapshots.
+
+`min_count`::
+(Optional, integer)
+Minimum number of snapshots to retain,
+even if the snapshots have expired.
+--
+
+
+[[slm-api-put-example]]
+==== {api-examples-title}
+
+The following request creates a snapshot lifecycle policy
+with an ID of `daily-snapshots`:
[source,console]
--------------------------------------------------
@@ -83,31 +213,6 @@ PUT /_slm/policy/daily-snapshots
<8> Always keep at least 5 successful snapshots, even if they're more than 30 days old
<9> Keep no more than 50 successful snapshots, even if they're less than 30 days old
-The top-level keys that the policy supports are described below:
-
-|==================
-| Key | Description
-
-| `schedule` | A periodic or absolute time schedule. Supports all values
- supported by the cron scheduler:
- <>
-
-| `name` | A name automatically given to each snapshot performed by this policy.
- Supports the same <> supported in index
- names. A UUID is automatically appended to the end of the name to prevent
- conflicting snapshot names.
-
-| `repository` | The snapshot repository that will contain snapshots created by
- this policy. The repository must exist prior to the policy's creation and can
- be created with the <>.
-
-| `config` | Configuration for each snapshot that will be created by this
- policy. Any configuration is included with <> issued by this policy.
-|==================
-
-To update an existing policy, simply use the put snapshot lifecycle policy API
-with the same policy id as an existing policy.
[[slm-api-get]]
=== Get Snapshot Lifecycle Policy API