Elasticsearch commands

Request lines of the Elasticsearch REST API, checked against the 9.5 branch of Elastic's API specification and grouped by task: cluster health and settings, nodes, cat tables, indices, mappings, aliases, templates, data streams, documents, search, reindex, tasks, snapshots, lifecycle policies, ingest pipelines and security basics. Braces mark a path parameter, so GET /{index}/_search targets your own index. Left out: machine learning, transforms, Watcher, cross-cluster replication, inference, connectors, Fleet, EQL and other specialised APIs named in the notes.

343 commands in 24 sections. Checked row by row against Elasticsearch API specification, branch 9.5 (elastic/elasticsearch-specification, output/schema/schema.json) on . Edited by Jay.

Cluster health and state 19

CommandWhat it does
GET /Version and build detailsShows which version and build the cluster runs; the quickest check that a node is answering.
HEAD /Ping the clusterAnswers with a status code only, which suits liveness probes and scripts.
GET /_cluster/healthCluster health statusReports green, yellow or red: red means a primary shard is unallocated, yellow that only replicas are missing.
GET /_cluster/health/{index}Health of chosen indicesLimits the answer to the named data streams or indices, each rated by its worst shard.
GET /_health_reportHealth report with diagnosesRates every health indicator green, yellow, red or unknown and adds impacts and a diagnosis when one is not green.
GET /_health_report/{feature}Report on one health indicatorNarrows the report to a single indicator named in the full report.
GET /_cluster/allocation/explainExplain a shard allocationGives the reasons a shard has no node, or the reasons an assigned shard is kept where it is.
POST /_cluster/allocation/explainExplain a shard named in the bodyTakes index, shard, primary and current_node as JSON; body and query parameters cannot be mixed.
GET /_cluster/allocation/explain?index=my-index-000001&shard=0&primary=false&current_node=my-nodeExplain one replica by URLNames the shard copy through query parameters, so no request body is needed.
GET /_cluster/health?filter_path=status,*_shardsStatus and shard counters onlyfilter_path cuts the health response down to the status and the shard numbers, the first look in an incident.
GET /_cluster/allocation/explain?filter_path=index,node_allocation_decisions.node_name,node_allocation_decisions.deciders.*Allocation deciders per nodeKeeps only the index, the node names and what each decider ruled for an unassigned shard.
POST /_cluster/rerouteMove or allocate shards by handRuns move, cancel and allocate commands from the body; normal rebalancing still follows afterwards.
POST /_cluster/reroute?retry_failedRetry failed shard allocationsFor shards that used up their allocation retries; they are allocated if the cause has been fixed.
GET /_cluster/stateFull cluster stateDumps the internal state kept by the master: nodes, settings, index metadata and shard locations. Meant for debugging.
GET /_cluster/state/{metric}Selected parts of cluster stateKeeps the response small by naming parts such as metadata, routing_table, nodes, blocks or master_node.
GET /_cluster/state/{metric}/{index}Cluster state for chosen indicesRestricts the chosen parts to a comma-separated list of index names.
GET /_cluster/statsCluster-wide statisticsSummarises shard counts, store size and memory use, plus roles, operating systems, JVM versions and plugins of the nodes.
GET /_cluster/pending_tasksPending cluster state updatesLists changes such as index creation or shard allocation that have not taken effect yet; separate from the task management list.
GET /_remote/infoRemote cluster connectionsLists configured remote clusters by alias; connected only means a connection is open right now.

Cluster settings, licence and upgrade checks 14

CommandWhat it does
GET /_cluster/settingsRead cluster settingsLists only settings that someone defined explicitly unless include_defaults is switched on.
GET /_cluster/settings?filter_path=persistent.cluster.remoteRead one branch of the settingsfilter_path trims the response, here to the persistent remote cluster configuration.
GET /_cluster/settings?flat_settings=true&include_defaults=trueAll cluster settings with defaultsDotted keys plus built-in defaults, the form to review allocation settings with.
GET /_cluster/settings?include_defaults=true&filter_path=*.cluster.routing.allocation.enableCheck that allocation is enabledShows whether shard allocation was left disabled after a restart or other maintenance.
PUT /_cluster/settingsChange cluster settingsChanges dynamic settings without a restart, as persistent or transient; a null value resets a setting.
POST /_cluster/voting_config_exclusionsExclude nodes from votingFor removing half the master-eligible nodes or more in one go; the call waits until the voting configuration has shrunk.
DELETE /_cluster/voting_config_exclusionsClear the voting exclusionsRun it once the excluded nodes have stopped, because the list should be empty in normal operation.
GET /_licenseLicence type and expiryShows the licence type, its status and the dates it was issued and expires.
POST /_license/start_trial?acknowledge=trueStart a 30-day trialUnlocks all subscription features; possible only once per major version.
POST /_license/start_basic?acknowledge=trueSwitch to the basic licenceThe acknowledge parameter confirms the loss of features that the previous licence covered.
GET /_xpackBuild, licence and feature summaryOne response with build details, the installed licence and which features are available and enabled.
GET /_xpack/usageFeature usage statisticsAdds usage numbers for the features the current licence enables.
GET /_migration/deprecationsDeprecation check before an upgradeLists cluster, node and index settings in use that the next major version removes or changes.
GET /_migration/system_featuresSystem feature migration statusShows which features still have to migrate their system indices and whether a migration is running; POST starts it.

Nodes 14

