A document API performs one operation on one Elasticsearch document at a time. It supports CRUD-style work: index, retrieve, update, and delete a document through RESTful HTTP endpoints. The document ID identifies the target for its lifetime; clients can supply it or let Elasticsearch generate one. section 3.2.1 section 5.1.1
Use a single-document API when an application handles an individual event or record, such as an e-commerce order, a movie, or an incoming vehicle alert. Use multi-document APIs instead when the job is batch-oriented, such as importing a catalog with millions of records. section 5.0
Index a movie with a chosen ID
Send PUT to an index, the _doc endpoint, and an ID. The JSON body becomes the stored document. PUT movies/_doc/1 { "title":"The Godfather", "synopsis":"The aging patriarch of an organized crime dynasty transfers control of his clandestine empire to his reluctant son" } Here, movies is the index, _doc is the document endpoint, and 1 is the document identifier. When no client ID is available, POST to <index>/_doc and Elasticsearch assigns a unique ID. section 5.1.1
Listing 5.1 Indexing a new document into the movies index
PUT movies/_doc/1 #1
{ #2
"title":"The Godfather",
"synopsis":"The aging patriarch of an organized crime dynasty transfers
control of his clandestine empire to his reluctant son"
}
Inspect the complete single-document indexing request and its annotated URL components. section 5.1.1
Retrieve a known document with GET <index>/_doc/<id>. A successful response contains metadata and the original JSON under _source. If the ID is absent, the response reports found: false. HEAD can check existence first, but GET often avoids an extra round trip by returning either the document or Not Found. section 5.2.1
Fetch or check a movie
GET movies/_doc/1 fetches the document and its metadata. HEAD movies/_doc/1 checks only whether it exists: Elasticsearch returns 200 OK when present and 404 Not Found when absent. section 5.2.1
IDs are the dividing line between direct retrieval and search. A single-document GET needs one ID. To fetch several known IDs, use a search endpoint with an ids query; to retrieve all documents, use _search. Those are search operations rather than single-document calls. section 2.2.2 section 5.2
For indexing, PUT is used when the client provides the ID, while POST is used when Elasticsearch should generate it. If creating a new record must fail when an ID already exists, use the _create endpoint; an existing ID produces a version-conflict response rather than silently accepting the create request. section 5.1.1
