API Evangelist conversational phrasing for Settings Letters API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Settings Letters API
  version: 1.0.0
extends: openapi/elation-health-letters-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: 5
- target: $.paths['/letters'].get
  update:
    x-apievangelist-phrasing:
      intent: Find patient letters
      effect: read
      questions:
      - Which letters were sent about a patient within a date range?
      - Can I find referral letters addressed to a specific recipient?
      - How do I list every letter my practice has written for one patient?
      instructions:
      - text: Find letters for patient {patient} dated on or after {document_date__gte}.
        slots:
          patient: query.patient
          document_date__gte: query.document_date__gte
      - text: Find letters sent to recipient {recipient_name}.
        slots:
          recipient_name: query.recipient_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a letter
      effect: read
      questions:
      - How do I read the body of a letter I already sent?
      - Can I check whether a letter has been signed and delivered?
      instructions:
      - text: Get letter {id}.
        slots:
          id: path.id
      - text: Show the subject, signer and delivery date of letter {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a letter (PUT)
      effect: write
      questions:
      - Can I rewrite an entire letter, including its referral order, with a full update?
      - What fields must I resend when replacing a letter with PUT?
      instructions:
      - text: Replace letter {id} for patient {patient} at practice {practice} tied to referral order {referral_order}.
        slots:
          id: path.id
          patient: requestBody.patient
          practice: requestBody.practice
          referral_order: requestBody.referral_order
      - text: Fully rewrite letter {id} with subject {subject} and body {body}.
        slots:
          id: path.id
          subject: requestBody.subject
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a letter (PATCH)
      effect: write
      questions:
      - Can I mark a letter as signed and sent out with a PATCH?
      - Is there a patch call to record a letter's delivery date?
      instructions:
      - text: Patch letter {id} for patient {patient}, practice {practice}, referral {referral_order}, signed by {signed_by} on {sign_date}.
        slots:
          id: path.id
          patient: requestBody.patient
          practice: requestBody.practice
          referral_order: requestBody.referral_order
          signed_by: requestBody.signed_by
          sign_date: requestBody.sign_date
      - text: Patch letter {id} to set send out {send_out} and delivery date {delivery_date}.
        slots:
          id: path.id
          send_out: requestBody.send_out
          delivery_date: requestBody.delivery_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/letters/'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a letter to a contact
      effect: write
      questions:
      - How do I send a referral letter about a patient to an outside provider?
      - Can a new letter be linked to an existing referral order?
      instructions:
      - text: Write a letter about patient {patient} from practice {practice} to contact {send_to_contact} for referral {referral_order} saying {body}.
        slots:
          patient: requestBody.patient
          practice: requestBody.practice
          send_to_contact: requestBody.send_to_contact
          referral_order: requestBody.referral_order
          body: requestBody.body
      - text: Create a letter titled {subject} to contact {send_to_contact} with body {body}.
        slots:
          subject: requestBody.subject
          send_to_contact: requestBody.send_to_contact
          body: requestBody.body
      method: generated
      generated: '2026-09-26'