CommandWhat it does
GET /_nodesNode informationLists every node with its attributes and core settings unless a metric is named.
GET /_nodes/{node_id}Information on chosen nodesAccepts node IDs or names separated by commas.
GET /_nodes/{metric}One section of node informationMetrics include settings, os, process, jvm, thread_pool, transport, http, plugins and ingest.
GET /_nodes/statsNode statisticsReturns every statistic for each node; the longer forms narrow it by node and metric.
GET /_nodes/{node_id}/statsStatistics for chosen nodesFilters by node ID or node name before collecting the numbers.
GET /_nodes/stats/{metric}One group of node statisticsMetrics include indices, os, process, jvm, thread_pool, fs, transport, http, breaker and indexing_pressure.
GET /_nodes/{node_id}/stats/{metric}One statistics group on chosen nodesThe narrowest everyday form: one node, one metric such as jvm or fs.
GET /_nodes/stats/{metric}/{index_metric}Index statistics per nodeNeeds indices or _all as the metric; the last segment picks groups such as store, search, merge or refresh.
GET /_nodes/stats/process?filter_path=**.max_file_descriptorsFile descriptor limit of every nodeCombines the process metric with filter_path so only that one field comes back.
GET /_nodes/hot_threadsHot threads on every nodeReturns plain text, not JSON, breaking down the busiest threads of each node.
GET /_nodes/{node_id}/hot_threadsHot threads on chosen nodesSamples only the nodes named in the path.
GET /_nodes/usageFeature usage per nodeThe longer form /_nodes/usage/{metric} narrows it to rest_actions or aggregations.
POST /_nodes/reload_secure_settingsReload keystore settingsApplies reloadable secure settings changed on disk without a restart; a password-protected keystore needs its password.
POST /_nodes/{node_id}/reload_secure_settingsReload the keystore on chosen nodesFor nodes whose keystore passwords differ, since the cluster-wide call assumes one shared password.

Cat tables for cluster and nodes 22

Cat endpoints are meant for people at a terminal or the Kibana console. Applications should call the JSON API that each cat description points to.

CommandWhat it does
GET /_catList the cat endpointsPrints the available cat commands; cat output is meant for people at a terminal or the Kibana console.
GET /_cat/healthHealth as a table rowTerminal-friendly view of cluster health; applications should call the cluster health API instead.
GET /_cat/health?v=true&format=jsonHealth with headings, as JSONv=true turns on verbose output and format switches the table to json, yaml, cbor or smile.
GET /_cat/nodesNodes tableOverview of the nodes in the cluster; applications should use the nodes info API instead.
GET /_cat/nodes?v=true&h=id,ip,port,v,m&format=jsonNodes table with chosen columnsh picks the columns to show; without it the default set is ip,hp,rp,r,m,n,cpu,l.
GET /_cat/masterElected master nodeShows which node is the elected master: its ID, IP address and name.
GET /_cat/nodeattrsCustom node attributesShows custom attributes per node next to host, IP and port columns.
GET /_cat/pluginsPlugins per nodeOne line per plugin and node; include_bootstrap adds the bootstrap plugins.
GET /_cat/allocationShards and disk per data nodeCounts the shards allocated to every data node next to its disk space.
GET /_cat/allocation?v=true&h=node,shards,disk.*Disk space per nodeCompare with the low disk watermark: nodes above 85% disk use receive no new shards by default.
GET /_cat/allocation/{node_id}Allocation for chosen nodesLimits the table to the listed node IDs or names.
GET /_cat/thread_poolThread pool statisticsCovers built-in and custom pools on every node.
GET /_cat/thread_pool/{thread_pool_patterns}Statistics for chosen thread poolsTakes pool names separated by commas, wildcards allowed.
GET /_cat/pending_tasksPending cluster changes as a tableTabular form of the pending cluster tasks call.
GET /_cat/pending_tasks?v=true&h=insertOrder,timeInQueue,priority,source&format=jsonPending changes with queue timeSelects the order, waiting time, priority and source columns.
GET /_cat/tasksRunning tasks as a tableTable view of the task management list.
GET /_cat/circuit_breakerCircuit breaker statisticsTabular view of the circuit breaker numbers; add ?v=true for column headings.
GET /_cat/fielddataFielddata heap use per nodeShows how much heap the field data cache takes on each data node.
GET /_cat/repositoriesSnapshot repositories tableLists the snapshot repositories registered in the cluster.
GET /_cat/snapshotsSnapshots tableLists snapshots across the registered repositories.
GET /_cat/snapshots/{repository}Snapshots in chosen repositoriesLimits the table to the repositories named in the path.
GET /_cat/snapshots/repo1?v=true&s=id&format=jsonSnapshots sorted by IDs sorts the table by a column; add :desc after the column name to reverse it.

Cat tables for indices and shards 15

CommandWhat it does
GET /_cat/indicesIndices tablePer index: health, shards, documents, deleted documents and store size, with data stream backing indices included.
GET /_cat/indices/{index}Table for chosen indicesAccepts names and wildcards for data streams, indices and aliases.
GET /_cat/indices/my-index-*?v=true&s=index&format=jsonMatching indices, sorted by nameWildcard target with headings switched on and rows ordered by the index column.
GET /_cat/shardsShards tableLists the shards in the cluster; data streams appear as their backing indices.
GET /_cat/shards?v=true&h=index,shard,prirep,state,node,unassigned.reason&s=stateUnassigned shards with reasonsUnassigned shards carry the state UNASSIGNED; prirep is p for a primary and r for a replica.
GET /_cat/shards/{index}Shards of chosen indicesLimits the table to the listed data streams, indices or aliases.
GET /_cat/segmentsLucene segments tableLow-level view of the segments inside every index shard.
GET /_cat/recoveryShard recoveries tableCovers ongoing and completed recoveries, such as a replica syncing from its primary or a restore from a snapshot.
GET /_cat/recovery/{index}Recoveries of chosen indicesLimits the recovery list to the targets named in the path.
GET /_cat/countDocument count for the clusterCounts live documents only; deleted ones not yet merged away are excluded.
GET /_cat/count/{index}Document count for chosen indicesQuick count for one data stream or index.
GET /_cat/aliasesAliases tableLists index aliases with their filter and routing details; data stream aliases are not included.
GET /_cat/aliases/{name}Table for chosen aliasesTakes alias names separated by commas, wildcards allowed.
GET /_cat/templatesIndex templates tableLists the index templates defined in the cluster.
GET /_cat/component_templatesComponent templates tableLists the building blocks that index templates are composed of.

