# 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 Snapshot API
  version: 1.0.0
extends: openapi/elk-stack-snapshot-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: 18
- target: $.paths['/_snapshot/{repository}/_cleanup'].post
  update:
    x-apievangelist-phrasing:
      intent: Clean up stale data in a snapshot repository
      effect: destructive
      questions:
      - How do I delete leftover files in a snapshot repository that no snapshot references anymore?
      - What cluster privilege do I need to clean up a snapshot repository?
      instructions:
      - text: Clean up unreferenced data in snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: Purge stale blobs from repository {repository}, waiting up to {timeout} for nodes.
        slots:
          repository: path.repository
          timeout: query.timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}/_clone/{target_snapshot}'].put
  update:
    x-apievangelist-phrasing:
      intent: Clone a snapshot within the same repository
      effect: write
      questions:
      - Can I copy some indices from an existing snapshot into a new snapshot?
      - Does cloning a snapshot have to stay in the same repository?
      instructions:
      - text: Clone snapshot {snapshot} in {repository} to {target_snapshot} with indices {indices}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
          target_snapshot: path.target_snapshot
          indices: requestBody.indices
      - text: Make a copy named {target_snapshot} of just the {indices} indices from snapshot {snapshot} in repo {repository}.
        slots:
          target_snapshot: path.target_snapshot
          indices: requestBody.indices
          snapshot: path.snapshot
          repository: path.repository
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get information about snapshots
      effect: read
      questions:
      - How do I list the snapshots stored in a repository?
      - Can I show only failed or partial snapshots, sorted by start time?
      - Which snapshots were taken by a particular SLM policy?
      instructions:
      - text: List snapshots {snapshot} in repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: Show snapshots in {repository} matching {snapshot} whose state is {state}.
        slots:
          repository: path.repository
          snapshot: path.snapshot
          state: query.state
      - text: Find snapshots {snapshot} in {repository} created by SLM policy {slm_policy_filter}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
          slm_policy_filter: query.slm_policy_filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}'].put
  update:
    x-apievangelist-phrasing:
      intent: Take a snapshot (PUT form)
      effect: write
      questions:
      - How do I back up my cluster's indices to a snapshot repository with a PUT request?
      - Can the PUT snapshot call wait until the snapshot is finished before returning?
      instructions:
      - text: Using PUT, take snapshot {snapshot} in repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: PUT a snapshot {snapshot} of indices {indices} into {repository} and wait for completion.
        slots:
          snapshot: path.snapshot
          indices: requestBody.indices
          repository: path.repository
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}'].post
  update:
    x-apievangelist-phrasing:
      intent: Take a snapshot (POST form)
      effect: write
      questions:
      - Is there a POST variant for creating a snapshot of data streams and indices?
      - Can a snapshot created by POST include the global cluster state?
      instructions:
      - text: Using POST, create snapshot {snapshot} in repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: POST a snapshot {snapshot} to {repository} with include_global_state set to {include_global_state}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
          include_global_state: requestBody.include_global_state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete snapshots
      effect: destructive
      questions:
      - How do I delete old snapshots from a repository?
      - Can I delete several snapshots at once using a wildcard?
      instructions:
      - text: Delete snapshot {snapshot} from repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: Remove every snapshot in {repository} matching {snapshot}.
        slots:
          repository: path.repository
          snapshot: path.snapshot
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get settings of named snapshot repositories
      effect: read
      questions:
      - How do I see the type and settings of one specific snapshot repository?
      - Can I read a named repository's configuration from the local node only?
      instructions:
      - text: Show the configuration of snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: Get repository {repository} settings from the local node when local is {local}.
        slots:
          repository: path.repository
          local: query.local
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}'].put
  update:
    x-apievangelist-phrasing:
      intent: Register or update a snapshot repository (PUT)
      effect: write
      questions:
      - How do I register a new snapshot repository with a PUT request?
      - Can the PUT repository call verify the repository works on every node?
      instructions:
      - text: Using PUT, register snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: PUT an update to repository {repository} with verify set to {verify}.
        slots:
          repository: path.repository
          verify: query.verify
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}'].post
  update:
    x-apievangelist-phrasing:
      intent: Register or update a snapshot repository (POST)
      effect: write
      questions:
      - Is there a POST form for registering a snapshot repository?
      - What must be true of cluster metadata before a repository can be registered via POST?
      instructions:
      - text: Using POST, register or update snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: POST repository {repository} and allow {timeout} for the nodes to respond.
        slots:
          repository: path.repository
          timeout: query.timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unregister snapshot repositories
      effect: destructive
      questions:
      - Does unregistering a snapshot repository delete the snapshots stored in it?
      - How do I remove a snapshot repository from my cluster?
      instructions:
      - text: Unregister snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: Remove the repository references matching {repository} from the cluster.
        slots:
          repository: path.repository
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot'].get
  update:
    x-apievangelist-phrasing:
      intent: List all snapshot repositories
      effect: read
      questions:
      - Which snapshot repositories are registered on my cluster?
      - What repositories can I back up to right now?
      instructions:
      - text: List every registered snapshot repository.
      - text: Show all snapshot repositories as seen by the local node.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/_analyze'].post
  update:
    x-apievangelist-phrasing:
      intent: Stress-test a snapshot repository's storage
      effect: write
      questions:
      - How can I check that my third-party storage behaves correctly as a snapshot repository?
      - Can I control how many blobs and how much data the repository analysis writes?
      instructions:
      - text: Analyze snapshot repository {repository} for incorrect behaviour.
        slots:
          repository: path.repository
      - text: Run a repository analysis on {repository} writing {blob_count} blobs up to {max_total_data_size} total.
        slots:
          repository: path.repository
          blob_count: query.blob_count
          max_total_data_size: query.max_total_data_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/_verify_integrity'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify the integrity of a snapshot repository
      effect: read
      questions:
      - How do I check a repository's contents for corruption that would stop a restore?
      - Can the integrity check verify the checksum of every data blob?
      instructions:
      - text: Verify the integrity of repository {repository}.
        slots:
          repository: path.repository
      - text: Check every blob checksum in {repository} with verify_blob_contents set to {verify_blob_contents}.
        slots:
          repository: path.repository
          verify_blob_contents: query.verify_blob_contents
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}/_restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a snapshot
      effect: write
      questions:
      - How do I restore indices from a snapshot into my running cluster?
      - Can I rename indices as they're restored so they don't clash with existing ones?
      instructions:
      - text: Restore snapshot {snapshot} from repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: Restore indices {indices} from {snapshot} in {repository}, renaming {rename_pattern} to {rename_replacement}.
        slots:
          indices: requestBody.indices
          snapshot: path.snapshot
          repository: path.repository
          rename_pattern: requestBody.rename_pattern
          rename_replacement: requestBody.rename_replacement
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get shard status of all running snapshots
      effect: read
      questions:
      - How do I see shard-level progress for every snapshot currently running?
      - What snapshots are in progress across all repositories right now?
      instructions:
      - text: Show the status of all currently running snapshots.
      - text: Get shard-level progress for every in-flight snapshot in the cluster.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get status of running snapshots in a repository
      effect: read
      questions:
      - Can I check progress only for the snapshots running in one repository?
      - Which in-progress snapshots in a given repository are still copying shards?
      instructions:
      - text: Show the status of running snapshots in repository {repository}.
        slots:
          repository: path.repository
      - text: Get shard progress for in-flight snapshots stored in {repository}.
        slots:
          repository: path.repository
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/{snapshot}/_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get detailed status of specific snapshots
      effect: read
      questions:
      - How do I get the per-shard status of one named snapshot?
      - Can I get per-shard status for a specific snapshot that has already finished?
      instructions:
      - text: Get the detailed status of snapshot {snapshot} in {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      - text: Show shard-by-shard state for snapshots {snapshot} in repository {repository}.
        slots:
          snapshot: path.snapshot
          repository: path.repository
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_snapshot/{repository}/_verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a snapshot repository for misconfiguration
      effect: read
      questions:
      - How do I confirm a newly registered repository is reachable from all nodes?
      - Is there a quick check for common snapshot repository misconfigurations?
      instructions:
      - text: Verify snapshot repository {repository}.
        slots:
          repository: path.repository
      - text: Quick-check {repository} for common misconfigurations.
        slots:
          repository: path.repository
      method: generated
      generated: '2026-09-26'