Elasticsearch REST API reference

We generate this reference from the Elasticsearch REST API specification. As such, its usefulness depends on the accuracy of the specification.

For language issues, missing information, and inaccuracies, modify the JSON files in rest-api-spec/src/main/resources/rest-api-spec/api and submit pull requests to the upstream Elasticsearch repository.

bulk

Allows to perform multiple index/update/delete operations in a single request.

POST _bulk
PUT _bulk

POST {index}/_bulk
PUT {index}/_bulk

POST {index}/{type}/_bulk
PUT {index}/{type}/_bulk

HTTP request body

The operation definition and data (action-data pairs), separated by newlines

Required: True

URL parameters

cat.aliases

Shows information about currently configured aliases to indices including filter and routing infos.

GET _cat/aliases

GET _cat/aliases/{name}

URL parameters

cat.allocation

Provides a snapshot of how many shards are allocated to each data node and how much disk space they are using.

GET _cat/allocation

GET _cat/allocation/{node_id}

URL parameters

cat.count

Provides quick access to the document count of the entire cluster, or individual indices.

GET _cat/count

GET _cat/count/{index}

URL parameters

cat.fielddata

Shows how much heap memory is currently being used by fielddata on every data node in the cluster.

GET _cat/fielddata

GET _cat/fielddata/{fields}

URL parameters

cat.health

Returns a concise representation of the cluster health.

GET _cat/health

URL parameters

cat.help

Returns help for the Cat APIs.

GET _cat

URL parameters

cat.indices

Returns information about indices: number of primaries and replicas, document counts, disk size, …

GET _cat/indices

GET _cat/indices/{index}

URL parameters

cat.master

Returns information about the master node.

GET _cat/master

URL parameters

cat.nodeattrs

Returns information about custom node attributes.

GET _cat/nodeattrs

URL parameters

cat.nodes

Returns basic statistics about performance of cluster nodes.

GET _cat/nodes

URL parameters

cat.pending_tasks

Returns a concise representation of the cluster pending tasks.

GET _cat/pending_tasks

URL parameters

cat.plugins

Returns information about installed plugins across nodes node.

GET _cat/plugins

URL parameters

cat.recovery

Returns information about index shard recoveries, both on-going completed.

GET _cat/recovery

GET _cat/recovery/{index}

URL parameters

cat.repositories

Returns information about snapshot repositories registered in the cluster.

GET _cat/repositories

URL parameters

cat.segments

Provides low-level information about the segments in the shards of an index.

GET _cat/segments

GET _cat/segments/{index}

URL parameters

cat.shards

Provides a detailed view of shard allocation on nodes.

GET _cat/shards

GET _cat/shards/{index}

URL parameters

cat.snapshots

Returns all snapshots in a specific repository.

GET _cat/snapshots

GET _cat/snapshots/{repository}

URL parameters

cat.tasks

Returns information about the tasks currently executing on one or more nodes in the cluster.

GET _cat/tasks

URL parameters

cat.templates

Returns information about existing templates.

GET _cat/templates

GET _cat/templates/{name}

URL parameters

cat.thread_pool

Returns cluster-wide thread pool statistics per node. By default the active, queue and rejected statistics are returned for all thread pools.

GET _cat/thread_pool

GET _cat/thread_pool/{thread_pool_patterns}

URL parameters

clear_scroll

Explicitly clears the search context for a scroll.

DELETE _search/scroll

DELETE _search/scroll/{scroll_id}

HTTP request body

A comma-separated list of scroll IDs to clear if none was specified via the scroll_id parameter

cluster.allocation_explain

Provides explanations for shard allocations in the cluster.

GET _cluster/allocation/explain
POST _cluster/allocation/explain

HTTP request body

The index, shard, and primary flag to explain. Empty means ‘explain the first unassigned shard’

URL parameters

cluster.delete_component_template

Deletes a component template

DELETE _component_template/{name}

URL parameters

cluster.delete_voting_config_exclusions

Clears cluster voting config exclusions.

DELETE _cluster/voting_config_exclusions

URL parameters

cluster.exists_component_template

Returns information about whether a particular component template exist

HEAD _component_template/{name}

URL parameters

cluster.get_component_template

Returns one or more component templates

GET _component_template

GET _component_template/{name}

