The Elasticsearch REST APIs are exposed over HTTP. Except where noted, the following conventions apply across all APIs.
The type of the content sent in a request body must be specified using
Content-Type header. The value of this header must map to one of
the supported formats that the API supports. Most APIs support JSON,
YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
JSON, and SMILE; other types will result in an error response.
When using the
source query string parameter, the content type must be
specified using the
source_content_type query string parameter.
Elasticsearch only supports UTF-8-encoded JSON. Elasticsearch ignores any other encoding headings sent with a request. Responses are also UTF-8 encoded.
X-Opaque-Id HTTP headeredit
You can pass an
X-Opaque-Id HTTP header to track the origin of a request in
Elasticsearch logs and tasks. If provided, Elasticsearch surfaces the
X-Opaque-Id value in the:
For the deprecation logs, Elasticsearch also uses the
X-Opaque-Id value to throttle
and deduplicate deprecation warnings. See Deprecation logs throttling.
X-Opaque-Id header accepts any arbitrary value. However, we recommend you
limit these values to a finite set, such as an ID per client. Don’t generate a
X-Opaque-Id header for every request. Too many unique
values can prevent Elasticsearch from deduplicating warnings in the deprecation logs.
traceparent HTTP headeredit
Elasticsearch also supports a
traceparent HTTP header using the
official W3C trace
context spec. You can use the
traceparent header to trace requests across
Elastic products and other services. Because it’s only used for traces, you can
safely generate a unique
traceparent header for each request.
If provided, Elasticsearch surfaces the header’s
trace-id value as
trace.id in the:
For example, the following
traceparent value would produce the following
trade.id value in the above logs.
`traceparent`: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 `trace.id`: 0af7651916cd43dd8448eb211c80319c
GET and POST requestsedit
A number of Elasticsearch GET APIs—most notably the search API—support a request body.
While the GET action makes sense in the context of retrieving information,
GET requests with a body are not supported by all HTTP libraries.
All Elasticsearch GET APIs that require a body can also be submitted as POST requests.
Alternatively, you can pass the request body as the
source query string parameter
when using GET.
REST API version compatibilityedit
Major version upgrades often include a number of breaking changes that impact how you interact with Elasticsearch. While we recommend that you monitor the deprecation logs and update applications before upgrading Elasticsearch, having to coordinate the necessary changes can be an impediment to upgrading.
You can enable an existing application to function without modification after an upgrade by including API compatibility headers, which tell Elasticsearch you are still using the previous version of the REST API. Using these headers allows the structure of requests and responses to remain the same; it does not guarantee the same behavior.
You set version compatibility on a per-request basis in the
compatible-with to the same major version as
the version you’re running has no impact,
but ensures that the request will still work after Elasticsearch is upgraded.
To tell Elasticsearch 8.0 you are using the 7.x request and response format,
Content-Type: application/vnd.elasticsearch+json; compatible-with=7 Accept: application/vnd.elasticsearch+json; compatible-with=7