diff --git a/docs/reference/search/suggesters.asciidoc b/docs/reference/search/suggesters.asciidoc
index 78aa5d3628564..9d7b5a76ca1ef 100644
--- a/docs/reference/search/suggesters.asciidoc
+++ b/docs/reference/search/suggesters.asciidoc
@@ -1,16 +1,8 @@
 [[search-suggesters]]
 === Suggesters
 
-The suggest feature suggests similar looking terms based on a provided
-text by using a suggester. Parts of the suggest feature are still under
-development.
-
-The suggest request part is defined alongside the query part in a `_search`
-request. If the query part is left out, only suggestions are returned.
-
-NOTE: `_suggest` endpoint has been deprecated in favour of using suggest via
-`_search` endpoint. In 5.0, the `_search` endpoint has been optimized for
-suggest only search requests.
+Suggests similar looking terms based on a provided text by using a suggester. 
+Parts of the suggest feature are still under development.
 
 [source,js]
 --------------------------------------------------
@@ -34,10 +26,27 @@ POST twitter/_search
 // CONSOLE
 // TEST[setup:twitter]
 
-Several suggestions can be specified per request. Each suggestion is
-identified with an arbitrary name. In the example below two suggestions
-are requested. Both `my-suggest-1` and `my-suggest-2` suggestions use
-the `term` suggester, but have a different `text`.
+
+[[search-suggesters-api-request]]
+==== {api-request-title}
+
+The suggest feature suggests similar looking terms based on a provided text by 
+using a suggester. The suggest request part is defined alongside the query part 
+in a `_search` request. If the query part is left out, only suggestions are 
+returned.
+
+NOTE: `_suggest` endpoint has been deprecated in favour of using suggest via
+`_search` endpoint. In 5.0, the `_search` endpoint has been optimized for
+suggest only search requests.
+
+
+[[search-suggesters-api-example]]
+==== {api-examples-title}
+
+Several suggestions can be specified per request. Each suggestion is identified 
+with an arbitrary name. In the example below two suggestions are requested. Both 
+`my-suggest-1` and `my-suggest-2` suggestions use the `term` suggester, but have 
+a different `text`.
 
 [source,js]
 --------------------------------------------------
@@ -62,6 +71,7 @@ POST _search
 // CONSOLE
 // TEST[setup:twitter]
 
+
 The below suggest response example includes the suggestion response for
 `my-suggest-1` and `my-suggest-2`. Each suggestion part contains
 entries. Each entry is effectively a token from the suggest text and
@@ -109,7 +119,7 @@ term suggester's score is based on the edit distance.
 
 [float]
 [[global-suggest]]
-==== Global suggest text
+===== Global suggest text
 
 To avoid repetition of the suggest text, it is possible to define a
 global text. In the example below the suggest text is defined globally