Creating and managing indices 16

CommandWhat it does
PUT /{index}Create an indexThe optional body carries settings, field mappings and aliases; index names must be lowercase.
GET /{index}Show an index definitionReturns aliases, mappings and settings together for the named indices; wildcards are allowed.
HEAD /{index}Check that an index existsWorks for data streams, indices and aliases and answers with the status code alone.
DELETE /{index}Delete indicesRemoves documents, shards and metadata; aliases cannot be named and wildcards are refused by default.
POST /{index}/_closeClose an indexA closed index can be neither written to nor searched, which lowers its overhead on the cluster.
POST /{index}/_openReopen a closed indexThe shards go through normal recovery; on a data stream it opens any closed backing indices.
PUT /{index}/_block/{block}Add an index blockBlock types are metadata, read, read_only and write; a write block makes the index read-only before a shrink or split.
DELETE /{index}/_block/{block}Remove an index blockLifts one block type again so the blocked operations are allowed.
POST /{index}/_clone/{target}Clone an indexCopies every primary shard into a new index; index templates are not applied and replica count is not carried over.
POST /{index}/_shrink/{target}Shrink to fewer primary shardsNeeds a read-only, green source with every shard on one node; the new shard count must divide the old.
POST /{index}/_split/{target}Split into more primary shardsNeeds a read-only source; how far it can split depends on index.number_of_routing_shards.
POST /{alias}/_rolloverStart a new write indexOn a data stream it creates a new write index; body conditions make it conditional and dry_run=true only tests them.
POST /{alias}/_rollover/{new_index}Roll over to a named indexFor index aliases only: sets the new index name, which may use date math.
GET /_resolve/index/{name}Resolve names and patternsShows which indices, aliases and data streams an expression matches, remote clusters included.
GET /_resolve/clusterList remote clusters before a searchWithout an index expression it reports on every configured remote cluster.
GET /_resolve/cluster/{name}Check clusters for an expressionReports for each cluster in the expression whether it is connected, a useful test before a cross-cluster search.

Index maintenance and statistics 23

CommandWhat it does
GET /_refreshRefresh all indicesMakes recent writes searchable at once instead of waiting for the periodic refresh; costly if run often.
POST /{index}/_refreshRefresh chosen indicesThe request returns only when the refresh has completed.
POST /_flushFlush all indicesWrites operations that so far exist only in the transaction log to the Lucene index; normally automatic.
POST /{index}/_flushFlush chosen indicesTakes data streams, indices and aliases, wildcards included.
POST /_forcemergeForce merge all indicesMerges segments on demand; recommended only for indices that no longer receive writes.
POST /{index}/_forcemergeForce merge chosen indicesAdd max_num_segments to set the target count or only_expunge_deletes to purge deleted documents only.
POST /_cache/clearClear caches on all indicesClears every cache unless fielddata, query or request is passed to pick one.
POST /{index}/_cache/clearClear caches of chosen indicesOn a data stream it clears the caches of the backing indices.
POST /my-index-000001,my-index-000002/_cache/clear?request=trueClear only the request cacheTwo indices in one call, limited to a single cache type.
GET /_statsStatistics for all indicesIndex-level numbers with primaries and total sections; level=shards breaks them down per shard.
GET /_stats/{metric}One statistics group for all indicesMetrics include docs, store, indexing, search, merge, refresh, flush, segments and translog.
GET /{index}/_statsStatistics for chosen indicesFor a data stream the numbers come from its backing indices.
GET /{index}/_stats/{metric}One statistics group for chosen indicesThe narrow form, for example the store or search numbers of a single index.
GET /_segmentsSegments of all indicesJSON counterpart of the cat segments table.
GET /{index}/_segmentsSegments of chosen indicesLow-level Lucene segment details for the shards of the named targets.
GET /_recoveryShard recoveries on all indicesReports ongoing and completed recoveries; active_only=true hides the finished ones.
GET /_recovery?humanRecoveries with readable unitsThe human flag adds sizes and times in a readable form.
GET /{index}/_recoveryShard recoveries of chosen indicesAdd detailed=true for more information on each recovery.
GET /_shard_storesShard store informationBy default limited to unassigned primaries and to primaries with unassigned replicas.
GET /_shard_stores?status=greenShard stores of healthy shardsstatus accepts green, yellow, red or all to widen the default selection.
GET /{index}/_shard_storesShard stores of chosen indicesShows which nodes hold a copy of each shard and any error hit while opening it.
POST /{index}/_disk_usageDisk usage per fieldExperimental and resource-intensive: it runs only when ?run_expensive_tasks=true is added.
GET /{index}/_field_usage_statsField usage per shardExperimental: counts how often searches touched each field's data structures.

Mappings, settings and analysis 18