URL parameters

cluster.get_settings

Returns cluster settings.

GET _cluster/settings

URL parameters

cluster.health

Returns basic information about the health of the cluster.

GET _cluster/health

GET _cluster/health/{index}

URL parameters

cluster.pending_tasks

Returns a list of any cluster-level changes (e.g. create index, update mapping, allocate or fail shard) which have not yet been executed.

GET _cluster/pending_tasks

URL parameters

cluster.post_voting_config_exclusions

Updates the cluster voting config exclusions by node ids or node names.

POST _cluster/voting_config_exclusions

URL parameters

cluster.put_component_template

Creates or updates a component template

PUT _component_template/{name}
POST _component_template/{name}

HTTP request body

The template definition

Required: True

URL parameters

cluster.put_settings

Updates the cluster settings.

PUT _cluster/settings

HTTP request body

The settings to be updated. Can be either transient or persistent (survives cluster restart).

Required: True

URL parameters

cluster.remote_info

Returns the information about configured remote clusters.

GET _remote/info

cluster.reroute

Allows to manually change the allocation of individual shards in the cluster.

POST _cluster/reroute

HTTP request body

The definition of commands to perform (move, cancel, allocate)

URL parameters

cluster.state

Returns a comprehensive information about the state of the cluster.

GET _cluster/state

GET _cluster/state/{metric}

GET _cluster/state/{metric}/{index}

URL parameters

cluster.stats

Returns high-level overview of cluster statistics.

GET _cluster/stats

GET _cluster/stats/nodes/{node_id}

URL parameters

count

Returns number of documents matching a query.

POST _count
GET _count

POST {index}/_count
GET {index}/_count

POST {index}/{type}/_count
GET {index}/{type}/_count

HTTP request body

A query to restrict the results specified with the Query DSL (optional)

URL parameters

create

Creates a new document in the index.

Returns a 409 response when a document with a same ID already exists in the index.

PUT {index}/_create/{id}
POST {index}/_create/{id}

PUT {index}/{type}/{id}/_create
POST {index}/{type}/{id}/_create

HTTP request body

The document

Required: True

URL parameters

dangling_indices.delete_dangling_index

Deletes the specified dangling index

DELETE _dangling/{index_uuid}

URL parameters

dangling_indices.import_dangling_index

Imports the specified dangling index

POST _dangling/{index_uuid}

URL parameters

dangling_indices.list_dangling_indices

Returns all dangling indices.

GET _dangling

delete

Removes a document from the index.

DELETE {index}/_doc/{id}

DELETE {index}/{type}/{id}

URL parameters

delete_by_query

Deletes documents matching the provided query.

POST {index}/_delete_by_query

POST {index}/{type}/_delete_by_query

HTTP request body

The search definition using the Query DSL

Required: True

URL parameters

delete_by_query_rethrottle

Changes the number of requests per second for a particular Delete By Query operation.

POST _delete_by_query/{task_id}/_rethrottle

URL parameters

delete_script

Deletes a script.

DELETE _scripts/{id}

URL parameters

exists

Returns information about whether a document exists in an index.

HEAD {index}/_doc/{id}

HEAD {index}/{type}/{id}

URL parameters

exists_source

Returns information about whether a document source exists in an index.

HEAD {index}/_source/{id}

HEAD {index}/{type}/{id}/_source

URL parameters

explain

Returns information about why a specific matches (or doesn’t match) a query.

GET {index}/_explain/{id}
POST {index}/_explain/{id}

GET {index}/{type}/{id}/_explain
POST {index}/{type}/{id}/_explain

HTTP request body

The query definition using the Query DSL

URL parameters

field_caps

Returns the information about the capabilities of fields among multiple indices.

GET _field_caps
POST _field_caps

GET {index}/_field_caps
POST {index}/_field_caps

HTTP request body

An index filter specified with the Query DSL

URL parameters

get

Returns a document.

GET {index}/_doc/{id}

GET {index}/{type}/{id}

URL parameters

get_script

Returns a script.

GET _scripts/{id}

URL parameters

get_script_context

Returns all script contexts.

GET _script_context

get_script_languages

Returns available script types, languages and contexts

GET _script_language

get_source

Returns the source of a document.

GET {index}/_source/{id}

GET {index}/{type}/{id}/_source

