API conventions

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 the 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.

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.

The 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 unique X-Opaque-Id header for every request. Too many unique X-Opaque-Id values can prevent Elasticsearch from deduplicating warnings in the deprecation logs.

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

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.

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 Content-Type and Accept headers. Setting 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, set compatible-with=7:

Content-Type: application/vnd.elasticsearch+json; compatible-with=7
Accept: application/vnd.elasticsearch+json; compatible-with=7