CommandWhat it does
GET /_mappingMappings of all indicesReturns the field mappings of every index in one response.
GET /{index}/_mappingMappings of chosen indicesFor a data stream it returns the mappings of the backing indices.
PUT /{index}/_mappingAdd fields to a mappingAdds new fields or properties to existing indices; changing an existing field type needs a reindex.
GET /_mapping/field/{fields}Mapping of single fieldsHandy when the full mapping is large and only a few fields matter.
GET /{index}/_mapping/field/{fields}Field mapping in chosen indicesLooks the listed fields up in the named targets only.
GET /_settingsSettings of all indicesExplicit settings only, unless include_defaults=true is added.
GET /{index}/_settingsSettings of chosen indicesflat_settings=true returns dotted keys instead of nested objects.
GET /my-index/_settings?flat_settings=true&include_defaults=trueIndex settings with defaultsEvery setting of one index in dotted form, including values it only inherits as defaults.
GET /{index}/_settings/{name}Named settings of chosen indicesThe last segment takes setting names or a wildcard expression.
GET /_all/_settings?expand_wildcards=all&filter_path=*.settings.index.*.slowlogSlow log settings of every indexCombines the _all target with filter_path so only the slowlog branch comes back.
PUT /{index}/_settingsChange settings of chosen indicesChanges dynamic settings on live indices; a null value restores the default.
PUT /_settingsChange settings on all indicesApplies the same dynamic setting change to every index at once.
GET /_analyzeTest an analyzer on textReturns the tokens that an analyzer, tokenizer or filter chain produces for sample text.
GET /{index}/_analyzeAnalyze with an index's analyzersDerives the analyzer from that index unless the request names an analyzer or a field.
POST /{index}/_reload_search_analyzersReload search analyzersPicks up changed synonym files of updateable filters; clear the request cache afterwards.
POST /_field_capsField capabilities across indicesCompares how fields are mapped across many indices; data streams answer through their backing indices.
POST /{index}/_field_capsField capabilities of chosen indicesRuntime fields are reported like any other field.
POST /my-index-*/_field_caps?fields=ratingCapabilities of one fieldfields takes the field names or patterns to look up.

Aliases 9

CommandWhat it does
GET /_aliasList all aliasesWith no name in the path it returns every data stream and index alias.
GET /_alias/{name}Look up aliases by nameAccepts several names or wildcards separated by commas.
GET /{index}/_aliasAliases of chosen indicesLists what points at the named data streams or indices.
GET /{index}/_alias/{name}Check an alias on an indexNarrows the lookup to given aliases on given targets.
HEAD /_alias/{name}Check that an alias existsAnswers with a status code alone, without a response body.
HEAD /{index}/_alias/{name}Check an alias on chosen indicesTests whether the alias points at those particular targets.
PUT /{index}/_alias/{name}Add an aliasPoints the alias at the listed data streams or indices and creates it if missing.
DELETE /{index}/_alias/{name}Remove an aliasDetaches the alias from the named data streams or indices.
POST /_aliasesChange aliases in one requestTakes a list of alias actions in the request body instead of naming index and alias in the URL.

Index and component templates 15

CommandWhat it does
GET /_index_templateList index templatesWith no name in the path every composable template is returned.
GET /_index_template/{name}Show index templates by nameAccepts a name or wildcard expression.
PUT /_index_template/{name}Create or replace an index templateDefines settings, mappings and aliases for new indices matching its patterns; existing indices are not changed.
DELETE /_index_template/{name}Delete an index templateSeveral names may be listed with commas, but then wildcards are not supported.
HEAD /_index_template/{name}Check that an index template existsAnswers through the status code alone, which suits scripts.
POST /_index_template/_simulate_index/{name}Simulate an index nameShows the settings, mappings and aliases an index of that name would get from the matching template.
POST /_index_template/_simulate/{name}Simulate an existing templateShows the configuration a stored template would apply.
POST /_index_template/_simulateSimulate a template from the bodyTests a template definition before it is added to the cluster.
GET /_component_templateList component templatesWithout a name it returns all of them; a name or wildcard narrows the list.
GET /_component_template/{name}Show component templates by nameAccepts a name or wildcard expression.
PUT /_component_template/{name}Create or replace a component templateA reusable block of mappings, settings and aliases that index templates list under composed_of.
DELETE /_component_template/{name}Delete component templates
HEAD /_component_template/{name}Check that a component template existsTells through the status code whether that building block is defined.
GET /_templateList legacy index templatesLegacy templates are deprecated in favour of the composable templates introduced in 7.8.
DELETE /_template/{name}Delete a legacy templateCleans up a template of the deprecated legacy kind.

Data streams 19

CommandWhat it does
PUT /_data_stream/{name}Create a data streamNeeds a matching index template that has data streams enabled.
GET /_data_streamList data streamsWith no name in the path it returns every data stream.
GET /_data_stream/{name}Show chosen data streamsAccepts names and wildcards; verbose=true also computes the maximum timestamp.
DELETE /_data_stream/{name}Delete data streamsRemoves the streams together with their backing indices.
GET /_data_stream/_statsStatistics for all data streamsCovers every data stream in the cluster and needs the monitor index privilege.
GET /_data_stream/{name}/_statsStatistics for chosen data streamsLimits the numbers to the streams named in the path.
POST /_data_stream/_migrate/{name}Turn an alias into a data streamThe alias needs a write index and a @timestamp date field in every index; its indices become hidden backing indices.
POST /_data_stream/_modifyModify data streams atomicallyRuns the list of actions in the body as a single all-or-nothing change.
GET /_data_stream/{name}/_lifecycleRead the data stream lifecycleShows how the named streams are set up for lifecycle management.
PUT /_data_stream/{name}/_lifecycleSet the data stream lifecycleThe body sets data_retention and can switch the lifecycle off with enabled: false.
DELETE /_data_stream/{name}/_lifecycleRemove the data stream lifecycleAfterwards the data stream lifecycle no longer manages the stream.
GET /{index}/_lifecycle/explainExplain data stream lifecycle stateShows time since creation and rollover, the lifecycle in force and any errors hit while running it.
GET /_lifecycle/statsData stream lifecycle statisticsSummarises the streams that a data stream lifecycle manages; add ?human for readable units.
GET /_data_stream/{name}/_settingsRead data stream settingsShows the setting overrides stored on the stream itself.
PUT /_data_stream/{name}/_settingsOverride data stream settingsTakes precedence over the matching template; applied to backing indices now or at the next rollover.
GET /_data_stream/{name}/_mappingsRead data stream mappingsShows the mapping overrides stored on the stream itself.
PUT /_data_stream/{name}/_mappingsOverride data stream mappingsChanges no existing index; the override reaches write indices created by later rollovers.
GET /_data_stream/{name}/_optionsRead data stream optionsShows the options, such as the failure store configuration, of the named streams.
PUT /_data_stream/{name}/_optionsSet data stream optionsThe body's failure_store object updates the failure store of every stream the name expression matches.