URL parameters

index

Creates or updates a document in an index.

PUT {index}/_doc/{id}
POST {index}/_doc/{id}

POST {index}/_doc

POST {index}/{type}

PUT {index}/{type}/{id}
POST {index}/{type}/{id}

HTTP request body

The document

Required: True

URL parameters

indices.add_block

Adds a block to an index.

PUT {index}/_block/{block}

URL parameters

indices.analyze

Performs the analysis process on a text and return the tokens breakdown of the text.

GET _analyze
POST _analyze

GET {index}/_analyze
POST {index}/_analyze

HTTP request body

Define analyzer/tokenizer parameters and the text on which the analysis should be performed

URL parameters

indices.clear_cache

Clears all or specific caches for one or more indices.

POST _cache/clear

POST {index}/_cache/clear

URL parameters

indices.clone

Clones an index

PUT {index}/_clone/{target}
POST {index}/_clone/{target}

HTTP request body

The configuration for the target index (settings and aliases)

URL parameters

indices.close

Closes an index.

POST {index}/_close

URL parameters

indices.create

Creates an index with optional settings and mappings.

PUT {index}

HTTP request body

The configuration for the index (settings and mappings)

URL parameters

indices.delete

Deletes an index.

DELETE {index}

URL parameters

indices.delete_alias

Deletes an alias.

DELETE {index}/_alias/{name}

DELETE {index}/_aliases/{name}

URL parameters

indices.delete_index_template

Deletes an index template.

DELETE _index_template/{name}

URL parameters

indices.delete_template

Deletes an index template.

DELETE _template/{name}

URL parameters

indices.exists

Returns information about whether a particular index exists.

HEAD {index}

URL parameters

indices.exists_alias

Returns information about whether a particular alias exists.

HEAD _alias/{name}

HEAD {index}/_alias/{name}

URL parameters

indices.exists_index_template

Returns information about whether a particular index template exists.

HEAD _index_template/{name}

URL parameters

indices.exists_template

Returns information about whether a particular index template exists.

HEAD _template/{name}

URL parameters

indices.exists_type

Returns information about whether a particular document type exists. (DEPRECATED)

HEAD {index}/_mapping/{type}

URL parameters

indices.flush

Performs the flush operation on one or more indices.

POST _flush
GET _flush

POST {index}/_flush
GET {index}/_flush

URL parameters

indices.flush_synced

Performs a synced flush operation on one or more indices. Synced flush is deprecated and will be removed in 8.0. Use flush instead

POST _flush/synced
GET _flush/synced

POST {index}/_flush/synced
GET {index}/_flush/synced

URL parameters

indices.forcemerge

Performs the force merge operation on one or more indices.

POST _forcemerge

POST {index}/_forcemerge

URL parameters

indices.get

Returns information about one or more indices.

GET {index}

URL parameters

indices.get_alias

Returns an alias.

GET _alias

GET _alias/{name}

GET {index}/_alias/{name}

GET {index}/_alias

URL parameters

indices.get_field_mapping

Returns mapping for one or more fields.

GET _mapping/field/{fields}

GET {index}/_mapping/field/{fields}

GET _mapping/{type}/field/{fields}

GET {index}/_mapping/{type}/field/{fields}

URL parameters

indices.get_index_template

Returns an index template.

GET _index_template

GET _index_template/{name}

URL parameters

indices.get_mapping

Returns mappings for one or more indices.

GET _mapping

GET {index}/_mapping

GET _mapping/{type}

GET {index}/_mapping/{type}

URL parameters

indices.get_settings

Returns settings for one or more indices.

GET _settings

GET {index}/_settings

GET {index}/_settings/{name}

GET _settings/{name}

URL parameters

indices.get_template

Returns an index template.

GET _template

GET _template/{name}

URL parameters

indices.get_upgrade

The _upgrade API is no longer useful and will be removed.

GET _upgrade

GET {index}/_upgrade

URL parameters

indices.open

Opens an index.

POST {index}/_open

URL parameters

indices.put_alias

Creates or updates an alias.

PUT {index}/_alias/{name}
POST {index}/_alias/{name}

PUT {index}/_aliases/{name}
POST {index}/_aliases/{name}

HTTP request body

The settings for the alias, such as routing or filter

