# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elation Health Handouts API
  version: 1.0.0
extends: openapi/elation-health-handouts-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: 12
- target: $.paths['/handouts/'].get
  update:
    x-apievangelist-phrasing:
      intent: Find patient handouts (legacy)
      effect: read
      questions:
      - How do I search the practice's patient education handouts by name on the older endpoint?
      - Can I filter legacy handouts by tag or by whether my practice created them?
      instructions:
      - text: Find legacy handouts named {name}.
        slots:
          name: query.name
      - text: Search the older handout library for tag {tags}, practice-created only {practice_created}.
        slots:
          tags: query.tags
          practice_created: query.practice_created
      method: generated
      generated: '2026-09-26'
- target: $.paths['/handouts/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a patient handout (legacy)
      effect: write
      questions:
      - How do I add a new patient education handout through the unversioned route?
      - Can a legacy handout carry a VIS barcode for vaccine information statements?
      instructions:
      - text: Create a legacy handout called {name} of type {type} with content {content}.
        slots:
          name: requestBody.name
          type: requestBody.type
          content: requestBody.content
      - text: Add an older-style handout {name} flagged practice-created {practice_created} with VIS barcode {vis_barcode}.
        slots:
          name: requestBody.name
          practice_created: requestBody.practice_created
          vis_barcode: requestBody.vis_barcode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/handouts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one patient handout (legacy)
      effect: read
      questions:
      - How do I open a single handout's content on the older unversioned route?
      - What is stored on one legacy handout record?
      instructions:
      - text: Get legacy handout {id}.
        slots:
          id: path.id
      - text: Open the content of older handout record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/handouts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a patient handout (legacy)
      effect: destructive
      questions:
      - How do I remove an outdated handout using the older delete route?
      - Which unversioned call deletes a handout from the library?
      instructions:
      - text: Delete legacy handout {id}.
        slots:
          id: path.id
      - text: Remove old handout {id} through the unversioned endpoint.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/handouts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a patient handout (legacy)
      effect: write
      questions:
      - Can I rename a handout without resending its content on the older PATCH route?
      - Which legacy call changes just the tags on a handout?
      instructions:
      - text: Rename legacy handout {id} to {name} with a PATCH.
        slots:
          id: path.id
          name: requestBody.name
      - text: Retag older handout {id} with {tags}, leaving everything else alone.
        slots:
          id: path.id
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/handouts/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a patient handout (legacy)
      effect: write
      questions:
      - How do I overwrite a handout's whole content on the unversioned PUT route?
      - What must I resend when replacing a legacy handout in full?
      instructions:
      - text: Replace legacy handout {id} with name {name}, type {type} and content {content}.
        slots:
          id: path.id
          name: requestBody.name
          type: requestBody.type
          content: requestBody.content
      - text: Overwrite old handout {id} completely, practice-created {practice_created}.
        slots:
          id: path.id
          practice_created: requestBody.practice_created
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/'].get
  update:
    x-apievangelist-phrasing:
      intent: List patient handouts with paging
      effect: read
      questions:
      - How do I page through every handout in the v2.0 API?
      - Can I sort v2.0 handouts and filter them by tag?
      instructions:
      - text: List v2.0 handouts tagged {tags}, {limit} per page.
        slots:
          tags: query.tags
          limit: query.limit
      - text: Page through handouts from offset {offset} ordered by {order_by}.
        slots:
          offset: query.offset
          order_by: query.order_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a patient handout in the v2.0 API
      effect: write
      questions:
      - How do I publish a new education handout through /api/2.0?
      - Which fields are required for a v2.0 handout?
      instructions:
      - text: Create v2.0 handout {name} of type {type} containing {content}.
        slots:
          name: requestBody.name
          type: requestBody.type
          content: requestBody.content
      - text: Publish a new /api/2.0 handout with tags {tags} and practice-created {practice_created}.
        slots:
          tags: requestBody.tags
          practice_created: requestBody.practice_created
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a handout from the v2.0 API
      effect: read
      questions:
      - How do I fetch one handout by ID from /api/2.0?
      - Does the v2.0 handout record show when it was received?
      instructions:
      - text: Retrieve v2.0 handout {id}.
        slots:
          id: path.id
      - text: Show the /api/2.0 handout {id} with its type and tags.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a handout in the v2.0 API
      effect: write
      questions:
      - How do I fully replace a handout's content in /api/2.0?
      - Which v2.0 call overwrites every field on a handout?
      instructions:
      - text: Replace v2.0 handout {id} with content {content}, name {name} and type {type}.
        slots:
          id: path.id
          content: requestBody.content
          name: requestBody.name
          type: requestBody.type
      - text: Overwrite /api/2.0 handout {id} entirely, setting practice-created {practice_created}.
        slots:
          id: path.id
          practice_created: requestBody.practice_created
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a handout in the v2.0 API
      effect: destructive
      questions:
      - How do I delete a handout through /api/2.0?
      - Can I retire a handout from the v2.0 library?
      instructions:
      - text: Delete v2.0 handout {id}.
        slots:
          id: path.id
      - text: Retire handout {id} from the /api/2.0 library.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/handouts/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a handout in the v2.0 API
      effect: write
      questions:
      - Can I change just a handout's VIS barcode in /api/2.0?
      - How do I edit one field of a v2.0 handout?
      instructions:
      - text: Set VIS barcode {vis_barcode} on v2.0 handout {id}.
        slots:
          vis_barcode: requestBody.vis_barcode
          id: path.id
      - text: Update only the name of /api/2.0 handout {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'