Indexing and reading documents 15

CommandWhat it does
PUT /{index}/_doc/{id}Index a document under an IDAdds the document, or replaces the one already stored under that ID and raises its version.
POST /{index}/_docIndex a document, generated IDEvery call adds a new document under an ID generated for it; the create_doc privilege is enough.
PUT /{index}/_create/{id}Create only if absentAnswers 409 when a document with that ID already exists instead of overwriting it.
GET /{index}/_doc/{id}Fetch a document by IDRealtime by default, so it does not depend on the index refresh interval.
GET /my-index-000001/_doc/1?stored_fields=tags,counterFetch chosen stored fieldsstored_fields names the stored fields to return with the document.
HEAD /{index}/_doc/{id}Check that a document existsStatus 200 when the ID is found and 404 when it is not.
GET /{index}/_source/{id}Fetch only the sourceReturns just the source; _source_includes and _source_excludes filter its fields.
HEAD /{index}/_source/{id}Check that a source existsA source is unavailable when it has been disabled in the mapping.
DELETE /{index}/_doc/{id}Delete a document by IDA data stream cannot be addressed directly: target the backing index that holds the document.
POST /{index}/_update/{id}Partially update a documentMerges the doc object from the body into the stored document or runs a script; upsert covers a missing document.
POST /_bulkBulk writeRuns many index, create, update and delete actions from one newline-delimited JSON body, which must end with a newline.
POST /{index}/_bulkBulk write to a default targetThe path names the data stream, index or alias that the actions in the body work on.
GET /_mgetFetch several documentsThe docs array in the body lists what to fetch; partial results come back if a shard fails.
GET /{index}/_mgetFetch several IDs from one indexWith the index in the path, the body needs only the document IDs.
GET /{index}/_termvectors/{id}Term vectors of a documentReturns terms with positions, offsets and optional statistics for the fields of a single document.

Searching 24

Search is defined for GET and POST on the same paths, and both take the same request body.

CommandWhat it does
GET /_searchSearch every indexThe body carries the Query DSL request; a q parameter with a Lucene query string wins when both are sent.
POST /_searchSearch every index with POSTSame endpoint and body through POST; the two methods are interchangeable here.
GET /{index}/_searchSearch chosen indicesReturns ten hits unless size says otherwise.
POST /{index}/_searchSearch chosen indices with POSTTakes the same body as the GET form: query, aggregations, sort, size, from and the rest.
GET /my-index-000001/_search?from=40&size=20Page through hitsfrom skips hits and size sets the page length; past 10,000 hits use search_after instead.
GET /_countCount documents everywhereWithout a query it counts every document, as a match_all would.
GET /{index}/_countCount matches in chosen indicesTakes a query in the body or a q parameter and returns the number of matches, not the hits.
GET /{index}/_explain/{id}Explain why a document matchesWorks on one document and one query and includes how the score was computed.
GET /_validate/queryValidate a queryChecks a query for errors without executing it.
GET /{index}/_validate/queryValidate against chosen indicesexplain=true details an error and rewrite=true shows the Lucene query that would run.
GET /my-index-000001/_validate/query?q=user.id:kimchyValidate a query stringq carries the query in Lucene query string syntax, so no body is needed.
GET /_msearchRun several searches in one requestThe body alternates header and search lines as NDJSON and has to end with a newline.
GET /{index}/_msearchSeveral searches on a default targetThe path gives the data streams, indices or aliases that the searches run on.
GET /_search/templateSearch with a templateThe body names a stored template by id, or gives one inline as source, plus the params to fill in.
GET /{index}/_search/templateTemplated search on chosen indicesRuns the rendered template against the targets named in the path.
POST /_render/templatePreview a rendered templateReturns the search body a template produces for the given params; nothing is searched.
POST /_render/template/{id}Preview a stored templateRenders the stored search template with that ID.
PUT /_scripts/{id}Save a stored script or templateSaves it under an ID that is unique in the cluster so requests can refer to it.
PUT /_scripts/{id}/{context}Store and compile for a contextCompiles the script in that context straight away, so errors show up when saving.
GET /_scripts/{id}Read a stored scriptWorks for stored search templates as well.
DELETE /_scripts/{id}Delete a stored scriptRemoves a stored script or stored search template by ID.
POST /_scripts/painless/_executeTest a Painless scriptExperimental: runs a script and returns the result, handy without write permission on the cluster.
GET /{index}/_search_shardsSearch shards of chosen indicesWhen a filtered alias is involved, its filter is listed in the indices section.
POST /{index}/_terms_enumTerms matching a prefixBuilt for low-latency autocomplete; can return terms from deleted documents until segments merge.

Reindex and update or delete by query 13

