# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for TextQL v2 Changes API
  version: 1.0.0
extends: openapi/textql-changes-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v2/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: List Ontology changes
      effect: read
      questions:
      - What Ontology changes are open for review in my organization?
      - Can I filter changes by status, like only denied or draft ones?
      - Are auto-approved changes hidden from the change list by default?
      instructions:
      - text: List Ontology changes with status {status}.
        slots:
          status: query.status
      - text: Show {page_size} changes including auto-approved ones.
        slots:
          page_size: query.page_size
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/changes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Ontology change with its diffs
      effect: read
      questions:
      - How do I see the file diffs in a single Ontology change?
      - Where do I get the git ref I need before approving a change?
      instructions:
      - text: Get Ontology change {id}.
        slots:
          id: path.id
      - text: Show revision {revision} of change {id}.
        slots:
          revision: query.revision
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/changes/{id}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve an Ontology change
      effect: write
      questions:
      - How do I approve a change so it merges into the Ontology?
      - Can I approve my own change when the folder rule needs distinct approvers?
      instructions:
      - text: Approve change {id} at git ref {expected_git_ref}.
        slots:
          id: path.id
          expected_git_ref: requestBody.expected_git_ref
      - text: Sign off on Ontology change {id} so it can merge.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/changes/{id}/deny'].post
  update:
    x-apievangelist-phrasing:
      intent: Deny an Ontology change
      effect: write
      questions:
      - How do I reject a proposed Ontology change?
      - Can the author deny their own change?
      instructions:
      - text: Deny change {id} at git ref {expected_git_ref}.
        slots:
          id: path.id
          expected_git_ref: requestBody.expected_git_ref
      - text: Mark Ontology change {id} as denied.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/changes/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Reopen a denied Ontology change
      effect: write
      questions:
      - Can I bring a denied Ontology change back to open?
      - Who is allowed to restore a change that was rejected?
      instructions:
      - text: Restore denied change {id} at git ref {expected_git_ref}.
        slots:
          id: path.id
          expected_git_ref: requestBody.expected_git_ref
      - text: Reopen Ontology change {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'