[DOCS] EQL: Document delete async search API (#57732)

Author: jrodewig

docs/reference/eql/delete-async-eql-search-api.asciidoc

@@ -0,0 +1,47 @@
+[role="xpack"]
+[testenv="basic"]
+
+[[delete-async-eql-search-api]]
+=== Delete async EQL search API
+++++
+<titleabbrev>Delete async EQL search</titleabbrev>
+++++
+
+dev::[]
+
+Deletes an <<eql-search-async,async EQL search>> or a
+<<eql-search-store-sync-eql-search,stored synchronous EQL search>>. The API also
+deletes results for the search.
+
+[source,console]
+----
+DELETE /_eql/search/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
+----
+// TEST[skip: no access to search ID]
+
+[[delete-async-eql-search-api-request]]
+==== {api-request-title}
+
+`DELETE /_eql/search/<search_id>`
+
+[[delete-async-eql-search-api-prereqs]]
+==== {api-prereq-title}
+
+See <<eql-requirements,EQL requirements>>.
+
+[[delete-async-eql-search-api-limitations]]
+===== Limitations
+
+See <<eql-limitations,EQL limitations>>.
+
+[[delete-async-eql-search-api-path-params]]
+==== {api-path-parms-title}
+
+`<search_id>`::
+(Required, string)
+Identifier for the search to delete.
++
+A search ID is provided in the <<eql-search-api,EQL search API>>'s response for
+an <<eql-search-async,async search>>. A search ID is also provided if the
+request's <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter
+is `true`.

docs/reference/eql/search.asciidoc

@@ -634,6 +634,23 @@ GET /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTo
 // TEST[skip: no access to search ID]
 ====
 
+You can use the <<delete-async-eql-search-api,delete async EQL search API>> to
+manually delete an async EQL search before the `keep_alive` period ends. If the
+search is still ongoing, this cancels the search request.
+
+.*Example*
+[%collapsible]
+====
+The following delete async EQL search API request deletes an async EQL search
+and its results.
+
+[source,console]
+----
+DELETE /_eql/search/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?keep_alive=5d
+----
+// TEST[skip: no access to search ID]
+====
+
 [discrete]
 [[eql-search-store-sync-eql-search]]
 === Store synchronous EQL searches
@@ -642,8 +659,7 @@ By default, the EQL search API only stores async searches that cannot be
 completed within the period set by the `wait_for_completion_timeout` parameter.
 
 To save the results of searches that complete during this period, set the
-`keep_on_completion` parameter to `true`. Note these saved searches are still
-subject to the storage retention period set by the `keep_alive` parameter.
+`keep_on_completion` parameter to `true`.
 
 [%collapsible]
 .*Example*
@@ -694,6 +710,13 @@ GET /_eql/search/FjlmbndxNmJjU0RPdExBTGg0elNOOEEaQk9xSjJBQzBRMldZa1VVQ2pPa01YUTo
 // TEST[skip: no access to search ID]
 ====
 
+Saved synchronous searches are still subject to the storage retention period set
+by the `keep_alive` parameter. After this period, the search and its saved
+results are deleted.
+
+You can also manually delete saved synchronous searches using the
+<<delete-async-eql-search-api,delete async EQL search API>>.
+
 [discrete]
 [[eql-search-case-sensitive]]
 === Run a case-sensitive EQL search

docs/reference/search.asciidoc

@@ -174,6 +174,8 @@ include::eql/eql-search-api.asciidoc[]
 
 include::eql/get-async-eql-search-api.asciidoc[]
 
+include::eql/delete-async-eql-search-api.asciidoc[]
+
 endif::[]
 
 include::search/count.asciidoc[]