# 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 Synonyms API
  version: 1.0.0
extends: openapi/elk-stack-synonyms-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: 7
- target: $.paths['/_synonyms/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the rules in a synonym set
      effect: read
      questions:
      - What synonym rules are in a particular synonym set?
      - Can I page through a large synonym set?
      instructions:
      - text: Get synonym set {id}.
        slots:
          id: path.id
      - text: Show {size} rules from synonym set {id} starting at {from}.
        slots:
          id: path.id
          size: query.size
          from: query.from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a synonym set
      effect: write
      questions:
      - How do I create a synonym set for my search analyzer?
      - Can I append rules to a synonym set instead of replacing it?
      - How many synonym rules can a single set hold?
      instructions:
      - text: Create synonym set {id} with rules {synonyms_set}.
        slots:
          id: path.id
          synonyms_set: requestBody.synonyms_set
      - text: Add rules {synonyms_set} to synonym set {id} with append {append}.
        slots:
          id: path.id
          synonyms_set: requestBody.synonyms_set
          append: query.append
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a synonym set
      effect: destructive
      questions:
      - How do I delete a synonym set?
      - Why can't I delete a synonym set that an analyzer is using?
      instructions:
      - text: Delete synonym set {id}.
        slots:
          id: path.id
      - text: Remove the unused synonym set {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms/{set_id}/{rule_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single synonym rule
      effect: read
      questions:
      - What does one specific rule in a synonym set say?
      - Can I fetch a synonym rule by its rule id?
      instructions:
      - text: Get rule {rule_id} from synonym set {set_id}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
      - text: Show synonym rule {rule_id} in {set_id}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms/{set_id}/{rule_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a single synonym rule
      effect: write
      questions:
      - How do I add or change one synonym rule without resending the whole set?
      - Do analyzers reload when I update a single synonym rule?
      instructions:
      - text: Set rule {rule_id} in synonym set {set_id} to {synonyms}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
          synonyms: requestBody.synonyms
      - text: Update synonym rule {rule_id} in {set_id} to {synonyms} with refresh {refresh}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
          synonyms: requestBody.synonyms
          refresh: query.refresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms/{set_id}/{rule_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single synonym rule
      effect: destructive
      questions:
      - How do I remove one rule from a synonym set?
      - Can I delete a synonym rule and keep the rest of the set?
      instructions:
      - text: Delete rule {rule_id} from synonym set {set_id}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
      - text: Remove synonym rule {rule_id} in {set_id} with refresh {refresh}.
        slots:
          set_id: path.set_id
          rule_id: path.rule_id
          refresh: query.refresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_synonyms'].get
  update:
    x-apievangelist-phrasing:
      intent: List all synonym sets
      effect: read
      questions:
      - Which synonym sets are defined in my cluster?
      - How many rules does each synonym set have?
      instructions:
      - text: List all synonym sets.
      - text: Show {size} synonym sets starting at {from}.
        slots:
          size: query.size
          from: query.from
      method: generated
      generated: '2026-09-26'