CommandWhat it does
POST /_reindexCopy documents to another indexThe body names source and dest; settings and mappings are not copied, so prepare the destination first.
POST /_reindex?slices=5&refreshReindex in parallel slicesslices splits the job into that many subtasks and refresh makes the result searchable when it ends.
GET /_reindexList running reindex tasksAdded in 9.5; a relocating task is listed once under its original task ID.
GET /_reindex?detailed=true&human=trueRunning reindexes with progressAdds the status block with progress counters and readable start and running times.
GET /_reindex/{task_id}Progress of one reindexKeeps working with the original task ID after the task has moved to another node.
POST /_reindex/{task_id}/_cancelCancel a reindexWaits for the final task state by default; wait_for_completion=false only acknowledges.
POST /_reindex/{task_id}/_rethrottleChange reindex throttlingSet requests_per_second, where -1 removes the limit; a speed-up applies at once.
POST /{index}/_update_by_queryUpdate documents matching a queryWith no query it rewrites every document unchanged, which picks up mapping changes.
POST /my-index-000001/_update_by_query?conflicts=proceedUpdate and skip version conflictsconflicts=proceed carries on where the default, abort, would stop.
POST /_update_by_query/{task_id}/_rethrottleChange update-by-query throttlingA slow-down takes effect only after the current batch, which avoids scroll timeouts.
POST /{index}/_delete_by_queryDelete documents matching a queryWorks from a snapshot of the index; a document changed meanwhile causes a version conflict.
POST /my-index-000001/_delete_by_query?refresh&slices=5Delete by query in slicesParallelises the deletion over five slices and refreshes the shards involved once it completes.
POST /_delete_by_query/{task_id}/_rethrottleChange delete-by-query throttlingSets the documents deleted per second for one running operation.

Tasks 6

The specification still marks the task management API as experimental and warns that it may change in incompatible ways.

CommandWhat it does
GET /_tasksList running tasksGrouped by node unless group_by is set to parents or none.
GET /_tasks?actions=*search&detailedList search tasks in detailactions filters by action name with wildcards; detailed adds a description of each task at extra cost.
GET /_tasks?detailed=true&actions=*/delete/byqueryFind delete-by-query tasksA wildcard action filter that picks out every running delete by query.
GET /_tasks/{task_id}Status of one taskAnswers 404 when the ID is unknown; wait_for_completion=true blocks until the task ends.
POST /_tasks/{task_id}/_cancelCancel a taskThe task may keep running for a while until it can stop safely.
POST /_tasks/_cancelCancel tasks by filterWithout an ID in the path, the nodes, actions and parent_task_id parameters choose what to cancel.

Snapshots and repositories 18

CommandWhat it does
GET /_snapshotList snapshot repositoriesWith no name in the path it returns every registered repository.
GET /_snapshot/{repository}Show chosen repositoriesAccepts several names and wildcards separated by commas.
PUT /_snapshot/{repository}Register a repositoryNeeds writable cluster metadata; the repository is verified on creation unless verify=false is passed.
DELETE /_snapshot/{repository}Unregister a repositoryDrops only the reference: the snapshots stay untouched in their storage location.
POST /_snapshot/{repository}/_verifyVerify a repositoryChecks the repository for common misconfigurations.
POST /_snapshot/{repository}/_cleanupClean up a repositoryDeletes stale data that no existing snapshot references.
POST /_snapshot/{repository}/_analyzeStress-test repository storageRuns read and write operations to detect storage that behaves incorrectly or slowly; defaults are deliberately small.
PUT /_snapshot/{repository}/{snapshot}Take a snapshotThe body can limit it to chosen indices and feature states; the name must be unique in the repository.
PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=trueTake a snapshot and waitwait_for_completion=true holds the response until the snapshot has finished.
GET /_snapshot/{repository}/{snapshot}Show snapshot detailsTakes names, wildcards or lists; meant for finished snapshots rather than shard-level progress.
GET /_snapshot/_statusStatus of running snapshotsWithout a snapshot name it covers only snapshots in progress, which is the preferred use.
GET /_snapshot/{repository}/_statusRunning snapshots in one repositoryNarrows the progress report to a single repository.
GET /_snapshot/{repository}/{snapshot}/_statusShard-level status of a snapshotDescribes every shard taking part, even for snapshots that are no longer running.
POST /_snapshot/{repository}/{snapshot}/_restoreRestore a snapshotRequires a running cluster that has an elected master; close or rename an index that already exists.
POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=trueRestore and waitWith rename_pattern and rename_replacement in the body, indices are restored under new names.
PUT /_snapshot/{repository}/{snapshot}/_clone/{target_snapshot}Clone a snapshotCopies a whole snapshot, or part of one, to a new name inside the same repository.
DELETE /_snapshot/{repository}/{snapshot}Delete snapshotsAccepts a comma-separated list of snapshot names and wildcards.
GET /_featuresFeatures with snapshot stateLists the names that feature_states accepts when a snapshot is created or restored.

Snapshot lifecycle policies 10

CommandWhat it does
GET /_slm/policyList snapshot policiesReturns each policy with details of its most recent snapshot attempts.
GET /_slm/policy/{policy_id}Show chosen snapshot policiesTakes one policy ID or several separated by commas.
PUT /_slm/policy/{policy_id}Create or replace a snapshot policyThe body sets schedule, snapshot name, repository, config and retention; saving again raises the version.
DELETE /_slm/policy/{policy_id}Delete a snapshot policyStops future snapshots but keeps the ones already taken and any in progress.
PUT /_slm/policy/{policy_id}/_executeRun a snapshot policy nowTakes a snapshot immediately instead of waiting for the schedule, for example before an upgrade.
POST /_slm/_execute_retentionApply retention nowRemoves expired snapshots at once rather than at the scheduled retention run.
GET /_slm/statusIs snapshot lifecycle runningShows whether SLM is currently running, for example after a stop request.
GET /_slm/statsSnapshot lifecycle statisticsCounts the actions SLM has taken, overall and per policy.
POST /_slm/startStart snapshot lifecycle managementOnly needed after a manual stop, because SLM starts when the cluster forms.
POST /_slm/stopPause snapshot lifecycle managementFor maintenance windows; snapshots in progress are not interrupted and policies can still be run by hand.

Index lifecycle management 11

