# 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 Transform API
  version: 1.0.0
extends: openapi/elk-stack-transform-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: 17
- target: $.paths['/_transform/{transform_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transform's configuration
      effect: read
      questions:
      - What source, destination and pivot does a particular transform use?
      - Can I look up several transforms by wildcard?
      instructions:
      - text: Show the configuration of transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Get config for transforms matching {transform_id}.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a transform
      effect: write
      questions:
      - How do I pivot raw events into an entity-centric summary index?
      - Can a new transform keep only the latest document per entity?
      - Can I skip validation when creating a transform?
      instructions:
      - text: Create transform {transform_id} from source {source} into destination {dest}.
        slots:
          transform_id: path.transform_id
          source: requestBody.source
          dest: requestBody.dest
      - text: Create transform {transform_id} reading {source}, writing {dest}, grouped by pivot {pivot}.
        slots:
          transform_id: path.transform_id
          source: requestBody.source
          dest: requestBody.dest
          pivot: requestBody.pivot
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a transform
      effect: destructive
      questions:
      - Can I delete a transform and its destination index together?
      - Is it possible to delete a transform that's still running?
      instructions:
      - text: Delete transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Force-delete {transform_id} and its destination index.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/_node_stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get transform usage per node
      effect: read
      questions:
      - How are transforms distributed across my cluster's nodes?
      - What transform activity is each node handling?
      instructions:
      - text: Show transform node stats.
      - text: Get per-node transform usage.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform'].get
  update:
    x-apievangelist-phrasing:
      intent: List all transforms
      effect: read
      questions:
      - Which transforms exist in my cluster?
      - Can I page through every transform configuration?
      instructions:
      - text: List all transforms.
      - text: List transforms from {from}, {size} at a time.
        slots:
          from: query.from
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transform's stats
      effect: read
      questions:
      - Is my transform running, and how many documents has it processed?
      - Can I get just basic stats to make the call faster?
      instructions:
      - text: Show stats for transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Get basic health and checkpoint stats for {transform_id}.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_preview'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview an existing transform's output
      effect: read
      questions:
      - What results would an existing transform produce right now?
      - How many rows does a transform preview return at most?
      instructions:
      - text: Preview transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Show sample output of saved transform {transform_id} with a GET request.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview an existing transform via POST
      effect: read
      questions:
      - Can I preview a saved transform using a POST request?
      - Which call previews an existing transform with a request body?
      instructions:
      - text: Using POST, preview transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: POST a preview for {transform_id} with a {timeout} timeout.
        slots:
          transform_id: path.transform_id
          timeout: query.timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/_preview'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a draft transform config
      effect: read
      questions:
      - Can I see what a transform would produce before I create it?
      - Does previewing a draft transform also suggest mappings for the destination?
      instructions:
      - text: Preview a transform from {source} pivoted by {pivot}.
        slots:
          source: requestBody.source
          pivot: requestBody.pivot
      - text: Show sample results for a draft transform keeping latest docs per {latest} from {source}.
        slots:
          latest: requestBody.latest
          source: requestBody.source
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/_preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a draft transform config via POST
      effect: read
      questions:
      - Can I POST an unsaved transform definition to preview its results?
      - Which POST call tests a transform config I haven't saved?
      instructions:
      - text: Using POST, preview an unsaved transform from {source} into {dest}.
        slots:
          source: requestBody.source
          dest: requestBody.dest
      - text: POST a draft transform with pivot {pivot} on {source} to preview it.
        slots:
          pivot: requestBody.pivot
          source: requestBody.source
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset a transform
      effect: destructive
      questions:
      - Can I reset a transform so it reprocesses from scratch?
      - Does resetting a transform delete its destination index?
      instructions:
      - text: Reset transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Force-reset running transform {transform_id}.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_schedule_now'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a transform immediately
      effect: write
      questions:
      - Can I make a transform process new data now instead of waiting for its frequency?
      - Is it possible to defer an instant transform run?
      instructions:
      - text: Run transform {transform_id} now.
        slots:
          transform_id: path.transform_id
      - text: Schedule {transform_id} to process new data immediately, deferred by {defer}.
        slots:
          transform_id: path.transform_id
          defer: query.defer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/set_upgrade_mode'].post
  update:
    x-apievangelist-phrasing:
      intent: Toggle transform upgrade mode
      effect: write
      questions:
      - How do I prepare transform indices for a cluster upgrade?
      - Can I turn off transform upgrade mode after upgrading?
      instructions:
      - text: Set transform upgrade mode to {enabled}.
        slots:
          enabled: query.enabled
      - text: Enable cluster-wide transform upgrade mode.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a transform
      effect: write
      questions:
      - Does starting a transform create its destination index automatically?
      - Can I start a transform from a specific point in time?
      instructions:
      - text: Start transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Start {transform_id} processing from {from}.
        slots:
          transform_id: path.transform_id
          from: query.from
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop transforms
      effect: write
      questions:
      - Can I stop a transform after its current checkpoint finishes?
      - Is there a way to stop several transforms at once?
      instructions:
      - text: Stop transform {transform_id}.
        slots:
          transform_id: path.transform_id
      - text: Stop {transform_id} after the next checkpoint and wait for completion.
        slots:
          transform_id: path.transform_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/{transform_id}/_update'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a transform
      effect: write
      questions:
      - When do changes to a running transform take effect?
      - Can I change an existing transform's frequency or destination?
      instructions:
      - text: Update transform {transform_id} to run every {frequency}.
        slots:
          transform_id: path.transform_id
          frequency: requestBody.frequency
      - text: Change the description of existing transform {transform_id} to {description}.
        slots:
          transform_id: path.transform_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_transform/_upgrade'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade all transforms
      effect: write
      questions:
      - How do I bring old transform configurations up to the current format?
      - Can I dry-run a transform upgrade to see what would change?
      instructions:
      - text: Upgrade all transforms to the latest format.
      - text: Do a transform upgrade with dry run set to {dry_run}.
        slots:
          dry_run: query.dry_run
      method: generated
      generated: '2026-09-26'