# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elasticsearch Request & Response Specification Watcher API
  version: 1.0.0
extends: openapi/elk-stack-watcher-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: 24
- target: $.paths['/_watcher/watch/{watch_id}/_ack'].put
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge all actions of a watch (PUT)
      effect: write
      questions:
      - How do I acknowledge a watch with a PUT request so its actions stop firing?
      - Can I throttle every action of a noisy watch by acknowledging it via PUT?
      instructions:
      - text: Acknowledge all actions of watch {watch_id} using PUT.
        slots:
          watch_id: path.watch_id
      - text: Send a PUT acknowledgement for every action on watch {watch_id}.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_ack'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge all actions of a watch (POST)
      effect: write
      questions:
      - How do I acknowledge an entire watch using a POST request?
      - Can I silence all actions of a watch with the POST form of the ack call?
      instructions:
      - text: Acknowledge all actions of watch {watch_id} using POST.
        slots:
          watch_id: path.watch_id
      - text: Send a POST acknowledgement for every action on watch {watch_id}.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_ack/{action_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge one action of a watch (PUT)
      effect: write
      questions:
      - Can I acknowledge just one action of a watch with a PUT request?
      - How do I throttle a single watch action via PUT while others keep running?
      instructions:
      - text: Acknowledge action {action_id} of watch {watch_id} using PUT.
        slots:
          watch_id: path.watch_id
          action_id: path.action_id
      - text: Send a PUT ack for only action {action_id} on watch {watch_id}.
        slots:
          watch_id: path.watch_id
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_ack/{action_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge one action of a watch (POST)
      effect: write
      questions:
      - How do I acknowledge a single named action of a watch using POST?
      - Can I throttle one specific action through the POST ack endpoint?
      instructions:
      - text: Acknowledge action {action_id} of watch {watch_id} using POST.
        slots:
          watch_id: path.watch_id
          action_id: path.action_id
      - text: Send a POST ack for only action {action_id} on watch {watch_id}.
        slots:
          watch_id: path.watch_id
          action_id: path.action_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_activate'].put
  update:
    x-apievangelist-phrasing:
      intent: Activate a watch (PUT)
      effect: write
      questions:
      - How do I turn an inactive watch back on with a PUT request?
      - Can I re-enable a paused watch using PUT?
      instructions:
      - text: Activate watch {watch_id} using PUT.
        slots:
          watch_id: path.watch_id
      - text: Re-enable the inactive watch {watch_id} with a PUT request.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a watch (POST)
      effect: write
      questions:
      - How do I activate a watch with a POST request?
      - Can I switch a watch to active using the POST form?
      instructions:
      - text: Activate watch {watch_id} using POST.
        slots:
          watch_id: path.watch_id
      - text: Re-enable the inactive watch {watch_id} with a POST request.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_deactivate'].put
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a watch (PUT)
      effect: write
      questions:
      - How do I pause a watch with a PUT request without deleting it?
      - Can I make a watch inactive using PUT?
      instructions:
      - text: Deactivate watch {watch_id} using PUT.
        slots:
          watch_id: path.watch_id
      - text: Pause watch {watch_id} with a PUT request so it stops triggering.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{watch_id}/_deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a watch (POST)
      effect: write
      questions:
      - How do I deactivate a watch with a POST request?
      - Can I stop a watch from triggering via the POST deactivate call?
      instructions:
      - text: Deactivate watch {watch_id} using POST.
        slots:
          watch_id: path.watch_id
      - text: Pause watch {watch_id} with a POST request so it stops triggering.
        slots:
          watch_id: path.watch_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a watch definition
      effect: read
      questions:
      - What does a specific watch's trigger, condition and actions look like?
      - Can I fetch one watch and its status by id?
      instructions:
      - text: Get watch {id}.
        slots:
          id: path.id
      - text: Show the definition and status of watch {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a watch (PUT)
      effect: write
      questions:
      - How do I register a new alerting watch with a PUT request?
      - Can I create a watch in an inactive state using PUT?
      - Can I use optimistic concurrency when updating a watch via PUT?
      instructions:
      - text: Create watch {id} with trigger {trigger}, input {input}, condition {condition} and actions {actions} using PUT.
        slots:
          id: path.id
          trigger: requestBody.trigger
          input: requestBody.input
          condition: requestBody.condition
          actions: requestBody.actions
      - text: PUT watch {id} as inactive by setting active to {active}.
        slots:
          id: path.id
          active: query.active
      - text: Update watch {id} via PUT only if its sequence number is {if_seq_no} and primary term {if_primary_term}.
        slots:
          id: path.id
          if_seq_no: query.if_seq_no
          if_primary_term: query.if_primary_term
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a watch (POST)
      effect: write
      questions:
      - How do I register or overwrite a watch with a POST request?
      - Can I set a throttle period when saving a watch through POST?
      instructions:
      - text: Create watch {id} with trigger {trigger}, condition {condition} and actions {actions} using POST.
        slots:
          id: path.id
          trigger: requestBody.trigger
          condition: requestBody.condition
          actions: requestBody.actions
      - text: POST watch {id} with a throttle period of {throttle_period}.
        slots:
          id: path.id
          throttle_period: requestBody.throttle_period
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a watch
      effect: destructive
      questions:
      - How do I permanently remove a watch so it never runs again?
      - Does deleting a watch also delete its execution history?
      instructions:
      - text: Delete watch {id}.
        slots:
          id: path.id
      - text: Remove watch {id} from Watcher permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}/_execute'].put
  update:
    x-apievangelist-phrasing:
      intent: Run a stored watch now (PUT)
      effect: write
      questions:
      - How do I force a stored watch to run immediately with a PUT request?
      - Can I simulate a saved watch's actions via PUT without actually sending them?
      instructions:
      - text: Execute stored watch {id} now using PUT.
        slots:
          id: path.id
      - text: Run watch {id} via PUT ignoring its condition when ignore_condition is {ignore_condition}.
        slots:
          id: path.id
          ignore_condition: requestBody.ignore_condition
      - text: Debug stored watch {id} with PUT, simulating actions {simulated_actions}.
        slots:
          id: path.id
          simulated_actions: requestBody.simulated_actions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/{id}/_execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a stored watch now (POST)
      effect: write
      questions:
      - How do I trigger a saved watch on demand with a POST request?
      - Can I feed alternative input to a stored watch when running it via POST?
      instructions:
      - text: Execute stored watch {id} now using POST.
        slots:
          id: path.id
      - text: Run watch {id} via POST with alternative input {alternative_input}.
        slots:
          id: path.id
          alternative_input: requestBody.alternative_input
      - text: Run watch {id} via POST and record the execution when record_execution is {record_execution}.
        slots:
          id: path.id
          record_execution: requestBody.record_execution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/_execute'].put
  update:
    x-apievangelist-phrasing:
      intent: Test an inline watch definition (PUT)
      effect: write
      questions:
      - Can I try out a watch definition with PUT before saving it?
      - How do I run an unsaved, inline watch using a PUT request?
      instructions:
      - text: Run the inline watch {watch} using PUT without storing it.
        slots:
          watch: requestBody.watch
      - text: Test watch definition {watch} via PUT with debug output {debug}.
        slots:
          watch: requestBody.watch
          debug: query.debug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/watch/_execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Test an inline watch definition (POST)
      effect: write
      questions:
      - How do I execute an ad-hoc watch body with a POST request?
      - Can I dry-run an unsaved watch using the POST execute endpoint?
      instructions:
      - text: Run the inline watch {watch} using POST without storing it.
        slots:
          watch: requestBody.watch
      - text: Dry-run watch definition {watch} via POST with action modes {action_modes}.
        slots:
          watch: requestBody.watch
          action_modes: requestBody.action_modes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Watcher index settings
      effect: read
      questions:
      - How many replicas does the .watches index currently use?
      - What settings can I see on the internal Watcher index?
      instructions:
      - text: Show the Watcher index settings.
      - text: Get the .watches index settings, waiting up to {master_timeout} for the master node.
        slots:
          master_timeout: query.master_timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/settings'].put
  update:
    x-apievangelist-phrasing:
      intent: Update Watcher index settings
      effect: write
      questions:
      - How do I change the replica count of the .watches index?
      - Can I set auto-expand replicas on the Watcher index?
      instructions:
      - text: Set the Watcher index number of replicas to {number_of_replicas}.
        slots:
          number_of_replicas: requestBody.index.number_of_replicas
      - text: Set auto_expand_replicas on the .watches index to {auto_expand_replicas}.
        slots:
          auto_expand_replicas: requestBody.index.auto_expand_replicas
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/_query/watches'].get
  update:
    x-apievangelist-phrasing:
      intent: Search registered watches (GET)
      effect: read
      questions:
      - How do I list all watches page by page with a GET request?
      - Can I filter watches by metadata fields when querying with GET?
      instructions:
      - text: List registered watches with GET, returning {size} at a time.
        slots:
          size: requestBody.size
      - text: Query watches via GET matching {query}.
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/_query/watches'].post
  update:
    x-apievangelist-phrasing:
      intent: Search registered watches (POST)
      effect: read
      questions:
      - How do I query watches with a POST body and sort the results?
      - Can I page past the first results using search_after when querying watches via POST?
      instructions:
      - text: Query watches via POST matching {query}, sorted by {sort}.
        slots:
          query: requestBody.query
          sort: requestBody.sort
      - text: Get the next page of watches via POST after {search_after}.
        slots:
          search_after: requestBody.search_after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/_start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start the Watcher service
      effect: write
      questions:
      - How do I start Watcher if it isn't running?
      - Can I turn the watch service back on for the cluster?
      instructions:
      - text: Start the Watcher service.
      - text: Start Watcher, waiting up to {master_timeout} for the master node.
        slots:
          master_timeout: query.master_timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Watcher statistics
      effect: read
      questions:
      - Is Watcher running and how many watches are executing?
      - Can I include stack traces for executing watches in Watcher stats?
      instructions:
      - text: Show Watcher statistics.
      - text: Get Watcher stats with stack traces when emit_stacktraces is {emit_stacktraces}.
        slots:
          emit_stacktraces: query.emit_stacktraces
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/stats/{metric}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific Watcher statistics metric
      effect: read
      questions:
      - How do I see only the current watches or queued watches metric?
      - Can I ask Watcher for a single named statistics metric?
      instructions:
      - text: Get the Watcher stats metric {metric}.
        slots:
          metric: path.metric
      - text: Show only the {metric} Watcher metric.
        slots:
          metric: path.metric
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_watcher/_stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop the Watcher service
      effect: write
      questions:
      - How do I stop Watcher from running any watches?
      - Can I shut down the watch service during maintenance?
      instructions:
      - text: Stop the Watcher service.
      - text: Stop Watcher, waiting up to {master_timeout} for the master node.
        slots:
          master_timeout: query.master_timeout
      method: generated
      generated: '2026-09-26'