# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elk Stack Cluster API
  version: 1.0.0
extends: openapi/elk-stack-cluster-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 40
- target: $.paths['/_cluster/allocation/explain'].get
  update:
    x-apievangelist-phrasing:
      intent: Explain why a shard is unassigned or placed
      effect: read
      questions:
      - Why is one of my Elasticsearch shards stuck unassigned?
      - Can I ask the cluster to explain the allocation decision for a specific shard using query-string parameters?
      - How do I see disk usage info alongside a shard allocation explanation?
      instructions:
      - text: Explain why shard {shard} of index {index} is not allocated, passing the details as query parameters.
        slots:
          shard: query.shard
          index: query.index
      - text: Using a GET request, tell me why the first unassigned shard in the cluster can't be placed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/allocation/explain'].post
  update:
    x-apievangelist-phrasing:
      intent: Explain a shard allocation with a request body
      effect: read
      questions:
      - How do I send the index and shard number in a JSON body to get an allocation explanation?
      - Can I find out why a replica shard is sitting on node X instead of moving elsewhere?
      instructions:
      - text: POST an allocation explain for index {index}, shard {shard}, primary {primary}, with the values in the body.
        slots:
          index: requestBody.index
          shard: requestBody.shard
          primary: requestBody.primary
      - text: Explain why the shard currently on node {current_node} is staying there, sending it in the request body.
        slots:
          current_node: requestBody.current_node
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/voting_config_exclusions'].post
  update:
    x-apievangelist-phrasing:
      intent: Exclude master nodes from voting
      effect: write
      questions:
      - How do I safely remove master-eligible nodes from the voting configuration before shutting them down?
      - Can I exclude a master node from voting by its node name rather than its ID?
      instructions:
      - text: Add nodes {node_names} to the voting configuration exclusions.
        slots:
          node_names: query.node_names
      - text: Exclude master-eligible node ID {node_ids} from cluster voting before I decommission it.
        slots:
          node_ids: query.node_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/voting_config_exclusions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear the voting configuration exclusion list
      effect: destructive
      questions:
      - How do I clear the voting exclusions after I've finished removing master nodes?
      - Can I clear voting exclusions without waiting for the excluded nodes to leave the cluster?
      instructions:
      - text: Clear all voting configuration exclusions on the cluster.
      - text: Remove the voting exclusions with wait_for_removal set to {wait_for_removal}.
        slots:
          wait_for_removal: query.wait_for_removal
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cluster-wide settings
      effect: read
      questions:
      - What persistent and transient settings have been set on my cluster?
      - Can I see the default values of cluster settings too, not just the ones I changed?
      instructions:
      - text: Show me the cluster settings that have been explicitly set.
      - text: Get cluster settings including defaults, in flat format {flat_settings}.
        slots:
          flat_settings: query.flat_settings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/settings'].put
  update:
    x-apievangelist-phrasing:
      intent: Update dynamic cluster settings
      effect: write
      questions:
      - How do I change a dynamic cluster setting without restarting nodes?
      - What's the difference between persistent and transient cluster setting updates?
      instructions:
      - text: Apply persistent cluster settings {persistent}.
        slots:
          persistent: requestBody.persistent
      - text: Set transient cluster settings {transient} on the running cluster.
        slots:
          transient: requestBody.transient
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check overall cluster health
      effect: read
      questions:
      - Is my Elasticsearch cluster green, yellow or red right now?
      - Can I wait until the whole cluster reaches yellow status before continuing a script?
      instructions:
      - text: Check the health status of the whole cluster.
      - text: Wait until the cluster reaches {wait_for_status} health, timing out after {timeout}.
        slots:
          wait_for_status: query.wait_for_status
          timeout: query.timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/health/{index}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check health of specific indices or data streams
      effect: read
      questions:
      - What's the health status of just one index or data stream rather than the whole cluster?
      - Can I get shard-level health for a particular index?
      instructions:
      - text: Check the health of index {index}.
        slots:
          index: path.index
      - text: Show shard-level health for data stream {index} with level {level}.
        slots:
          index: path.index
          level: query.level
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_info/{target}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cluster info for a chosen target
      effect: read
      questions:
      - How do I pull cluster info such as HTTP, ingest or script stats for a named target?
      - Which info targets can I request from the _info endpoint?
      instructions:
      - text: Get the cluster info for target {target}.
        slots:
          target: path.target
      - text: Fetch _info for the {target} section of the cluster.
        slots:
          target: path.target
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/pending_tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending cluster-level tasks
      effect: read
      questions:
      - Are there cluster state changes like index creation or mapping updates waiting to be applied?
      - Why do my mapping updates seem queued up on the master node?
      instructions:
      - text: List the pending cluster tasks queued on the master.
      - text: Show pending cluster tasks from the local node only, local={local}.
        slots:
          local: query.local
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_remote/info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get remote cluster connection info
      effect: read
      questions:
      - Which remote clusters are configured for cross-cluster search and are they connected?
      - Can I see the seed endpoints for each remote cluster alias?
      instructions:
      - text: Show me connection details for every configured remote cluster.
      - text: List remote cluster aliases and whether each is connected.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/reroute'].post
  update:
    x-apievangelist-phrasing:
      intent: Manually move or allocate shards
      effect: write
      questions:
      - How do I move a shard from one node to another by hand?
      - Can I retry shards that failed allocation too many times?
      - Is there a dry run to preview a shard reroute before applying it?
      instructions:
      - text: Reroute shards using commands {commands}.
        slots:
          commands: requestBody.commands
      - text: Retry allocation of shards that previously failed, retry_failed={retry_failed}.
        slots:
          retry_failed: query.retry_failed
      - text: Do a dry run of reroute commands {commands} and explain the outcome.
        slots:
          commands: requestBody.commands
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/state'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the full cluster state
      effect: read
      questions:
      - How do I dump the entire internal cluster state for debugging?
      - Can I wait for a particular cluster state metadata version before reading it?
      instructions:
      - text: Get the complete cluster state.
      - text: Fetch the full cluster state once metadata version {wait_for_metadata_version} is reached.
        slots:
          wait_for_metadata_version: query.wait_for_metadata_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/state/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get selected metrics of the cluster state
      effect: read
      questions:
      - Can I pull only the routing table or metadata part of the cluster state?
      - How do I limit the cluster state response to certain metrics to keep it small?
      instructions:
      - text: Get only the {metric} section of the cluster state.
        slots:
          metric: path.metric
      - text: Show cluster state metric {metric} across all indices.
        slots:
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/state/{metric}/{index}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cluster state metrics for specific indices
      effect: read
      questions:
      - What does the cluster state say about the routing of one particular index?
      - Can I filter cluster state metrics down to a list of indices?
      instructions:
      - text: Get cluster state metric {metric} for index {index}.
        slots:
          metric: path.metric
          index: path.index
      - text: Show the {metric} part of the cluster state limited to indices {index}.
        slots:
          metric: path.metric
          index: path.index
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cluster-wide statistics
      effect: read
      questions:
      - How much storage and memory is my whole cluster using, and how many shards does it have?
      - Can cluster stats include figures from remote clusters too?
      instructions:
      - text: 'Give me the cluster-wide stats: shards, store size, JVM and node counts.'
      - text: Get cluster stats including remote clusters, include_remotes={include_remotes}.
        slots:
          include_remotes: query.include_remotes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_cluster/stats/nodes/{node_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get cluster statistics for selected nodes
      effect: read
      questions:
      - Can I compute cluster stats using only a subset of nodes, like the data nodes?
      - What are the cluster statistics restricted to one node filter?
      instructions:
      - text: Get cluster stats computed only from nodes {node_id}.
        slots:
          node_id: path.node_id
      - text: Show store size and JVM usage in cluster stats filtered to node filter {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get basic cluster info from the root endpoint
      effect: read
      questions:
      - What does hitting the root URL of my cluster return?
      - How can I confirm the cluster name from the root endpoint?
      instructions:
      - text: Call the root endpoint and show me the cluster's basic info.
      - text: Get the cluster name and version details from the root path.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/'].head
  update:
    x-apievangelist-phrasing:
      intent: Ping the cluster to see if it is up
      effect: read
      questions:
      - Is my Elasticsearch cluster up and responding?
      - Can I do a lightweight liveness check without fetching a response body?
      instructions:
      - text: Ping the cluster to confirm it's running.
      - text: Send a HEAD request to check the cluster is reachable.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/_repositories_metering/{max_archive_version}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear archived repository metering data
      effect: destructive
      questions:
      - How do I clear old archived snapshot repository metering data from a node?
      - Can I delete repository metering archives up to a certain archive version?
      instructions:
      - text: Clear repositories metering archive on nodes {node_id} up to version {max_archive_version}.
        slots:
          node_id: path.node_id
          max_archive_version: path.max_archive_version
      - text: Purge archived metering for node {node_id} through archive version {max_archive_version}.
        slots:
          node_id: path.node_id
          max_archive_version: path.max_archive_version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/_repositories_metering'].get
  update:
    x-apievangelist-phrasing:
      intent: Get snapshot repository metering counters
      effect: read
      questions:
      - How many requests has each node made against my snapshot repositories?
      - Where can I get the repository metering counters to compute storage request costs?
      instructions:
      - text: Get repositories metering info for nodes {node_id}.
        slots:
          node_id: path.node_id
      - text: Show the snapshot repository request counters on node {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/hot_threads'].get
  update:
    x-apievangelist-phrasing:
      intent: Get hot threads across all nodes
      effect: read
      questions:
      - Which threads are burning CPU across my cluster right now?
      - Can I sample hot threads by wait or block time instead of CPU?
      instructions:
      - text: Show the top hot threads on every node.
      - text: Get the top {threads} hot threads of type {type} across the cluster.
        slots:
          threads: query.threads
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/hot_threads'].get
  update:
    x-apievangelist-phrasing:
      intent: Get hot threads for specific nodes
      effect: read
      questions:
      - What's making one particular node's CPU spike?
      - Can I get hot threads for a single node and skip idle threads?
      instructions:
      - text: Show hot threads on node {node_id}.
        slots:
          node_id: path.node_id
      - text: Sample hot threads on node {node_id} over interval {interval}.
        slots:
          node_id: path.node_id
          interval: query.interval
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get info about every node in the cluster
      effect: read
      questions:
      - What roles, versions and settings do all my cluster nodes have?
      - Which plugins are installed on the nodes in my cluster?
      instructions:
      - text: List information for all nodes in the cluster.
      - text: Get every node's attributes and core settings in flat format.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get info about specific nodes
      effect: read
      questions:
      - What version and roles does a particular node report?
      - How do I look up node information for one node by its ID or name?
      instructions:
      - text: Get node information for node {node_id}.
        slots:
          node_id: path.node_id
      - text: Show the settings and attributes of nodes {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one category of info for all nodes
      effect: read
      questions:
      - Can I get just the JVM or OS section of node info for every node?
      - How do I limit node info to certain metrics like plugins or http?
      instructions:
      - text: Get the {metric} node info for all nodes.
        slots:
          metric: path.metric
      - text: Show only the {metric} section of node information across the cluster.
        slots:
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one category of info for specific nodes
      effect: read
      questions:
      - What JVM details does one specific node report in its node info?
      - Can I combine a node filter and a metric filter in one node info call?
      instructions:
      - text: Get the {metric} node info for node {node_id}.
        slots:
          metric: path.metric
          node_id: path.node_id
      - text: Show node {node_id}'s {metric} information only.
        slots:
          node_id: path.node_id
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/reload_secure_settings'].post
  update:
    x-apievangelist-phrasing:
      intent: Reload keystore secure settings on all nodes
      effect: write
      questions:
      - How do I apply changed keystore settings on every node without a restart?
      - Can I reload a password-protected keystore across the cluster?
      instructions:
      - text: Reload the secure settings keystore on all nodes.
      - text: Reload secure settings cluster-wide using keystore password {secure_settings_password}.
        slots:
          secure_settings_password: requestBody.secure_settings_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/reload_secure_settings'].post
  update:
    x-apievangelist-phrasing:
      intent: Reload keystore secure settings on chosen nodes
      effect: write
      questions:
      - Can I reload the keystore on just one node after editing it?
      - How do I refresh reloadable secure settings on a subset of nodes?
      instructions:
      - text: Reload secure settings on node {node_id}.
        slots:
          node_id: path.node_id
      - text: Reload the keystore on nodes {node_id} with password {secure_settings_password}.
        slots:
          node_id: path.node_id
          secure_settings_password: requestBody.secure_settings_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get statistics for all nodes
      effect: read
      questions:
      - How much heap, disk and CPU is each node in the cluster using?
      - Can I include segment file sizes in the node statistics?
      instructions:
      - text: Get the full statistics for every node in the cluster.
      - text: Show node stats for all nodes including fielddata for fields {fielddata_fields}.
        slots:
          fielddata_fields: query.fielddata_fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get statistics for specific nodes
      effect: read
      questions:
      - What are the resource statistics for a single node?
      - How do I get all stats for one node by name?
      instructions:
      - text: Get all node stats for node {node_id}.
        slots:
          node_id: path.node_id
      - text: Show heap and disk statistics for nodes {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/stats/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one stats metric for all nodes
      effect: read
      questions:
      - Can I pull only JVM or indices stats for every node?
      - How do I limit node statistics to one metric like os or fs?
      instructions:
      - text: Get the {metric} node stats for all nodes.
        slots:
          metric: path.metric
      - text: Show only {metric} statistics across every node.
        slots:
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/stats/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one stats metric for specific nodes
      effect: read
      questions:
      - What are the JVM stats for one particular node?
      - Can I filter node stats by both node and metric in the same call?
      instructions:
      - text: Get {metric} stats for node {node_id}.
        slots:
          metric: path.metric
          node_id: path.node_id
      - text: Show node {node_id}'s {metric} statistics only.
        slots:
          node_id: path.node_id
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/stats/{metric}/{index_metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get index-level node stats for all nodes
      effect: read
      questions:
      - How much memory are segments or the query cache using on each node?
      - Can I break down the indices metric of node stats into sub-metrics like fielddata?
      instructions:
      - text: Get {metric} node stats narrowed to index metric {index_metric} for all nodes.
        slots:
          metric: path.metric
          index_metric: path.index_metric
      - text: Show the {index_metric} index statistics from every node's {metric} stats.
        slots:
          index_metric: path.index_metric
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/stats/{metric}/{index_metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get index-level stats for specific nodes
      effect: read
      questions:
      - How big is the query cache on one specific node?
      - Can I get a single index sub-metric for one node only?
      instructions:
      - text: Get {metric} stats with index metric {index_metric} for node {node_id}.
        slots:
          metric: path.metric
          index_metric: path.index_metric
          node_id: path.node_id
      - text: On node {node_id}, show the {index_metric} figures within its {metric} stats.
        slots:
          node_id: path.node_id
          index_metric: path.index_metric
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get feature usage for all nodes
      effect: read
      questions:
      - Which REST actions have my nodes been serving and how often?
      - Can I see feature usage counts across the whole cluster?
      instructions:
      - text: Get feature usage information for every node.
      - text: Show REST action usage counts cluster-wide.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get feature usage for specific nodes
      effect: read
      questions:
      - Which REST endpoints has a single node been handling?
      - How do I check feature usage on one node by ID?
      instructions:
      - text: Get feature usage for node {node_id}.
        slots:
          node_id: path.node_id
      - text: Show how often REST actions were used on nodes {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/usage/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one usage metric for all nodes
      effect: read
      questions:
      - Can I limit node usage output to only the rest_actions or aggregations metric?
      - What aggregation usage do my nodes report?
      instructions:
      - text: Get the {metric} usage metric for all nodes.
        slots:
          metric: path.metric
      - text: Show node usage restricted to {metric} across the cluster.
        slots:
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_nodes/{node_id}/usage/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one usage metric for specific nodes
      effect: read
      questions:
      - What aggregation usage does one specific node report?
      - Can I filter usage by both a node and a metric at once?
      instructions:
      - text: Get the {metric} usage for node {node_id}.
        slots:
          metric: path.metric
          node_id: path.node_id
      - text: Show node {node_id}'s feature usage limited to {metric}.
        slots:
          node_id: path.node_id
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_info'].get
  update:
    x-apievangelist-phrasing:
      intent: Get general cluster information
      effect: read
      questions:
      - What does the bare _info endpoint return about my cluster?
      - Can I get all cluster info sections without naming a target?
      instructions:
      - text: Call _info with no target and show everything it returns.
      - text: Get the untargeted cluster information summary.
      method: generated
      generated: '2026-09-26'