# 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 Patient Letters (BETA) API
  version: 1.0.0
extends: openapi/elation-health-patient-letters-beta-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: 9
- target: $.paths['/api/2.0/patient-letters/{patient_letters}/comments/'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a patient letter
      effect: read
      questions:
      - What comments have been left on a patient letter?
      - Can I page through comments left on a letter?
      instructions:
      - text: List comments on patient letter {letter}.
        slots:
          letter: path.patient_letters
      - text: Show the first {limit} comments on letter {letter}.
        slots:
          letter: path.patient_letters
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient-letters/{patient_letters}/comments/'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a patient letter
      effect: write
      questions:
      - How do I add a comment to a patient letter?
      - Who must be named as the author when commenting on a letter?
      instructions:
      - text: Add comment {message} to patient letter {letter} as author {author}.
        slots:
          message: requestBody.message
          letter: path.patient_letters
          author: requestBody.author
      - text: Post a note from {author} on letter {letter}.
        slots:
          author: requestBody.author
          letter: path.patient_letters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient-letters/{patient_letters}/comments/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one comment on a patient letter
      effect: read
      questions:
      - Can I read one specific comment on a patient letter?
      - Can I fetch a single letter comment by its id?
      instructions:
      - text: Get comment {id} on patient letter {letter}.
        slots:
          id: path.id
          letter: path.patient_letters
      - text: Show letter {letter}'s comment {id}.
        slots:
          id: path.id
          letter: path.patient_letters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient-letters/{patient_letters}/comments/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on a patient letter
      effect: destructive
      questions:
      - Is there a way to remove a comment from a patient letter?
      - Can I delete a letter comment posted by mistake?
      instructions:
      - text: Delete comment {id} from patient letter {letter}.
        slots:
          id: path.id
          letter: path.patient_letters
      - text: Remove letter {letter}'s comment {id}.
        slots:
          id: path.id
          letter: path.patient_letters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient_letters/'].get
  update:
    x-apievangelist-phrasing:
      intent: List patient letters
      effect: read
      questions:
      - Which patient letters are still unread?
      - How do I list letters exchanged with a patient in both directions?
      - Can I filter patient letters by document date?
      instructions:
      - text: List patient letters for patient {patient}.
        slots:
          patient: query.patient
      - text: Show unread letters in practice {practice}.
        slots:
          practice: query.practice
      - text: List letters dated on or after {date}.
        slots:
          date: query.document_date__gte
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient_letters/'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a patient letter
      effect: write
      questions:
      - How do I draft a letter to a patient?
      - Can a patient be recorded as the author of a letter?
      - Is a new letter sent right away, or does it need signing first?
      instructions:
      - text: Create a letter to patient {patient} in practice {practice} with subject {subject}.
        slots:
          patient: requestBody.patient
          practice: requestBody.practice
          subject: requestBody.subject
      - text: Draft a letter for patient {patient} in practice {practice} saying {body}.
        slots:
          patient: requestBody.patient
          practice: requestBody.practice
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient_letters/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a patient letter
      effect: read
      questions:
      - Where can I open a single patient letter by id?
      - Can I see whether a patient has read a letter?
      instructions:
      - text: Get patient letter {id}.
        slots:
          id: path.id
      - text: Show whether letter {id} was read by the patient.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient_letters/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a patient letter
      effect: write
      questions:
      - Can I rewrite an entire patient letter in one call?
      - Which call replaces every field of a letter rather than patching it?
      instructions:
      - text: Replace patient letter {id} for patient {patient} in practice {practice}.
        slots:
          id: path.id
          patient: requestBody.patient
          practice: requestBody.practice
      - text: Overwrite letter {id} with new body {body}.
        slots:
          id: path.id
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/2.0/patient_letters/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Sign, send or acknowledge a patient letter
      effect: write
      questions:
      - How do I send a patient letter after it has been signed?
      - Can I mark a letter as read by the patient?
      instructions:
      - text: Send signed letter {id} out by setting send_out to {send_out}.
        slots:
          id: path.id
          send_out: requestBody.send_out
      - text: Record that letter {id} was read at {time}.
        slots:
          id: path.id
          time: requestBody.patient_read_time
      - text: Change the subject of letter {id} to {subject}.
        slots:
          id: path.id
          subject: requestBody.subject
      method: generated
      generated: '2026-09-26'