CommandWhat it does
GET /_ilm/policyList lifecycle policiesWith no policy name it returns every ILM policy definition.
GET /_ilm/policy/{policy}Show one lifecycle policyLooks a policy up by its identifier.
PUT /_ilm/policy/{policy}Create or replace a lifecycle policyAn existing policy is replaced and its version goes up; older versions are not kept.
DELETE /_ilm/policy/{policy}Delete a lifecycle policyFails while any index is still managed by the policy.
GET /{index}/_ilm/explainExplain lifecycle stateShows when each index entered its lifecycle state and any failure; only_errors=true keeps just indices in error.
POST /{index}/_ilm/retryRetry a failed lifecycle stepFor indices in the ERROR step: reruns the step where the failure happened.
POST /_ilm/move/{index}Jump to a lifecycle stepExpert call that can lose data; the body must give both current_step and next_step.
POST /{index}/_ilm/removeDetach the lifecycle policyILM stops managing the index or the backing indices of the data stream.
GET /_ilm/statusIs ILM runningUse it after a stop request to see whether ILM has actually halted.
POST /_ilm/stopPause ILMKeeps ILM from acting during maintenance; in-progress operations finish first.
POST /_ilm/startResume ILMNeeded only after a stop, since ILM starts by itself when the cluster forms.

Ingest pipelines 7

CommandWhat it does
GET /_ingest/pipelineList ingest pipelinesReturns every pipeline definition; summary=true shortens the output.
GET /_ingest/pipeline/{id}Show chosen pipelinesAccepts pipeline IDs and wildcards separated by commas.
PUT /_ingest/pipeline/{id}Create or replace a pipelineThe body holds a description and the processors list; the change is live immediately.
DELETE /_ingest/pipeline/{id}Delete pipelinesTakes an ID or wildcard; an asterisk removes every pipeline in the cluster.
POST /_ingest/pipeline/_simulateTest a pipeline definitionRuns the pipeline given in the body against the sample docs, so nothing has to be stored first.
POST /_ingest/pipeline/{id}/_simulateTest a stored pipelineRuns sample docs through an existing pipeline; verbose=true shows the output of each processor.
GET /_ingest/geoip/statsGeoIP download statisticsReports on the GeoIP2 databases downloaded for the geoip processor.

Users and authentication 15

CommandWhat it does
GET /_security/_authenticateWho am IReturns the username, roles, metadata and realm of the credentials sent; 401 if they are not valid.
GET /_security/userList usersCovers native realm users and the built-in users.
GET /_security/user/{username}Show chosen usersAccepts several usernames separated by commas.
POST /_security/user/{username}Create or update a userA password is required for a new user and optional when changing an existing one.
DELETE /_security/user/{username}Delete a userWorks on users of the native realm.
PUT /_security/user/{username}/_disableDisable a userRevokes access without deleting the account.
PUT /_security/user/{username}/_enableEnable a userReverses a disable; new users start out enabled.
POST /_security/user/{username}/_passwordChange a user's passwordWorks for native realm users and built-in users.
POST /_security/user/_passwordChange your own passwordWith no username in the path it applies to the user making the request.
GET /_security/user/_privilegesShow your own privilegesLists what the logged-in user may do; other users can be inspected only through run as.
GET /_security/user/_has_privilegesTest for specific privilegesThe body lists the cluster, index and application privileges to test for the current user.
POST /_security/oauth2/tokenGet a bearer tokenWorks like an OAuth 2.0 token endpoint with a JSON body; the token service needs TLS on HTTP.
DELETE /_security/oauth2/tokenInvalidate a tokenThe body names a token or refresh_token, or a realm_name or username whose tokens should all go.
POST /_security/realm/{realms}/_clear_cacheClear cached users of a realmEvicts cached credentials; an asterisk clears all realms.
GET /_ssl/certificatesTLS certificates in useLists the X.509 certificates of the transport and HTTP layers and of realms, including trusted ones.

Roles and role mappings 9

CommandWhat it does
GET /_security/roleList rolesReturns roles of the native realm; roles defined in files are not included.
GET /_security/role/{name}Show chosen rolesAccepts several role names separated by commas.
POST /_security/role/{name}Create or update a roleThe body grants cluster privileges, index privileges, application privileges and run_as.
DELETE /_security/role/{name}Delete a roleRoles that come from a roles file cannot be deleted this way.
GET /_security/privilege/_builtinList built-in privilegesShows the cluster and index privilege names this version understands.
GET /_security/role_mappingList role mappingsA role mapping ties users to roles through rules; mappings kept in files are not listed.
GET /_security/role_mapping/{name}Show a role mapping by nameThe name is only an identifier and has no effect on what the mapping does.
POST /_security/role_mapping/{name}Create or update a role mappingThe body pairs rules that identify users with the roles those users get.
DELETE /_security/role_mapping/{name}Delete a role mappingRemoves a mapping created through the API, not one from a file.

API keys 8

CommandWhat it does
POST /_security/api_keyCreate an API keyReturns the key, its id and name; keys never expire unless the body sets expiration.
GET /_security/api_keyLook up API keysWith only manage_own_api_key you see your own keys; filter by id, name, owner, realm_name or username.
GET /_security/api_key?username=myuser&realm_name=native1API keys of one userCombines the username and realm_name filters.
PUT /_security/api_key/{id}Update an API keyChanges role_descriptors, metadata or expiration of a key you own.
POST /_security/api_key/_bulk_updateUpdate several API keysApplies one change to many keys; an API key cannot authenticate this call.
DELETE /_security/api_keyInvalidate API keysThe body picks keys by ids, name, owner, realm_name or username; invalidated keys stop authenticating.
POST /_security/api_key/grantCreate a key for another userThe caller supplies that user's credentials or access token in the body.
GET /_security/_query/api_keySearch API keysPaginated listing with an optional query, sort and aggregations in the body.

