The _create API indexes a document only when its chosen ID is unused. It protects an index from an accidental overwrite: a request that targets an existing ID fails instead of replacing that document’s contents. section 5.1.1 section 5.8
Use a document ID in the request URL and replace _doc with _create. The first request creates document 100; repeating it with the same ID is not an update. section 5.1.1
Listing 5.5 Indexing a new movie using the _create endpoint
PUT movies/_create/100
{
"title":"Mission: Impossible",
"director":"Brian De Palma"
}
Creates a Mission: Impossible document at ID 100. The ID is the condition: this request succeeds only if 100 does not already identify a document in movies. section 5.1.1
Existing IDs produce a conflict
After creating document 100, sending another PUT movies/_create/100 request—even with different fields—returns a version conflict error. The error signals that the existing document remains protected rather than overwritten. section 5.1.1
Choose the endpoint by intent:
- Use _create when a duplicate ID must fail and existing content must remain unchanged. section 5.1.1
- Use _doc with the same ID when replacing a document is intentional. section 5.1.1 section 5.4.4
- Use the _update API when modifying or adding fields to an existing document. section 5.8
A version conflict is operational feedback, not permission to retry the same create unchanged. Decide whether the duplicate indicates an expected prior write, a wrong ID, or a case where replacement through _doc is actually intended. section 5.1.1 section 5.4.4
