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

A cron expression is a string of the following form:

    <seconds> <minutes> <hours> <day_of_month> <month> <day_of_week> [year]

Elasticsearch uses the cron parser from the Quartz Job Scheduler. For more information about writing Quartz cron expressions, see the Quartz CronTrigger Tutorial.

All schedule times are in coordinated universal time (UTC); other timezones are not supported.

All elements are required except for year. See Cron special characters for information about the allowed special characters.

Date math name resolution lets you to search a range of time series indices or index aliases rather than searching all of your indices and filtering the results. Limiting the number of searched indices reduces cluster load and improves search performance. For example, if you are searching for errors in your daily logs, you can use a date math name template to restrict the search to the past two days.

Most APIs that accept an index or index alias argument support date math. A date math name takes the following form:

<static_name{date_math_expr{date_format|time_zone}}>

Where:

Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other calendars than the Gregorian calendar.

You must enclose date math names in angle brackets. If you use the name in a request path, special characters must be URI encoded. For example:

resp = client.indices.create(
    index="<my-index-{now/d}>",
)
print(resp)

response = client.indices.create(
  index: '<my-index-{now/d}>'
)
puts response

# PUT /<my-index-{now/d}>
PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E

The following example shows different forms of date math names and the final names they resolve to given the current time is 22nd March 2024 noon UTC.

To use the characters { and } in the static part of a name template, escape them with a backslash \, for example:

The following example shows a search request that searches the Logstash indices for the past three days, assuming the indices use the default Logstash index name format, logstash-YYYY.MM.dd.

$params = [
    'index' => '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E',
    'body' => [
        'query' => [
            'match' => [
                'test' => 'data',
            ],
        ],
    ],
];
$response = $client->search($params);

resp = client.search(
    index=[
        "<logstash-{now/d-2d}>",
        "<logstash-{now/d-1d}>",
        "<logstash-{now/d}>",
    ],
    body={"query": {"match": {"test": "data"}}},
)
print(resp)

response = client.search(
  index: '<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>',
  body: {
    query: {
      match: {
        test: 'data'
      }
    }
  }
)
puts response

res, err := es.Search(
	es.Search.WithIndex("%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E"),
	es.Search.WithBody(strings.NewReader(`{
	  "query": {
	    "match": {
	      "test": "data"
	    }
	  }
	}`)),
	es.Search.WithPretty(),
)
fmt.Println(res, err)

const response = await client.search({
  index: '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E',
  body: {
    query: {
      match: {
        test: 'data'
      }
    }
  }
})
console.log(response)

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}

Most APIs that accept a <data-stream>, <index>, or <target> request path parameter also support multi-target syntax.

In multi-target syntax, you can use a comma-separated list to run a request on multiple resources, such as data streams, indices, or aliases: test1,test2,test3. You can also use glob-like wildcard (*) expressions to target resources that match a pattern: test* or *test or te*t or *test*.

You can exclude targets using the - character: test*,-test3.

You can also exclude clusters from a list of clusters to search using the - character: remote*:*,-remote1:*,-remote4:* will search all clusters with an alias that starts with "remote" except for "remote1" and "remote4". Note that to exclude a cluster with this notation you must exclude all of its indexes. Excluding a subset of indexes on a remote cluster is currently not supported. For example, this will throw an exception: remote*:*,-remote1:logs*.

Multi-target APIs that can target indices support the following query string parameters:

The defaults settings for the above parameters depend on the API being used.

Some multi-target APIs that can target indices also support the following query string parameter:

For most APIs, wildcard expressions do not match hidden data streams and indices by default. To match hidden data streams and indices using a wildcard expression, you must specify the expand_wildcards query parameter.

Alternatively, querying an index pattern starting with a dot, such as .watcher_hist*, will match hidden indices by default. This is intended to mirror Unix file-globbing behavior and provide a smoother transition path to hidden indices.

You can create hidden data streams by setting data_stream.hidden to true in the stream’s matching index template. You can hide indices using the index.hidden index setting.

The backing indices for data streams are hidden automatically. Some features, such as machine learning, store information in hidden indices.

Global index templates that match all indices are not applied to hidden indices.

Elasticsearch modules and plugins can store configuration and state information in internal system indices. You should not directly access or modify system indices as they contain data essential to the operation of the system.

Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing.

For libraries that don’t accept a request body for non-POST requests, you can pass the request body as the source query string parameter instead. When using 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.

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

Elasticsearch APIs may respond with the HTTP 429 Too Many Requests status code, indicating that the cluster is too busy to handle the request. When this happens, consider retrying after a short delay. If the retry also receives a 429 Too Many Requests response, extend the delay by backing off exponentially before each subsequent retry.

Many users use a proxy with URL-based access control to secure access to Elasticsearch data streams and indices. For multi-search, multi-get, and bulk requests, the user has the choice of specifying a data stream or index in the URL and on each individual request within the request body. This can make URL-based access control challenging.

To prevent the user from overriding the data stream or index specified in the URL, set rest.action.multi.allow_explicit_index to false in elasticsearch.yml.

This causes Elasticsearch to reject requests that explicitly specify a data stream or index in the request body.

All REST API parameters (both request parameters and JSON body) support providing boolean "false" as the value false and boolean "true" as the value true. All other values will raise an error.

When passing a numeric parameter in a request body, you may use a string containing the number instead of the native numeric type. For example:

resp = client.search(
    body={"size": "1000"},
)
print(resp)

POST /_search
{
  "size": "1000"
}

Integer-valued fields in a response body are described as integer (or occasionally long) in this manual, but there are generally no explicit bounds on such values. JSON, SMILE, CBOR and YAML all permit arbitrarily large integer values. Do not assume that integer fields in a response body will always fit into a 32-bit signed integer.

Whenever the byte size of data needs to be specified, e.g. when setting a buffer size parameter, the value must specify the unit, like 10kb for 10 kilobytes. Note that these units use powers of 1024, so 1kb means 1024 bytes. The supported units are:

Wherever distances need to be specified, such as the distance parameter in the Geo-distance), the default unit is meters if none is specified. Distances can be specified in other units, such as "1km" or "2mi" (2 miles).

The full list of units is listed below:

Whenever durations need to be specified, e.g. for a timeout parameter, the duration must specify the unit, like 2d for 2 days. The supported units are:

Unit-less quantities means that they don’t have a "unit" like "bytes" or "Hertz" or "meter" or "long tonne".

If one of these quantities is large we’ll print it out like 10m for 10,000,000 or 7k for 7,000. We’ll still print 87 when we mean 87 though. These are the supported multipliers: