# 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 Query Rules API
  version: 1.0.0
extends: openapi/elk-stack-query-rules-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: 8
- target: $.paths['/_query_rules/{ruleset_id}/_rule/{rule_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a query rule
      effect: read
      questions:
      - How do I see the criteria and actions of one rule inside a ruleset?
      - What does a specific query rule pin or exclude?
      instructions:
      - text: Get rule {rule_id} from query ruleset {ruleset_id}.
        slots:
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
      - text: Show the criteria and actions for rule {rule_id} in {ruleset_id}.
        slots:
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}/_rule/{rule_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a single query rule
      effect: write
      questions:
      - How do I pin specific documents to the top when a query matches certain criteria?
      - Can I add one rule to a ruleset without resending the whole ruleset?
      - Can a single rule pin by ids and docs at the same time?
      instructions:
      - text: Add a {type} rule {rule_id} to ruleset {ruleset_id} with criteria {criteria} and actions {actions}.
        slots:
          type: requestBody.type
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
          criteria: requestBody.criteria
          actions: requestBody.actions
      - text: Update rule {rule_id} in {ruleset_id} as type {type}, matching {criteria}, doing {actions}, at priority {priority}.
        slots:
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
          type: requestBody.type
          criteria: requestBody.criteria
          actions: requestBody.actions
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}/_rule/{rule_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a query rule
      effect: destructive
      questions:
      - How do I remove one rule from a query ruleset?
      - Can a deleted query rule be recovered?
      instructions:
      - text: Delete rule {rule_id} from query ruleset {ruleset_id}.
        slots:
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
      - text: Remove the single rule {rule_id} but keep the rest of {ruleset_id}.
        slots:
          rule_id: path.rule_id
          ruleset_id: path.ruleset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a query ruleset
      effect: read
      questions:
      - What rules are in a given query ruleset?
      - Can I inspect a whole ruleset by its ID?
      instructions:
      - text: Get query ruleset {ruleset_id}.
        slots:
          ruleset_id: path.ruleset_id
      - text: Show every rule defined in ruleset {ruleset_id}.
        slots:
          ruleset_id: path.ruleset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a query ruleset
      effect: write
      questions:
      - How many rules can one query ruleset hold?
      - How do I create a ruleset that promotes documents for certain searches?
      instructions:
      - text: Create query ruleset {ruleset_id} with rules {rules}.
        slots:
          ruleset_id: path.ruleset_id
          rules: requestBody.rules
      - text: Replace the full set of rules in {ruleset_id} with {rules}.
        slots:
          ruleset_id: path.ruleset_id
          rules: requestBody.rules
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a query ruleset
      effect: destructive
      questions:
      - How do I delete an entire query ruleset and everything in it?
      - Is removing a query ruleset reversible?
      instructions:
      - text: Delete query ruleset {ruleset_id}.
        slots:
          ruleset_id: path.ruleset_id
      - text: Permanently remove ruleset {ruleset_id} with all its rules.
        slots:
          ruleset_id: path.ruleset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List query rulesets
      effect: read
      questions:
      - Which query rulesets exist on my cluster?
      - Can I page through ruleset summaries with from and size?
      instructions:
      - text: List all query rulesets.
      - text: Show {size} rulesets starting at offset {from}.
        slots:
          size: query.size
          from: query.from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query_rules/{ruleset_id}/_test'].post
  update:
    x-apievangelist-phrasing:
      intent: Test which query rules would match
      effect: read
      questions:
      - Which rules in my ruleset would fire for a given user query?
      - Can I dry-run match criteria against a ruleset before going live?
      instructions:
      - text: Test ruleset {ruleset_id} against match criteria {match_criteria}.
        slots:
          ruleset_id: path.ruleset_id
          match_criteria: requestBody.match_criteria
      - text: Show which rules in {ruleset_id} would match {match_criteria}.
        slots:
          ruleset_id: path.ruleset_id
          match_criteria: requestBody.match_criteria
      method: generated
      generated: '2026-09-26'