Elasticsearch API

Base URL

http://api.example.com

Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.

Documentation source and versions

This documentation is derived from the 8.18 branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International. This documentation contains work-in-progress information for future Elastic Stack releases.

Last update on Apr 15, 2025.

This API is provided under license Apache 2.0.

Authentication

The API accepts 3 different authentication methods:

Api key auth (http_api_key)

Elasticsearch APIs support 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, use the /_security/api_key APIs.

Basic auth (http)

Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password (separated by a : colon).

Example: send a Authorization: Basic aGVsbG86aGVsbG8= HTTP header with your requests to authenticate with the API.

Bearer auth (http)

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Get an autoscaling policy Added in 7.11.0

GET /_autoscaling/policy/{name}

Api key auth Basic auth Bearer auth

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

External documentation

Path parameters

name string Required

the name of the autoscaling policy

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attributes Show response attributes object
- roles array[string] Required
- deciders object Required
  
  Decider settings.
  
  External documentation
  
  Hide deciders attribute Show deciders attribute object
  
  * object Additional properties

GET /_autoscaling/policy/{name}

curl \
 --request GET 'http://api.example.com/_autoscaling/policy/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

This may be a response to `GET /_autoscaling/policy/my_autoscaling_policy`.

{
   "roles": <roles>,
   "deciders": <deciders>
}

Create or update an autoscaling policy Added in 7.11.0

PUT /_autoscaling/policy/{name}

Api key auth Basic auth Bearer auth

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

External documentation

Path parameters

name string Required

the name of the autoscaling policy

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body Required

roles array[string] Required
deciders object Required

Decider settings.

External documentation
Hide deciders attribute Show deciders attribute object
- * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_autoscaling/policy/{name}

curl \
 --request PUT 'http://api.example.com/_autoscaling/policy/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"roles\": [],\n  \"deciders\": {\n    \"fixed\": {\n    }\n  }\n}"'

Request examples

{
  "roles": [],
  "deciders": {
    "fixed": {
    }
  }
}

The API method and path for this request: `PUT /_autoscaling/policy/my_autoscaling_policy`. It creates `my_autoscaling_policy` using the fixed autoscaling decider, applying to the set of nodes having (only) the `data_hot` role.

{
  "roles" : [ "data_hot" ],
  "deciders": {
    "fixed": {
    }
  }
}

Response examples (200)

{
  "acknowledged": true
}

Delete an autoscaling policy Added in 7.11.0

DELETE /_autoscaling/policy/{name}

Api key auth Basic auth Bearer auth

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

External documentation

Path parameters

name string Required

the name of the autoscaling policy

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
timeout string

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_autoscaling/policy/{name}

curl \
 --request DELETE 'http://api.example.com/_autoscaling/policy/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

This may be a response to either `DELETE /_autoscaling/policy/my_autoscaling_policy` or `DELETE /_autoscaling/policy/*`.

{
  "acknowledged": true
}

Get the autoscaling capacity Added in 7.11.0

GET /_autoscaling/capacity

Api key auth Basic auth Bearer auth

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

This API gets the current autoscaling capacity based on the configured autoscaling policy. It will return information to size the cluster appropriately to the current workload.

The required_capacity is calculated as the maximum of the required_capacity result of all individual deciders that are enabled for the policy.

The operator should verify that the current_nodes match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.

The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required. This information is provided for diagnosis only. Do not use this information to make autoscaling decisions.

External documentation

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- policies object Required
  
  Hide policies attribute Show policies attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  required_capacity object Required
  
  Hide required_capacity attributes Show required_capacity attributes object
  
  node object Required
  
  Hide node attributes Show node attributes object
  
  storage number Required
  
  memory number Required
  
  total object Required
  
  Hide total attributes Show total attributes object
  
  storage number Required
  
  memory number Required
  
  current_capacity object Required
  
  Hide current_capacity attributes Show current_capacity attributes object
  
  node object Required
  
  Hide node attributes Show node attributes object
  
  storage number Required
  
  memory number Required
  
  total object Required
  
  Hide total attributes Show total attributes object
  
  storage number Required
  
  memory number Required
  
  current_nodes array[object] Required
  
  Hide current_nodes attribute Show current_nodes attribute object
  
  name string Required
  
  deciders object Required
  
  Hide deciders attribute Show deciders attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  required_capacity object Required
  
  Hide required_capacity attributes Show required_capacity attributes object
  
  node object Required
  
  total object Required
  
  reason_summary string
  
  reason_details object

