Elastic Stack (ELK Stack) Cluster API
The cluster API from Elastic Stack (ELK Stack) — 35 operation(s) for cluster.
The cluster API from Elastic Stack (ELK Stack) — 35 operation(s) for cluster.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack-cluster-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Elasticsearch Request & Response Specification Cluster API
license:
name: Apache 2.0
url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
version: ''
tags:
- name: cluster
paths:
/_cluster/allocation/explain:
get:
tags:
- cluster
summary: Explain the shard allocations
description: 'Get explanations for shard allocations in the cluster.
This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.
For unassigned shards, it provides an explanation for why the shard is unassigned.
For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.
This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
Refer to the linked documentation for examples of how to troubleshoot allocation issues using this API.'
externalDocs:
description: Cluster allocation API examples
url: https://www.elastic.co/docs/troubleshoot/elasticsearch/cluster-allocation-api-examples
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/cluster-allocation-explain.html
operationId: cluster-allocation-explain
parameters:
- $ref: '#/components/parameters/cluster.allocation_explain-index'
- $ref: '#/components/parameters/cluster.allocation_explain-shard'
- $ref: '#/components/parameters/cluster.allocation_explain-primary'
- $ref: '#/components/parameters/cluster.allocation_explain-current_node'
- $ref: '#/components/parameters/cluster.allocation_explain-include_disk_info'
- $ref: '#/components/parameters/cluster.allocation_explain-include_yes_decisions'
- $ref: '#/components/parameters/cluster.allocation_explain-master_timeout'
requestBody:
$ref: '#/components/requestBodies/cluster.allocation_explain'
responses:
'200':
$ref: '#/components/responses/cluster.allocation_explain-200'
x-state: Generally available; Added in 5.0.0
x-metaTags:
- content: Elasticsearch
name: product_name
post:
tags:
- cluster
summary: Explain the shard allocations
description: 'Get explanations for shard allocations in the cluster.
This API accepts the current_node, index, primary and shard parameters in the request body or in query parameters, but not in both at the same time.
For unassigned shards, it provides an explanation for why the shard is unassigned.
For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.
This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.
Refer to the linked documentation for examples of how to troubleshoot allocation issues using this API.'
externalDocs:
description: Cluster allocation API examples
url: https://www.elastic.co/docs/troubleshoot/elasticsearch/cluster-allocation-api-examples
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/cluster-allocation-explain.html
operationId: cluster-allocation-explain-1
parameters:
- $ref: '#/components/parameters/cluster.allocation_explain-index'
- $ref: '#/components/parameters/cluster.allocation_explain-shard'
- $ref: '#/components/parameters/cluster.allocation_explain-primary'
- $ref: '#/components/parameters/cluster.allocation_explain-current_node'
- $ref: '#/components/parameters/cluster.allocation_explain-include_disk_info'
- $ref: '#/components/parameters/cluster.allocation_explain-include_yes_decisions'
- $ref: '#/components/parameters/cluster.allocation_explain-master_timeout'
requestBody:
$ref: '#/components/requestBodies/cluster.allocation_explain'
responses:
'200':
$ref: '#/components/responses/cluster.allocation_explain-200'
x-state: Generally available; Added in 5.0.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/voting_config_exclusions:
post:
tags:
- cluster
summary: Update voting configuration exclusions
description: 'Update the cluster voting config exclusions by node IDs or node names.
By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks.
If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually.
The API adds an entry for each specified node to the cluster’s voting configuration exclusions list.
It then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.
Clusters should have no voting configuration exclusions in normal operation.
Once the excluded nodes have stopped, clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`.
This API waits for the nodes to be fully removed from the cluster before it returns.
If your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.
A response to `POST /_cluster/voting_config_exclusions` with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.
If the call to `POST /_cluster/voting_config_exclusions` fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration.
In that case, you may safely retry the call.
NOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period.
They are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.'
externalDocs:
description: More about node management
url: https://www.elastic.co/docs/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/voting-config-exclusions.html
operationId: cluster-post-voting-config-exclusions
parameters:
- in: query
name: node_names
description: 'A comma-separated list of the names of the nodes to exclude from the
voting configuration. If specified, you may not also specify node_ids.'
deprecated: false
schema:
$ref: '#/components/schemas/_types.Names'
style: form
- in: query
name: node_ids
description: 'A comma-separated list of the persistent ids of the nodes to exclude
from the voting configuration. If specified, you may not also specify node_names.'
deprecated: false
schema:
$ref: '#/components/schemas/_types.Ids'
style: form
- in: query
name: master_timeout
description: Period to wait for a connection to the master node.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
- in: query
name: timeout
description: 'When adding a voting configuration exclusion, the API waits for the
specified nodes to be excluded from the voting configuration before
returning. If the timeout expires before the appropriate condition
is satisfied, the request fails and returns an error.'
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
responses:
'200':
description: ''
content:
application/json: {}
x-state: Generally available; Added in 7.0.0
x-metaTags:
- content: Elasticsearch
name: product_name
delete:
tags:
- cluster
summary: Clear cluster voting config exclusions
description: Remove master-eligible nodes from the voting configuration exclusion list.
externalDocs:
description: More about node management
url: https://www.elastic.co/docs/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/voting-config-exclusions.html
operationId: cluster-delete-voting-config-exclusions
parameters:
- in: query
name: master_timeout
description: Period to wait for a connection to the master node.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
- in: query
name: wait_for_removal
description: 'Specifies whether to wait for all excluded nodes to be removed from the
cluster before clearing the voting configuration exclusions list.
Defaults to true, meaning that all excluded nodes must be removed from
the cluster before this API takes any action. If set to false then the
voting configuration exclusions list is cleared even if some excluded
nodes are still in the cluster.'
deprecated: false
schema:
default: true
type: boolean
style: form
responses:
'200':
description: ''
content:
application/json: {}
x-state: Generally available; Added in 7.0.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/settings:
get:
tags:
- cluster
summary: Get cluster-wide settings
description: 'By default, it returns only settings that have been explicitly defined.
## Required authorization
* Cluster privileges: `monitor`
'
externalDocs:
description: More about Elastic Stack settings
url: https://www.elastic.co/docs/deploy-manage/stack-settings
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/cluster-get-settings.html
operationId: cluster-get-settings
parameters:
- in: query
name: flat_settings
description: If `true`, returns settings in flat format.
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: include_defaults
description: 'If `true`, also returns the values of all other cluster settings set in the
`elasticsearch.yml` file on one of the nodes in your cluster, together with the default
values of all other cluster settings on that node. The default value of each setting may
depend on the values of other settings on that node. If the nodes in your cluster do not all
have the same configuration then the values returned by this API may vary from invocation to
invocation and may not reflect the values that Elasticsearch uses in all situations. Use the
`GET _nodes/settings` API to fetch the settings for each individual node in your cluster.'
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: master_timeout
description: '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.'
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
- in: query
name: timeout
description: 'Period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.'
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
persistent:
description: The settings that persist after the cluster restarts.
type: object
additionalProperties:
type: object
transient:
description: The settings that do not persist after the cluster restarts.
type: object
additionalProperties:
type: object
defaults:
description: The default setting values.
type: object
additionalProperties:
type: object
required:
- persistent
- transient
x-state: Generally available
x-metaTags:
- content: Elasticsearch
name: product_name
put:
tags:
- cluster
summary: Update the cluster settings
description: 'Configure and update dynamic settings on a running cluster.
You can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.
Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.
You can also reset transient or persistent settings by assigning them a null value.
If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.
For example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.
However, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.
TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.
If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.
Only use `elasticsearch.yml` for static cluster settings and node settings.
The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.
WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.
If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.'
externalDocs:
description: More about Elastic Stack settings
url: https://www.elastic.co/docs/deploy-manage/stack-settings
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/cluster-update-settings.html
operationId: cluster-put-settings
parameters:
- in: query
name: flat_settings
description: Return settings in flat format
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: master_timeout
description: The period to wait for a connection to the master node.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
- in: query
name: timeout
description: The period to wait for a response.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
requestBody:
content:
application/json:
schema:
type: object
properties:
persistent:
description: The settings that persist after the cluster restarts.
type: object
additionalProperties:
type: object
transient:
description: The settings that do not persist after the cluster restarts.
type: object
additionalProperties:
type: object
examples:
ClusterPutSettingsRequestExample1:
summary: A simple setting
description: An example of a persistent update.
value: "{\n \"persistent\" : {\n \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n }\n}"
ClusterPutSettingsRequestExample2:
summary: A setting with multiple patterns
description: 'PUT `/_cluster/settings` to update the `action.auto_create_index` setting. The setting accepts a comma-separated list of patterns that you want to allow or you can prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. In this example, the auto-creation of indices called `my-index-000001` or `index10` is allowed, the creation of indices that match the pattern `index1*` is blocked, and the creation of any other indices that match the `ind*` pattern is allowed. Patterns are matched in the order specified.
'
value: "{\n \"persistent\": {\n \"action.auto_create_index\": \"my-index-000001,index10,-index1*,+ind*\" \n }\n}"
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
acknowledged:
type: boolean
persistent:
type: object
additionalProperties:
type: object
transient:
type: object
additionalProperties:
type: object
required:
- acknowledged
- persistent
- transient
x-state: Generally available
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/health:
get:
tags:
- cluster
summary: Get the cluster health status
description: 'You can also use the API to get the health status of only specified data streams and indices.
For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red.
On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.
The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.
The cluster status is controlled by the worst index status.
## Required authorization
* Cluster privileges: `monitor`,`manage`
'
operationId: cluster-health
parameters:
- $ref: '#/components/parameters/cluster.health-expand_wildcards'
- $ref: '#/components/parameters/cluster.health-level'
- $ref: '#/components/parameters/cluster.health-local'
- $ref: '#/components/parameters/cluster.health-master_timeout'
- $ref: '#/components/parameters/cluster.health-timeout'
- $ref: '#/components/parameters/cluster.health-wait_for_active_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_events'
- $ref: '#/components/parameters/cluster.health-wait_for_nodes'
- $ref: '#/components/parameters/cluster.health-wait_for_no_initializing_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_no_relocating_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_status'
responses:
'200':
$ref: '#/components/responses/cluster.health-200'
x-state: Generally available; Added in 1.3.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/health/{index}:
get:
tags:
- cluster
summary: Get the cluster health status
description: 'You can also use the API to get the health status of only specified data streams and indices.
For data streams, the API retrieves the health status of the stream’s backing indices.
The cluster health status is: green, yellow or red.
On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.
The index level status is controlled by the worst shard status.
One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.
The cluster status is controlled by the worst index status.
## Required authorization
* Cluster privileges: `monitor`,`manage`
'
operationId: cluster-health-1
parameters:
- $ref: '#/components/parameters/cluster.health-index'
- $ref: '#/components/parameters/cluster.health-expand_wildcards'
- $ref: '#/components/parameters/cluster.health-level'
- $ref: '#/components/parameters/cluster.health-local'
- $ref: '#/components/parameters/cluster.health-master_timeout'
- $ref: '#/components/parameters/cluster.health-timeout'
- $ref: '#/components/parameters/cluster.health-wait_for_active_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_events'
- $ref: '#/components/parameters/cluster.health-wait_for_nodes'
- $ref: '#/components/parameters/cluster.health-wait_for_no_initializing_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_no_relocating_shards'
- $ref: '#/components/parameters/cluster.health-wait_for_status'
responses:
'200':
$ref: '#/components/responses/cluster.health-200'
x-state: Generally available; Added in 1.3.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_info/{target}:
get:
tags:
- cluster
summary: Get cluster info
description: Returns basic information about the cluster.
operationId: cluster-info
parameters:
- in: path
name: target
description: Limits the information returned to the specific target. Supports a comma-separated list, such as http,ingest.
required: true
deprecated: false
schema:
$ref: '#/components/schemas/_types.ClusterInfoTargets'
style: simple
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
cluster_name:
allOf:
- $ref: '#/components/schemas/_types.Name'
http:
allOf:
- $ref: '#/components/schemas/nodes._types.Http'
ingest:
allOf:
- $ref: '#/components/schemas/nodes._types.Ingest'
thread_pool:
type: object
additionalProperties:
$ref: '#/components/schemas/nodes._types.ThreadCount'
script:
allOf:
- $ref: '#/components/schemas/nodes._types.Scripting'
required:
- cluster_name
x-state: Generally available; Added in 8.9.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/pending_tasks:
get:
tags:
- cluster
summary: Get the pending cluster tasks
description: 'Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.
NOTE: This API returns a list of any pending updates to the cluster state.
These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.
However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.
## Required authorization
* Cluster privileges: `monitor`
'
operationId: cluster-pending-tasks
parameters:
- in: query
name: local
description: 'If `true`, the request retrieves information from the local node only.
If `false`, information is retrieved from the master node.'
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: master_timeout
description: '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.'
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
tasks:
type: array
items:
$ref: '#/components/schemas/cluster.pending_tasks.PendingTask'
required:
- tasks
x-state: Generally available
x-metaTags:
- content: Elasticsearch
name: product_name
/_remote/info:
get:
tags:
- cluster
summary: Get remote cluster information
description: 'Get information about configured remote clusters.
The API returns connection and endpoint information keyed by the configured remote cluster alias.
> info
> This API returns information that reflects current state on the local cluster.
> The `connected` field does not necessarily reflect whether a remote cluster is down or unavailable, only whether there is currently an open connection to it.
> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.
> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).
## Required authorization
* Cluster privileges: `monitor`
'
externalDocs:
description: More about cross-cluster search
url: https://www.elastic.co/docs/solutions/search/cross-cluster-search
x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/cluster-remote-info.html
operationId: cluster-remote-info
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/cluster.remote_info.ClusterRemoteInfo'
x-state: Generally available; Added in 6.1.0
x-metaTags:
- content: Elasticsearch
name: product_name
/_cluster/reroute:
post:
tags:
- cluster
summary: Reroute the cluster
description: 'Manually change the allocation of individual shards in the cluster.
For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.
It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as `cluster.routing.rebalance.enable`) in order to remain in a balanced state.
For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.
The cluster can be set to disable allocations using the `cluster.routing.allocation.enable` setting.
If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.
The cluster will attempt to allocate a shard a maximum of `index.allocation.max_retries` times in a row (defaults to `5`), before giving up and leaving the shard unallocated.
This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.
Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the `?retry_failed` URI query parameter, which will attempt a single retry round for these shards.'
operationId: cluster-reroute
parameters:
- in: query
name: dry_run
description: 'If true, then the request simulates the operation.
It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.'
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: explain
description: If true, then the response contains an explanation of why the commands can or cannot run.
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: metric
description: Limits the information returned to the specified metrics.
deprecated: true
schema:
oneOf:
- type: string
- type: array
items:
type: string
style: form
- in: query
name: retry_failed
description: If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures.
deprecated: false
schema:
default: false
type: boolean
style: form
- in: query
name: master_timeout
description: 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.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
- in: query
name: timeout
description: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
deprecated: false
schema:
default: 30s
allOf:
- $ref: '#/components/schemas/_types.Duration'
style: form
requestBody:
content:
application/json:
schema:
type: object
properties:
commands:
description: D
# --- truncated at 32 KB (304 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-cluster-api-openapi.yml