Required: False

URL parameters

indices.put_index_template

Creates or updates an index template.

PUT _index_template/{name}
POST _index_template/{name}

HTTP request body

The template definition

Required: True

URL parameters

indices.put_mapping

Updates the index mappings.

PUT {index}/_mapping
POST {index}/_mapping

PUT {index}/{type}/_mapping
POST {index}/{type}/_mapping

PUT {index}/_mapping/{type}
POST {index}/_mapping/{type}

PUT {index}/{type}/_mappings
POST {index}/{type}/_mappings

PUT {index}/_mappings/{type}
POST {index}/_mappings/{type}

PUT _mappings/{type}
POST _mappings/{type}

PUT {index}/_mappings
POST {index}/_mappings

PUT _mapping/{type}
POST _mapping/{type}

HTTP request body

The mapping definition

Required: True

URL parameters

indices.put_settings

Updates the index settings.

PUT _settings

PUT {index}/_settings

HTTP request body

The index settings to be updated

Required: True

URL parameters

indices.put_template

Creates or updates an index template.

PUT _template/{name}
POST _template/{name}

HTTP request body

The template definition

Required: True

URL parameters

indices.recovery

Returns information about ongoing index shard recoveries.

GET _recovery

GET {index}/_recovery

URL parameters

indices.refresh

Performs the refresh operation in one or more indices.

POST _refresh
GET _refresh

POST {index}/_refresh
GET {index}/_refresh

URL parameters

indices.resolve_index

Returns information about any matching indices, aliases, and data streams

GET _resolve/index/{name}

URL parameters

indices.rollover

Updates an alias to point to a new index when the existing index is considered to be too large or too old.

POST {alias}/_rollover

POST {alias}/_rollover/{new_index}

HTTP request body

The conditions that needs to be met for executing rollover

URL parameters

indices.segments

Provides low-level information about segments in a Lucene index.

GET _segments

GET {index}/_segments

URL parameters

indices.shard_stores

Provides store information for shard copies of indices.

GET _shard_stores

GET {index}/_shard_stores

URL parameters

indices.shrink

Allow to shrink an existing index into a new index with fewer primary shards.

PUT {index}/_shrink/{target}
POST {index}/_shrink/{target}

HTTP request body

The configuration for the target index (settings and aliases)

URL parameters

indices.simulate_index_template

Simulate matching the given index name against the index templates in the system

POST _index_template/_simulate_index/{name}

HTTP request body

New index template definition, which will be included in the simulation, as if it already exists in the system

Required: False

URL parameters

indices.simulate_template

Simulate resolving the given template name or body

POST _index_template/_simulate

POST _index_template/_simulate/{name}

HTTP request body

New index template definition to be simulated, if no index template name is specified

Required: False

URL parameters

indices.split

Allows you to split an existing index into a new index with more primary shards.

PUT {index}/_split/{target}
POST {index}/_split/{target}

HTTP request body

The configuration for the target index (settings and aliases)

URL parameters

indices.stats

Provides statistics on operations happening in an index.

GET _stats

GET _stats/{metric}

GET {index}/_stats

GET {index}/_stats/{metric}

URL parameters

indices.update_aliases

Updates index aliases.

POST _aliases

HTTP request body

The definition of actions to perform

Required: True

URL parameters

indices.upgrade

The _upgrade API is no longer useful and will be removed.

POST _upgrade

POST {index}/_upgrade

URL parameters

indices.validate_query

Allows a user to validate a potentially expensive query without executing it.

GET _validate/query
POST _validate/query

GET {index}/_validate/query
POST {index}/_validate/query

GET {index}/{type}/_validate/query
POST {index}/{type}/_validate/query

HTTP request body

The query definition specified with the Query DSL

URL parameters

info

Returns basic information about the cluster.

GET 

ingest.delete_pipeline

Deletes a pipeline.

DELETE _ingest/pipeline/{id}

URL parameters

ingest.get_pipeline

Returns a pipeline.

GET _ingest/pipeline

GET _ingest/pipeline/{id}

URL parameters

ingest.processor_grok

Returns a list of the built-in patterns.

GET _ingest/processor/grok

ingest.put_pipeline

Creates or updates a pipeline.

PUT _ingest/pipeline/{id}

HTTP request body