GET /_autoscaling/capacity

curl \
 --request GET 'http://api.example.com/_autoscaling/capacity' \
 --header "Authorization: $API_KEY"

Response examples (200)

This may be a response to `GET /_autoscaling/capacity`.

{
  policies: {}
}

Get behavioral analytics collections Technical preview

GET /_application/analytics/{name}

Api key auth Basic auth Bearer auth

Path parameters

name array[string] Required

A list of analytics collections to limit the returned information

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  event_data_stream object Required
  
  Hide event_data_stream attribute Show event_data_stream attribute object
  
  name string Required

GET /_application/analytics/{name}

curl \
 --request GET 'http://api.example.com/_application/analytics/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _application/analytics/my*`

{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}

Create a behavioral analytics collection Technical preview

PUT /_application/analytics/{name}

Api key auth Basic auth Bearer auth

Path parameters

name string Required

The name of the analytics collection to be created or updated.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- name string Required

PUT /_application/analytics/{name}

curl \
 --request PUT 'http://api.example.com/_application/analytics/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "acknowledged": true,
  "name": "string"
}

Delete a behavioral analytics collection Technical preview

DELETE /_application/analytics/{name}

Api key auth Basic auth Bearer auth

The associated data stream is also deleted.

Path parameters

name string Required

The name of the analytics collection to be deleted

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_application/analytics/{name}

curl \
 --request DELETE 'http://api.example.com/_application/analytics/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "acknowledged": true
}

Get behavioral analytics collections Technical preview

GET /_application/analytics

Api key auth Basic auth Bearer auth

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  event_data_stream object Required
  
  Hide event_data_stream attribute Show event_data_stream attribute object
  
  name string Required

GET /_application/analytics