ES|QL and SQL queries 12

CommandWhat it does
POST /_queryES|QL query, synchronousThe query string goes in the body's query field; format picks csv, json, tsv, txt, yaml and others.
POST /_query/asyncES|QL query, asynchronousSame body as the synchronous call plus wait_for_completion_timeout, keep_alive and keep_on_completion.
GET /_query/async/{id}Fetch async ES|QL resultsReturns status and whatever results exist; only the submitting user can read them.
POST /_query/async/{id}/stopStop an async ES|QL queryInterrupts execution and returns the rows gathered so far.
DELETE /_query/async/{id}Delete async ES|QL resultsCancels a running query or removes its stored results.
POST /_sqlRun an SQL queryThe body's query field holds the statement; large results continue through a cursor.
POST /_sql?format=txtSQL result as a text tableformat switches the response from JSON to another representation such as txt.
POST /_sql/translateTranslate SQL to Query DSLReturns the search request the statement would run, without executing it.
POST /_sql/closeClose an SQL cursorReleases a paging cursor that will not be read to the end.
GET /_sql/async/{id}Fetch async SQL resultsWorks for async searches and for stored synchronous ones.
GET /_sql/async/status/{id}Check async SQL statusReports whether the search is still running.
DELETE /_sql/async/delete/{id}Delete async SQL resultsCancels it if still running and removes the stored result.

Notes

Reading the table

Paths in braces are parameters: GET /{index} means GET /my-index. Rows with literal names such as my-index-000001 or my_repository are request examples copied from the specification or the Elastic troubleshooting guide, kept because they show useful query parameters. Many routes exist cluster-wide and again with an /{index} prefix that scopes them to chosen indices. Underscore-prefixed segments — _search, _cat, _cluster — are APIs; anything without an underscore is an index name. Where the specification defines a route for two methods (GET and POST for searches, PUT and POST for most writes), the table shows the one its own examples use.

The operator's dozen

GET /_cluster/health is the first call in any incident; GET /_cat/indices, GET /_cat/nodes and GET /_cat/allocation give the human-readable tables behind it, and GET /_cluster/allocation/explain says why a shard is unassigned. GET /_cat/pending_tasks and GET /_nodes/hot_threads are the next stops when the cluster is slow. GET /_cluster/settings and PUT /_cluster/settings read and change transient or persistent settings, and GET /_tasks lists long-running operations so they can be cancelled with POST /_tasks/{task_id}/_cancel. Reindex jobs have their own listing from 9.5 on, GET /_reindex.

The developer's dozen

Documents go in through PUT /{index}/_doc/{id} or, for anything more than a handful, POST /_bulk. GET /{index}/_doc/{id} fetches one, POST /{index}/_update/{id} patches one, and POST /{index}/_delete_by_query and POST /{index}/_update_by_query act on everything a query matches. Searching is POST /{index}/_search in practice, with GET /{index}/_count for totals, GET /{index}/_explain/{id} for why a document scored as it did, and POST /{index}/_pit plus search_after for deep pagination instead of scroll. POST /_reindex copies between indices, and PUT /_index_template/{name} defines mappings for indices that do not exist yet.

Newer surfaces

POST /_query runs an ES|QL query, the piped query language, with POST /_query/async for long ones. GET /_health_report goes beyond the three-colour health status and attaches impacts and a diagnosis to each indicator. Data streams carry their own lifecycle, set with PUT /_data_stream/{name}/_lifecycle, plus their own setting and mapping overrides. GET /_migration/deprecations is the pre-upgrade check.

What this page leaves out

The 9.5 specification describes about 600 endpoints; this page keeps the ones an operator or developer types. Not listed: machine learning (including its cat tables), transforms, Watcher, cross-cluster replication, inference, connectors, Fleet, EQL, synonym sets, enrich policies, query rules, search applications, rollup, Logstash pipelines, Graph, streams, autoscaling, node shutdown, dangling indices, searchable snapshots, text structure, profiling and monitoring. Within security, SAML and OpenID Connect sign-in, service accounts, user profiles, application privileges, cross-cluster API keys and enrollment are omitted; within ES|QL, the experimental view, dataset and data source routes. Alternate methods and deprecated path spellings of listed routes are not repeated.

Questions

Why does the table show one method where Elasticsearch accepts two?

The specification defines search-style routes for GET and POST and most write routes for PUT and POST, and both behave the same. To keep the table readable, each route appears once, under the method the specification's own request examples use; GET /_search and POST /_search are both listed as a reminder.

What do the curly braces mean?

A path parameter you replace: {index} is an index name or pattern, {id} a document ID, {name} a template, alias or data stream name, {repository} a snapshot repository. Index, alias and template parameters usually accept comma-separated lists and wildcards.

Which call tells me why a shard is unassigned?

GET /_cluster/allocation/explain, with an optional body naming the index and shard. To see which shards are unassigned first, the troubleshooting guide uses GET /_cat/shards?v=true&h=index,shard,prirep,state,node,unassigned.reason&s=state.

What replaced the scroll API for paging?

A point in time (POST /{index}/_pit) combined with search_after in the search body. Scroll still works, but the specification no longer recommends it for deep pagination.

How do I get column headings in a _cat response?

Add v=true. The same family of parameters shapes every cat table: h picks columns, s sorts by a column, and format=json returns JSON instead of text, as in GET /_cat/health?v=true&format=json.

Which Elasticsearch version do these request lines match?

The 9.5 branch of Elastic's API specification. Routes the specification marks as added in 9.5.0, such as GET /_reindex and POST /_reindex/{task_id}/_cancel, do not exist on older clusters; most other rows go back many versions.

Sources and checks

Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.

375 rows from the earlier version of this page were removed in that check: duplicates, and bindings the documentation does not list or lists differently.

Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.