[DOCS] Add clean up snapshot repository API docs (elastic#56519)

docs/reference/rest-api/index.asciidoc

@@ -33,6 +33,7 @@ endif::[]
 * <<search, Search APIs>>
 * <<searchable-snapshots-apis, Searchable snapshots APIs>>
 * <<security-api,Security APIs>>
+* <<snapshot-restore-apis,Snapshot and restore APIs>>
 * <<snapshot-lifecycle-management-api,Snapshot lifecycle management APIs>>
 * <<transform-apis,{transform-cap} APIs>>
 * <<usage-api,Usage API>>
@@ -62,6 +63,7 @@ include::{es-repo-dir}/rollup/rollup-api.asciidoc[]
 include::{es-repo-dir}/search.asciidoc[]
 include::{es-repo-dir}/searchable-snapshots/apis/searchable-snapshots-apis.asciidoc[]
 include::{xes-repo-dir}/rest-api/security.asciidoc[]
+include::{es-repo-dir}/snapshot-restore/apis/snapshot-restore-apis.asciidoc[]
 include::{es-repo-dir}/slm/apis/slm-api.asciidoc[]
 include::{es-repo-dir}/transform/apis/index.asciidoc[]
 include::usage.asciidoc[]

docs/reference/snapshot-restore/apis/clean-up-repo-api.asciidoc

@@ -0,0 +1,116 @@
+[[clean-up-snapshot-repo-api]]
+=== Clean up snapshot repository API
+++++
+<titleabbrev>Clean up snapshot repository</titleabbrev>
+++++
+
+Triggers the review of a snapshot repository's contents and deletes any stale
+data that is not referenced by existing snapshots.
+
+////
+[source,console]
+-----------------------------------
+PUT /_snapshot/my_repository
+{
+  "type": "fs",
+  "settings": {
+    "location": "my_backup_location"
+  }
+}
+-----------------------------------
+// TESTSETUP
+////
+
+[source,console]
+----
+POST /_snapshot/my_repository/_cleanup
+----
+
+[[clean-up-snapshot-repo-api-request]]
+==== {api-request-title}
+
+`POST /_snapshot/<repository>/_cleanup`
+
+[[clean-up-snapshot-repo-api-desc]]
+==== {api-description-title}
+
+Over time, snapshot repositories can accumulate stale data that is no longer
+referenced by existing snapshots.
+
+While this unreferenced data does not negatively impact the performance or
+safety of a snapshot repository, it can lead to more storage use than necessary.
+
+You can use the clean up snapshot repository API to detect and delete this
+unreferenced data.
+
+[TIP]
+====
+Most cleanup operations performed by this API are performed automatically when
+a snapshot is deleted from a repository.
+
+If you regularly delete snapshots, calling this API may only reduce your storage
+slightly or not at all.
+====
+
+[[clean-up-snapshot-repo-api-path-params]]
+==== {api-path-parms-title}
+
+`<repository>`::
+(Required, string)
+Name of the snapshot repository to review and clean up.
+
+[[clean-up-snapshot-repo-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+[role="child_attributes"]
+[[clean-up-snapshot-repo-api-response-body]]
+==== {api-response-body-title}
+
+`results`::
+(object)
+Contains statistics for cleanup operations.
++
+.Properties of `results`
+[%collapsible%open]
+====
+`deleted_bytes`::
+(integer)
+Number of bytes freed by cleanup operations.
+
+`deleted_blobs`::
+(integer)
+Number of binary large objects (blobs) removed from the snapshot repository
+during cleanup operations. Any non-zero value implies that unreferenced blobs
+were found and subsequently cleaned up.
+====
+
+[[clean-up-snapshot-repo-api-example]]
+==== {api-examples-title}
+
+[source,console]
+----
+POST /_snapshot/my_repository/_cleanup
+----
+
+The API returns the following response:
+
+[source,console-result]
+----
+{
+  "results": {
+    "deleted_bytes": 20,
+    "deleted_blobs": 5
+  }
+}
+----
+// TEST[s/"deleted_bytes": 20/"deleted_bytes": 0/]
+// TEST[s/"deleted_blobs": 5/"deleted_blobs": 0/]
+
+////
+[source,console]
+----
+DELETE /_snapshot/my_repository
+----
+////

docs/reference/snapshot-restore/apis/snapshot-restore-apis.asciidoc

@@ -0,0 +1,22 @@
+[[snapshot-restore-apis]]
+== Snapshot and restore APIs
+
+You can use the following APIs to set up snapshot repositories, manage snapshot
+backups, and restore snapshots to a running cluster.
+
+For more information, see <<snapshot-restore>>.
+
+[NOTE]
+====
+We are working on including more snapshot and restore APIs in this section. Some
+content may not be included yet.
+====
+
+[discrete]
+[[snapshot-restore-repo-apis]]
+=== Snapshot repository management APIs
+
+* <<clean-up-snapshot-repo-api,Clean up snapshot repository>>
+
+
+include::clean-up-repo-api.asciidoc[]

rest-api-spec/src/main/resources/rest-api-spec/api/snapshot.cleanup_repository.json

@@ -1,7 +1,7 @@
 {
   "snapshot.cleanup_repository": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html",
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/clean-up-snapshot-repo-api.html",
       "description": "Removes stale data from repository."
     },
     "stability": "stable",