openapi: 3.1.0
info:
  title: CharmHealth FHIR API
  description: >-
    HL7 FHIR R4 (4.0.1) REST API exposed by CharmHealth EHR conforming to
    the US Core 3.1.1 Implementation Guide. Supports SMART on FHIR
    authorization for patient-facing apps, provider-facing apps, and
    backend services. Resource paths follow FHIR conventions and accept
    standard FHIR search parameters.
  version: '4.0.1'
  contact:
    name: CharmHealth Developer Support
    url: https://www.charmhealth.com/support/
externalDocs:
  description: CharmHealth FHIR API Documentation
  url: https://www.charmhealth.com/resources/fhir/index.html
servers:
  - url: https://ehr2.charmtracker.com/api/ehr/v2/fhir
    description: CharmHealth FHIR Production
tags:
  - name: Patient
    description: Patient demographic resource
  - name: AllergyIntolerance
    description: Patient allergies and intolerances
  - name: Condition
    description: Diagnoses and problems
  - name: Encounter
    description: Patient encounters and visits
  - name: Observation
    description: Vital signs, lab results, and clinical observations
  - name: MedicationRequest
    description: Medication orders
  - name: Immunization
    description: Immunization records
  - name: CarePlan
    description: Care plans
  - name: CareTeam
    description: Care teams
  - name: DocumentReference
    description: Clinical documents
  - name: Practitioner
    description: Care providers
  - name: Organization
    description: Provider organizations
  - name: Appointment
    description: Scheduled appointments
  - name: Capability
    description: Server capability statement
security:
  - smartOnFhir: []
paths:
  /metadata:
    get:
      operationId: getCapabilityStatement
      summary: Get FHIR CapabilityStatement
      tags: [Capability]
      responses:
        '200':
          description: CapabilityStatement resource
  /Patient/{id}:
    get:
      operationId: readPatient
      summary: Read Patient
      tags: [Patient]
      parameters:
        - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Patient resource
  /Patient:
    get:
      operationId: searchPatient
      summary: Search Patient
      tags: [Patient]
      parameters:
        - name: identifier
          in: query
          schema: { type: string }
        - name: name
          in: query
          schema: { type: string }
        - name: birthdate
          in: query
          schema: { type: string, format: date }
        - name: gender
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Patient Bundle
  /AllergyIntolerance:
    get:
      operationId: searchAllergyIntolerance
      summary: Search AllergyIntolerance
      tags: [AllergyIntolerance]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: clinical-status
          in: query
          schema: { type: string }
      responses:
        '200':
          description: AllergyIntolerance Bundle
  /Condition:
    get:
      operationId: searchCondition
      summary: Search Condition
      tags: [Condition]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Condition Bundle
  /Encounter:
    get:
      operationId: searchEncounter
      summary: Search Encounter
      tags: [Encounter]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Encounter Bundle
  /Observation:
    get:
      operationId: searchObservation
      summary: Search Observation
      tags: [Observation]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string }
        - name: code
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Observation Bundle
  /MedicationRequest:
    get:
      operationId: searchMedicationRequest
      summary: Search MedicationRequest
      tags: [MedicationRequest]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string }
      responses:
        '200':
          description: MedicationRequest Bundle
  /Immunization:
    get:
      operationId: searchImmunization
      summary: Search Immunization
      tags: [Immunization]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Immunization Bundle
  /CarePlan:
    get:
      operationId: searchCarePlan
      summary: Search CarePlan
      tags: [CarePlan]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
      responses:
        '200':
          description: CarePlan Bundle
  /CareTeam:
    get:
      operationId: searchCareTeam
      summary: Search CareTeam
      tags: [CareTeam]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
      responses:
        '200':
          description: CareTeam Bundle
  /DocumentReference:
    get:
      operationId: searchDocumentReference
      summary: Search DocumentReference
      tags: [DocumentReference]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: type
          in: query
          schema: { type: string }
      responses:
        '200':
          description: DocumentReference Bundle
  /Practitioner:
    get:
      operationId: searchPractitioner
      summary: Search Practitioner
      tags: [Practitioner]
      parameters:
        - name: identifier
          in: query
          schema: { type: string }
        - name: name
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Practitioner Bundle
  /Organization:
    get:
      operationId: searchOrganization
      summary: Search Organization
      tags: [Organization]
      responses:
        '200':
          description: Organization Bundle
  /Appointment:
    get:
      operationId: searchAppointment
      summary: Search Appointment
      tags: [Appointment]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Appointment Bundle
components:
  parameters:
    idParam:
      name: id
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    smartOnFhir:
      type: oauth2
      description: SMART on FHIR authorization with patient/, user/, and system/ scopes.
      flows:
        authorizationCode:
          authorizationUrl: https://ehr2.charmtracker.com/oauth/v2/auth
          tokenUrl: https://ehr2.charmtracker.com/oauth/v2/token
          scopes:
            launch/patient: Patient context launch
            patient/Patient.read: Read patient demographic data
            patient/Observation.read: Read observations
            patient/Condition.read: Read conditions
            patient/MedicationRequest.read: Read medication orders
            user/*.read: Read all user-accessible resources
        clientCredentials:
          tokenUrl: https://ehr2.charmtracker.com/oauth/v2/token
          scopes:
            system/*.read: Backend services read access