API Evangelist conversational phrasing for Visit Notes Notes v2 API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Visit Notes Notes v2 API
  version: 1.0.0
extends: openapi/elation-health-notes-v2-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: 13
- target: $.paths['/v2/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List visit notes
      effect: read
      questions:
      - How do I list the visit notes written for a patient?
      - Can I filter notes to only drafts or to specific providers?
      - Is the notes list paginated?
      instructions:
      - text: List notes for patient {patient}.
        slots:
          patient: query.patient
      - text: Show draft notes at practice {practice_id} where draft is {is_draft}.
        slots:
          practice_id: query.practice_id
          is_draft: query.is_draft
      - text: List notes written by providers {providers}, {limit} per page.
        slots:
          providers: query.providers
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new sections-based visit note
      effect: write
      questions:
      - What do I need to create a new visit note using a layout?
      - Can I mark a new note confidential and set the exam reason when I create it?
      instructions:
      - text: Create a {category} note for patient {patient} by provider {provider} at practice {practice} using layout {layout_name}.
        slots:
          category: requestBody.category
          patient: requestBody.patient
          provider: requestBody.provider
          practice: requestBody.practice
          layout_name: requestBody.layout_name
      - text: Start a note for patient {patient} with exam reason {exam_reason}, serviced at {serviced_at}.
        slots:
          patient: requestBody.patient
          exam_reason: requestBody.exam_reason
          serviced_at: requestBody.serviced_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a visit note
      effect: read
      questions:
      - Can I read the full sections of one visit note?
      - Why would fetching a note return a 400 error?
      instructions:
      - text: Get note {note_id}.
        slots:
          note_id: path.note_id
      - text: Show me the sections of visit note {note_id}.
        slots:
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a draft visit note
      effect: destructive
      questions:
      - Can I delete a visit note that hasn't been signed?
      - Which notes are allowed to be deleted?
      instructions:
      - text: Delete draft note {note_id}.
        slots:
          note_id: path.note_id
      - text: Discard the unsigned note {note_id}.
        slots:
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a visit note's content
      effect: write
      questions:
      - How do I save edits to a visit note's sections?
      - Do I need a snapshot id to update a note collaboratively?
      instructions:
      - text: Update note {note_id} with content {content_map} against snapshot {snapshot_id}.
        slots:
          note_id: path.note_id
          content_map: requestBody.content_map
          snapshot_id: requestBody.snapshot_id
      - text: Change the exam reason on note {note_id} to {exam_reason}.
        slots:
          note_id: path.note_id
          exam_reason: requestBody.exam_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/amendments'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an amendment to a signed note
      effect: write
      questions:
      - Can I amend a note after it has been signed?
      - What happens if a draft amendment already exists for the note?
      instructions:
      - text: Create an amendment for signed note {note_id}.
        slots:
          note_id: path.note_id
      - text: Open an amendment draft on note {note_id}.
        slots:
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/amendments/{amendment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a note amendment
      effect: read
      questions:
      - Where can I see the contents of an amendment on a note?
      - Can I fetch one specific amendment by its id?
      instructions:
      - text: Get amendment {amendment_id} on note {note_id}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
      - text: Show me what amendment {amendment_id} changed in note {note_id}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/amendments/{amendment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a draft note amendment
      effect: destructive
      questions:
      - Can I throw away an amendment I started but never signed?
      - Is it possible to delete an amendment once it's finalized?
      instructions:
      - text: Delete draft amendment {amendment_id} from note {note_id}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
      - text: Discard the unsigned amendment {amendment_id} on note {note_id}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/amendments/{amendment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a draft note amendment
      effect: write
      questions:
      - How can I change the content of a draft amendment?
      - Can I update the billing or provider on an amendment before signing it?
      instructions:
      - text: Update amendment {amendment_id} on note {note_id} with content {content_map}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
          content_map: requestBody.content_map
      - text: Set the provider on draft amendment {amendment_id} of note {note_id} to {provider}.
        slots:
          amendment_id: path.amendment_id
          note_id: path.note_id
          provider: requestBody.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/doctags'].get
  update:
    x-apievangelist-phrasing:
      intent: List the doctags on a note
      effect: read
      questions:
      - Which document tags are attached to a visit note?
      - Can I see the quality-measure tags on a note?
      instructions:
      - text: List doctags on note {note_id}.
        slots:
          note_id: path.note_id
      - text: Show every document tag attached to note {note_id}.
        slots:
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/doctags'].patch
  update:
    x-apievangelist-phrasing:
      intent: Tag a note with a doctag
      effect: write
      questions:
      - How do I attach a document tag like a MIPS measure to a note?
      - Can I add a coded tag with a SNOMED result code to a visit note?
      instructions:
      - text: Add doctag {id} with value {value} to note {note_id}.
        slots:
          id: requestBody.id
          value: requestBody.value
          note_id: path.note_id
      - text: Tag note {note_id} with code {code} of type {code_type}, doctag {id}, value {value}.
        slots:
          note_id: path.note_id
          code: requestBody.code
          code_type: requestBody.code_type
          id: requestBody.id
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/doctags/{doctag_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a doctag from a note
      effect: destructive
      questions:
      - Can I untag a note that was tagged by mistake?
      - What removes a single document tag from a visit note?
      instructions:
      - text: Remove doctag {doctag_id} from note {note_id}.
        slots:
          doctag_id: path.doctag_id
          note_id: path.note_id
      - text: Untag note {note_id} of tag {doctag_id}.
        slots:
          note_id: path.note_id
          doctag_id: path.doctag_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/notes/{note_id}/edit'].get
  update:
    x-apievangelist-phrasing:
      intent: Open a note for editing and get a snapshot
      effect: write
      questions:
      - How do I get a snapshot id before editing a note?
      - Does opening a note for edit create anything?
      instructions:
      - text: Open note {note_id} for editing.
        slots:
          note_id: path.note_id
      - text: Check out note {note_id} and give me its snapshot id.
        slots:
          note_id: path.note_id
      method: generated
      generated: '2026-09-26'