diff --git a/docs/en/rest-api/security/clear-cache.asciidoc b/docs/en/rest-api/security/clear-cache.asciidoc
index c4e06eeff23..882ae362bdb 100644
--- a/docs/en/rest-api/security/clear-cache.asciidoc
+++ b/docs/en/rest-api/security/clear-cache.asciidoc
@@ -5,6 +5,31 @@
 The Clear Cache API evicts users from the user cache. You can completely clear
 the cache or evict specific users.
 
+==== Request
+
+`POST _xpack/security/realm/<realms>/_clear_cache` +
+
+`POST _xpack/security/realm/<realms>/_clear_cache?usernames=<usernames>`
+
+
+==== Description
+
+User credentials are cached in memory on each node to avoid connecting to a
+remote authentication service or hitting the disk for every incoming request.
+There are realm settings that you can use to configure the user cache. For more
+information, see {xpack-ref}/controlling-user-cache.html[Controlling the User Cache].
+
+==== Path Parameters
+
+`realms` (required)::
+  (list) A comma-separated list of the realms to clear.
+
+`usernames`::
+  (list) A comma-separated list of the users to clear from the cache. If you
+  do not specify this parameter, the API evicts all users from the user cache.
+
+==== Examples
+
 For example, to evict all users cached by the `file` realm:
 
 [source,js]
@@ -29,6 +54,3 @@ list:
 POST _xpack/security/realm/default_file,ldap1/_clear_cache
 ------------------------------------------------------------
 // CONSOLE
-
-For more information, see 
-{xpack-ref}/controlling-user-cache.html[Controlling the User Cache].