curl \
 --request GET 'http://api.example.com/_application/analytics' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _application/analytics/my*`

{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}

Create a behavioral analytics collection event Technical preview

POST /_application/analytics/{collection_name}/event/{event_type}

Api key auth Basic auth Bearer auth

External documentation

Path parameters

collection_name string Required

The name of the behavioral analytics collection.
event_type string Required

The analytics event type.

Values are page_view, search, or search_click.

Query parameters

debug boolean

Whether the response type has to include more details

application/json

Body Required

object

Responses

200 application/json
Hide response attributes Show response attributes object
- accepted boolean Required
- event object

POST /_application/analytics/{collection_name}/event/{event_type}

curl \
 --request POST 'http://api.example.com/_application/analytics/{collection_name}/event/{event_type}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"session\": {\n    \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n  },\n  \"user\": {\n    \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n  },\n  \"search\":{\n    \"query\": \"search term\",\n    \"results\": {\n      \"items\": [\n        {\n          \"document\": {\n            \"id\": \"123\",\n            \"index\": \"products\"\n          }\n        }\n      ],\n      \"total_results\": 10\n    },\n    \"sort\": {\n      \"name\": \"relevance\"\n    },\n    \"search_application\": \"website\"\n  },\n  \"document\":{\n    \"id\": \"123\",\n    \"index\": \"products\"\n  }\n}"'

Request example

Run `POST _application/analytics/my_analytics_collection/event/search_click` to send a `search_click` event to an analytics collection called `my_analytics_collection`.

{
  "session": {
    "id": "1797ca95-91c9-4e2e-b1bd-9c38e6f386a9"
  },
  "user": {
    "id": "5f26f01a-bbee-4202-9298-81261067abbd"
  },
  "search":{
    "query": "search term",
    "results": {
      "items": [
        {
          "document": {
            "id": "123",
            "index": "products"
          }
        }
      ],
      "total_results": 10
    },
    "sort": {
      "name": "relevance"
    },
    "search_application": "website"
  },
  "document":{
    "id": "123",
    "index": "products"
  }
}

Response examples (200)

{
  "accepted": true,
  "event": {}
}

Compact and aligned text (CAT)

The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API. All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.

Get aliases

GET /_cat/aliases

Api key auth Basic auth Bearer auth

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
expand_wildcards string | array[string]

The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicated that the request should never timeout, you can set it to -1.

Responses

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
- filter string
  
  filter
- routing.index string
  
  index routing
- routing.search string
  
  search routing
- is_write_index string
  
  write index

GET /_cat/aliases

curl \
 --request GET 'http://api.example.com/_cat/aliases' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.

[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Get aliases

GET /_cat/aliases/{name}

Api key auth Basic auth Bearer auth

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

Path parameters

name string | array[string] Required

A comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
expand_wildcards string | array[string]

The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicated that the request should never timeout, you can set it to -1.

Responses

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
- filter string
  
  filter
- routing.index string
  
  index routing
- routing.search string
  
  search routing
- is_write_index string
  
  write index

GET /_cat/aliases/{name}

curl \
 --request GET 'http://api.example.com/_cat/aliases/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.

[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Get shard allocation information

GET /_cat/allocation

Api key auth Basic auth Bearer auth

Get a snapshot of the number of shards allocated to each data node and their disk space.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- shards string
  
  Number of primary and replica shards assigned to the node.
- shards.undesired string | null
  
  Amount of shards that are scheduled to be moved elsewhere in the cluster or -1 other than desired balance allocator is used
  
  One of:
  string-1 string string-2 string | null
- write_load.forecast number | string | null
  
  Sum of index write load forecasts
  
  One of:
  Stringifieddouble number Stringifieddouble string string-2 string | null
- disk.indices.forecast number | string | null
  
  Sum of shard size forecasts
  
  One of:
  ByteSize number ByteSize string string-2 string | null
- disk.indices number | string | null
  
  Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards. IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.
  
  One of:
  ByteSize number ByteSize string string-2 string | null
- disk.used number | string | null
  
  Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node. Unlike disk.indices, this metric does not double-count disk space for hard-linked files.
  
  One of:
  ByteSize number ByteSize string string-2 string | null
- disk.avail number | string | null
  
  Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s operating system. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
  
  One of:
  ByteSize number ByteSize string string-2 string | null
- disk.total number | string | null
  
  Total disk space for the node, including in-use and available space.
  
  One of:
  ByteSize number ByteSize string string-2 string | null
- disk.percent string | number | null
  
  Total percentage of disk space in use. Calculated as disk.used / disk.total.
  
  One of:
  Percentage string Percentage number string-2 string | null
- host string | null
  
  Network host for the node. Set using the network.host setting.
  
  One of:
  Host string string-2 string | null
- ip string | null
  
  IP address and port for the node.
  
  One of:
  Ip string string-2 string | null
- node string
  
  Name for the node. Set using the node.name setting.
- node.role string | null
  
  Node roles
  
  One of:
  string-1 string string-2 string | null

GET /_cat/allocation

curl \
 --request GET 'http://api.example.com/_cat/allocation' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_cat/allocation?v=true&format=json`. It shows a single shard is allocated to the one node available.

[
  {
    "shards": "1",
    "shards.undesired": "0",
    "write_load.forecast": "0.0",
    "disk.indices.forecast": "260b",
    "disk.indices": "260b",
    "disk.used": "47.3gb",
    "disk.avail": "43.4gb",
    "disk.total": "100.7gb",
    "disk.percent": "46",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "CSUXak2",
    "node.role": "himrst"
  }
]

Get an autoscaling policy Added in 7.11.0

Create or update an autoscaling policy Added in 7.11.0

Body Required

Delete an autoscaling policy Added in 7.11.0

Get the autoscaling capacity Added in 7.11.0

Get behavioral analytics collections Technical preview

Create a behavioral analytics collection Technical preview

Delete a behavioral analytics collection Technical preview

Get behavioral analytics collections Technical preview

Create a behavioral analytics collection event Technical preview

Body Required

shards.undesired string | null

write_load.forecast number | string | null

disk.indices.forecast number | string | null

disk.indices number | string | null

disk.used number | string | null

disk.avail number | string | null

disk.total number | string | null

disk.percent string | number | null

host string | null

ip string | null

node.role string | null