From 416652cdd8255409a159711df7dff737b03f0071 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Tue, 30 Jun 2020 15:53:03 -0400
Subject: [PATCH] [DOCS] Clarify request formats for index API (#58768)
 (#58774)

---
 docs/reference/docs/index_.asciidoc | 33 +++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/docs/reference/docs/index_.asciidoc b/docs/reference/docs/index_.asciidoc
index b5b5b594878..aa0715da8ac 100644
--- a/docs/reference/docs/index_.asciidoc
+++ b/docs/reference/docs/index_.asciidoc
@@ -10,9 +10,9 @@ Adds a JSON document to the specified data stream or index and makes
 it searchable. If the target is an index and the document already exists,
 the request updates the document and increments its version.
 
-NOTE: You cannot send update requests for existing documents to a data stream.
-To update a document in a data stream, you must target the backing index
-containing the document. See <<update-delete-docs-in-a-data-stream>>.
+NOTE: You cannot use the index API to send update requests for existing
+documents to a data stream. See <<update-delete-docs-in-a-data-stream>>
+and <<update-delete-docs-in-a-backing-index>>.
 
 [[docs-index-api-request]]
 ==== {api-request-title}
@@ -25,6 +25,11 @@ containing the document. See <<update-delete-docs-in-a-data-stream>>.
 
 `POST /<target>/_create/<_id>`
 
+IMPORTANT: You cannot add new documents to a data stream using the 
+`PUT /<target>/_doc/<_id>` request format. To specify a document ID, use the 
+`PUT /<target>/_create/<_id>` format instead. See 
+<<add-documents-to-a-data-stream>>.
+
 [[docs-index-api-path-params]]
 ==== {api-path-parms-title}
 
@@ -42,9 +47,19 @@ this request creates the index.
 You can check for existing targets using the resolve index API.
 
 `<_id>`::
-(Optional, string) Unique identifier for the document. Required if you are
-using a PUT request. Omit to automatically generate an ID when using a
-POST request.
+(Optional, string) Unique identifier for the document.
++
+--
+This parameter is required for the following request formats:
+
+* `PUT /<target>/_doc/<_id>`
+* `PUT /<target>/_create/<_id>`
+* `POST /<target>/_create/<_id>`
+
+To automatically generate a document ID, use the `POST /<target>/_doc/` request
+format and omit this parameter.
+--
+
 
 
 [[docs-index-api-query-params]]
@@ -214,9 +229,9 @@ already exists in the index.
 [float]
 ===== Create document IDs automatically
 
-If you don't specify a document ID when using POST, the `op_type` is
-automatically set to `create` and the index operation generates a unique ID
-for the document.
+When using the `POST /<target>/_doc/` request format, the `op_type` is
+automatically set to `create` and the index operation generates a unique ID for
+the document.
 
 [source,console]
 --------------------------------------------------