Elasticsearch API conventions

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

You can run Elasticsearch API requests in Dev Tools → Console. For example:

GET _cat/indices?v=true

Check out Console.

When you call Elasticsearch APIs outside of the Console, you must provide a request header. The Elasticsearch APIs support the Authorization, Content-Type, and X-Opaque-Id headers.

Elasticsearch APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example:

curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys or the Elasticsearch Endpoint (${ES_URL}) for a project, refer to Get started.

The type of the content sent in a request body must be specified using the Content-Type header. For example:

curl -X GET "${ES_URL}/_search?pretty" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '
  {
    "query": {
      "match_all": { "boost" : 1.2 }
    }
  }
'

The value of this header must map to one of the 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.

If you use the source query string parameter, you must specify the content type with the source_content_type query string parameter.

Elasticsearch APIs support only UTF-8-encoded JSON. Any other encoding headings sent with a request are ignored. 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. For example:

curl -X GET "${ES_URL}/_search?pretty" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Opaque-Id: 123456" \
  -d '
  {
    "query": {
      "match_all": { "boost" : 1.2 }
    }
  }
'

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.

The X-Opaque-Id header accepts any arbitrary value. However, it is recommended that 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.

A number of Elasticsearch APIs with GET operations—​most notably the search API—​support a request body. While the GET operation makes sense in the context of retrieving information, GET requests with a body are not supported by all HTTP libraries.

All Elasticsearch APIs with GET operations 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. When you use this method, the source_content_type parameter should also be passed with a media type value that indicates the format of the source, such as application/json.