# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Care Gaps Definitions API
  version: 1.0.0
extends: openapi/elation-health-definitions-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: 4
- target: $.paths['/caregaps/api/{quality_program}/definition/'].get
  update:
    x-apievangelist-phrasing:
      intent: List care gap definitions for a quality program
      effect: read
      questions:
      - Which care gap definitions exist for a given quality program?
      - Can I find care gap definitions by closing code or external ID?
      - How do I page through a quality program's gap definitions?
      instructions:
      - text: List care gap definitions for quality program {quality_program}, {page_size} per page.
        slots:
          quality_program: path.quality_program
          page_size: query.page_size
      - text: Find definitions in program {quality_program} named {name}.
        slots:
          quality_program: path.quality_program
          name: query.name
      - text: Look up program {quality_program} definitions with closing code {closing_code}.
        slots:
          quality_program: path.quality_program
          closing_code: query.closing_code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/caregaps/api/{quality_program}/definition/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a care gap definition
      effect: write
      questions:
      - How do I define a new care gap measure for a quality program?
      - Can a care gap definition include closing codes and override reasons?
      instructions:
      - text: 'Create gap definition {name} in {quality_program}: indicator {indicator}, source {source}, selection {selection_behavior}, suggestions {suggestions}.'
        slots:
          name: requestBody.name
          quality_program: path.quality_program
          indicator: requestBody.indicator
          source: requestBody.source
          selection_behavior: requestBody.selection_behavior
          suggestions: requestBody.suggestions
      - text: Add gap definition {name} to program {quality_program} running {start_date} to {end_date}.
        slots:
          name: requestBody.name
          quality_program: path.quality_program
          start_date: requestBody.start_date
          end_date: requestBody.end_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/caregaps/api/{quality_program}/definition/{definition_id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a care gap definition
      effect: read
      questions:
      - What criteria make up one specific care gap definition?
      - Can I see a single definition as it applies to one practice?
      instructions:
      - text: Get care gap definition {definition_id} in program {quality_program}.
        slots:
          definition_id: path.definition_id
          quality_program: path.quality_program
      - text: Show definition {definition_id} of program {quality_program} for practice {practice_id}.
        slots:
          definition_id: path.definition_id
          quality_program: path.quality_program
          practice_id: query.practice_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/caregaps/api/{quality_program}/definition/{definition_id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a care gap definition
      effect: destructive
      questions:
      - Can I retire a care gap definition from a quality program?
      - What happens when I delete a gap definition?
      instructions:
      - text: Delete care gap definition {definition_id} from program {quality_program}.
        slots:
          definition_id: path.definition_id
          quality_program: path.quality_program
      - text: Retire gap measure {definition_id} in quality program {quality_program}.
        slots:
          definition_id: path.definition_id
          quality_program: path.quality_program
      method: generated
      generated: '2026-09-26'