The ingest definition

Required: True

URL parameters

ingest.simulate

Allows to simulate a pipeline with example documents.

GET _ingest/pipeline/_simulate
POST _ingest/pipeline/_simulate

GET _ingest/pipeline/{id}/_simulate
POST _ingest/pipeline/{id}/_simulate

HTTP request body

The simulate definition

Required: True

URL parameters

mget

Allows to get multiple documents in one request.

GET _mget
POST _mget

GET {index}/_mget
POST {index}/_mget

GET {index}/{type}/_mget
POST {index}/{type}/_mget

HTTP request body

Document identifiers; can be either docs (containing full document information) or ids (when index and type is provided in the URL.

Required: True

URL parameters

msearch

Allows to execute several search operations in one request.

GET _msearch
POST _msearch

GET {index}/_msearch
POST {index}/_msearch

GET {index}/{type}/_msearch
POST {index}/{type}/_msearch

HTTP request body

The request definitions (metadata-search request definition pairs), separated by newlines

Required: True

URL parameters

msearch_template

Allows to execute several search template operations in one request.

GET _msearch/template
POST _msearch/template

GET {index}/_msearch/template
POST {index}/_msearch/template

GET {index}/{type}/_msearch/template
POST {index}/{type}/_msearch/template

HTTP request body

The request definitions (metadata-search request definition pairs), separated by newlines

Required: True

URL parameters

mtermvectors

Returns multiple termvectors in one request.

GET _mtermvectors
POST _mtermvectors

GET {index}/_mtermvectors
POST {index}/_mtermvectors

GET {index}/{type}/_mtermvectors
POST {index}/{type}/_mtermvectors

HTTP request body

Define ids, documents, parameters or a list of parameters per document here. You must at least provide a list of document ids. See documentation.

Required: False

URL parameters

nodes.hot_threads

Returns information about hot threads on each node in the cluster.

GET _nodes/hot_threads

GET _nodes/{node_id}/hot_threads

GET _cluster/nodes/hotthreads

GET _cluster/nodes/{node_id}/hotthreads

GET _nodes/hotthreads

GET _nodes/{node_id}/hotthreads

GET _cluster/nodes/hot_threads

GET _cluster/nodes/{node_id}/hot_threads

URL parameters

nodes.info

Returns information about nodes in the cluster.

GET _nodes

GET _nodes/{node_id}

GET _nodes/{metric}

GET _nodes/{node_id}/{metric}

URL parameters

nodes.reload_secure_settings

Reloads secure settings.

POST _nodes/reload_secure_settings

POST _nodes/{node_id}/reload_secure_settings

HTTP request body

An object containing the password for the elasticsearch keystore

Required: False

URL parameters

nodes.stats

Returns statistical information about nodes in the cluster.

GET _nodes/stats

GET _nodes/{node_id}/stats

GET _nodes/stats/{metric}

GET _nodes/{node_id}/stats/{metric}

GET _nodes/stats/{metric}/{index_metric}

GET _nodes/{node_id}/stats/{metric}/{index_metric}

URL parameters

nodes.usage

Returns low-level information about REST actions usage on nodes.

GET _nodes/usage

GET _nodes/{node_id}/usage

GET _nodes/usage/{metric}

GET _nodes/{node_id}/usage/{metric}

URL parameters

ping

Returns whether the cluster is running.

HEAD 

put_script

Creates or updates a script.

PUT _scripts/{id}
POST _scripts/{id}

PUT _scripts/{id}/{context}
POST _scripts/{id}/{context}

HTTP request body

The document

Required: True

URL parameters

rank_eval

Allows to evaluate the quality of ranked search results over a set of typical search queries

GET _rank_eval
POST _rank_eval

GET {index}/_rank_eval
POST {index}/_rank_eval

HTTP request body

The ranking evaluation search definition, including search requests, document ratings and ranking metric definition.

Required: True

URL parameters

reindex

Allows to copy documents from one index to another, optionally filtering the source documents by a query, changing the destination index settings, or fetching the documents from a remote cluster.

POST _reindex

HTTP request body

The search definition using the Query DSL and the prototype for the index request.

Required: True

URL parameters

reindex_rethrottle

Changes the number of requests per second for a particular Reindex operation.

POST _reindex/{task_id}/_rethrottle

URL parameters

render_search_template

Allows to use the Mustache language to pre-render a search definition.

GET _render/template
POST _render/template

GET _render/template/{id}
POST _render/template/{id}

HTTP request body

The search definition template and its params

scripts_painless_execute

Allows an arbitrary script to be executed and a result to be returned

GET _scripts/painless/_execute
POST _scripts/painless/_execute

HTTP request body

The script to execute

scroll

Allows to retrieve a large numbers of results from a single search request.

GET _search/scroll
POST _search/scroll

GET _search/scroll/{scroll_id}
POST _search/scroll/{scroll_id}

HTTP request body

The scroll ID if not passed by URL or query parameter.

URL parameters

search

Returns results matching a query.

GET _search
POST _search

GET {index}/_search
POST {index}/_search

GET {index}/{type}/_search
POST {index}/{type}/_search

HTTP request body

The search definition using the Query DSL

URL parameters

search_shards

Returns information about the indices and shards that a search request would be executed against.

GET _search_shards
POST _search_shards

GET {index}/_search_shards
POST {index}/_search_shards

URL parameters

search_template

Allows to use the Mustache language to pre-render a search definition.

GET _search/template
POST _search/template

GET {index}/_search/template
POST {index}/_search/template

GET {index}/{type}/_search/template
POST {index}/{type}/_search/template

HTTP request body

The search definition template and its params

Required: True

URL parameters

snapshot.cleanup_repository

Removes stale data from repository.

POST _snapshot/{repository}/_cleanup

URL parameters

snapshot.create

Creates a snapshot in a repository.

PUT _snapshot/{repository}/{snapshot}
POST _snapshot/{repository}/{snapshot}

HTTP request body

The snapshot definition

Required: False

URL parameters

snapshot.create_repository

Creates a repository.

PUT _snapshot/{repository}
POST _snapshot/{repository}

HTTP request body

The repository definition

Required: True

URL parameters

snapshot.delete

Deletes a snapshot.

DELETE _snapshot/{repository}/{snapshot}

URL parameters

snapshot.delete_repository

Deletes a repository.

DELETE _snapshot/{repository}

URL parameters

snapshot.get

Returns information about a snapshot.

GET _snapshot/{repository}/{snapshot}

URL parameters

snapshot.get_repository

Returns information about a repository.

GET _snapshot

GET _snapshot/{repository}

URL parameters

snapshot.restore

Restores a snapshot.

POST _snapshot/{repository}/{snapshot}/_restore

HTTP request body

Details of what to restore

Required: False

URL parameters

snapshot.status

Returns information about the status of a snapshot.

GET _snapshot/_status

GET _snapshot/{repository}/_status

GET _snapshot/{repository}/{snapshot}/_status

URL parameters

snapshot.verify_repository

Verifies a repository.

POST _snapshot/{repository}/_verify

URL parameters

tasks.cancel

Cancels a task, if it can be cancelled through an API.

POST _tasks/_cancel

POST _tasks/{task_id}/_cancel

URL parameters

tasks.get

Returns information about a task.

GET _tasks/{task_id}

URL parameters

tasks.list

Returns a list of tasks.

GET _tasks

URL parameters

termvectors

Returns information and statistics about terms in the fields of a particular document.

GET {index}/_termvectors/{id}
POST {index}/_termvectors/{id}

GET {index}/_termvectors
POST {index}/_termvectors

GET {index}/{type}/{id}/_termvectors
POST {index}/{type}/{id}/_termvectors

GET {index}/{type}/_termvectors
POST {index}/{type}/_termvectors

HTTP request body

Define parameters and or supply a document to get termvectors for. See documentation.

Required: False

URL parameters

update

Updates a document with a script or partial document.

POST {index}/_update/{id}

POST {index}/{type}/{id}/_update

HTTP request body

The request definition requires either script or partial doc

Required: True

URL parameters

update_by_query

Performs an update on every document in the index without changing the source, for example to pick up a mapping change.

POST {index}/_update_by_query

POST {index}/{type}/_update_by_query

HTTP request body

The search definition using the Query DSL

URL parameters

update_by_query_rethrottle

Changes the number of requests per second for a particular Update By Query operation.

POST _update_by_query/{task_id}/_rethrottle

URL parameters