diff --git a/docs/reference/indices/shard-stores.asciidoc b/docs/reference/indices/shard-stores.asciidoc
index 202a5826ac46f..a1d3f7f224dd4 100644
--- a/docs/reference/indices/shard-stores.asciidoc
+++ b/docs/reference/indices/shard-stores.asciidoc
@@ -4,38 +4,132 @@
 <titleabbrev>Index shard stores</titleabbrev>
 ++++
 
-Provides store information for shard copies of indices.
-Store information reports on which nodes shard copies exist, the shard
-copy allocation ID, a unique identifier for each shard copy, and any exceptions
-encountered while opening the shard index or from earlier engine failure.
+Returns store information
+about replica shards in one or more indices.
 
-By default, only lists store information for shards that have at least one
-unallocated copy. When the cluster health status is yellow, this will list
-store information for shards that have at least one unassigned replica.
-When the cluster health status is red, this will list store information
-for shards, which has unassigned primaries.
+[source,console]
+----
+GET /twitter/_shard_stores
+----
+// TEST[setup:twitter]
+
+
+[[index-shard-stores-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_shard_stores`
+
+`GET /_shard_stores`
+
+
+[[index-shard-stores-api-desc]]
+==== {api-description-title}
+
+Use the index shard stores API to return store information
+about replica shards in one or more indices.
+
+Returned information includes:
+
+* The node on which each replica shard exists
+* Allocation ID for each replica shard
+* Unique ID for each replica shard
+* Any errors encountered
+  while opening the shard index
+  or from an earlier failure
+
+By default, the API only returns store information
+for primary shards that are unassigned
+or have one or more unassigned replica shards.
+
+
+[[index-shard-stores-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To retrieve information for all indices in the cluster,
+use a value of `_all` or `*`
+or omit this parameter.
+
+
+[[index-shard-stores-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+`status`::
++
+--
+(Optional, string)
+Comma-separated list of shard health statuses
+used to limit the request.
 
-Endpoints include shard stores information for a specific index, several
-indices, or all:
+Valid values include:
+
+`green`::
+The primary shard and all replica shards are assigned.
+
+`yellow`::
+One or more replica shards are unassigned.
+
+`red`::
+The primary shard is unassigned.
+
+`all`::
+Return all shards,
+regardless of health status.
+
+Defaults to `yellow,red`.
+--
+
+[[index-shard-stores-api-example]]
+==== {api-examples-title}
+
+
+[[index-shard-stores-api-single-ex]]
+===== Get shard store information for a specific index
 
 [source,console]
---------------------------------------------------
-# return information of only index test
+----
 GET /test/_shard_stores
+----
+// TEST[s/^/PUT test\n/]
+
 
-# return information of only test1 and test2 indices
+[[index-shard-stores-api-multi-ex]]
+===== Get shard store information for several indices
+
+[source,console]
+----
 GET /test1,test2/_shard_stores
+----
+// TEST[s/^/PUT test1\nPUT test2\n/]
+
 
-# return information of all indices
+[[index-shard-stores-api-all-ex]]
+===== Get shard store information for all indices
+
+[source,console]
+----
 GET /_shard_stores
---------------------------------------------------
-// TEST[s/^/PUT test\nPUT test1\nPUT test2\n/]
+----
+// TEST[continued]
+
+
+[[index-shard-stores-api-health-ex]]
+===== Get shard store information based on cluster health
 
-The scope of shards to list store information can be changed through
-`status` param. Defaults to 'yellow' and 'red'. 'yellow' lists store information of
-shards with at least one unassigned replica and 'red' for shards with unassigned
-primary shard.
-Use 'green' to list store information for shards with all assigned copies.
+You can use the `status` query parameter
+to limit returned information based on shard health.
+
+The following request only returns information
+for assigned primary and replica shards.
 
 [source,console]
 --------------------------------------------------
@@ -44,9 +138,7 @@ GET /_shard_stores?status=green
 // TEST[setup:node]
 // TEST[s/^/PUT my-index\n{"settings":{"number_of_shards":1, "number_of_replicas": 0}}\nPOST my-index\/test\?refresh\n{"test": "test"}\n/]
 
-Response:
-
-The shard stores information is grouped by indices and shard ids.
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------