openapi: 3.0.3
info:
  title: Canvas Medical FHIR API
  description: >
    A FHIR R4-compliant REST API providing secure access to electronic health
    record data. Canvas Medical supports 41 FHIR resources (21 with write
    capabilities) covering clinical, administrative, financial, and care
    coordination domains. The API follows the HL7 FHIR R4 specification and
    supports OAuth 2.0 Client Credentials and Authorization Code flows with
    SMART on FHIR scopes for machine-to-machine and user-delegated access.
  version: '4.0'
  contact:
    name: Canvas Medical Support
    url: https://help.canvasmedical.com/
  termsOfService: https://www.canvasmedical.com/
  license:
    name: HL7 FHIR R4
    url: https://hl7.org/fhir/R4/

externalDocs:
  description: Canvas Medical FHIR API Documentation
  url: https://docs.canvasmedical.com/api/

servers:
  - url: https://fumage-{canvas-instance}.canvasmedical.com
    description: FHIR R4 base URL (fumage subdomain)
    variables:
      canvas-instance:
        default: yoursandbox
        description: Your Canvas Medical instance name

security:
  - OAuth2ClientCredentials: []
  - OAuth2AuthCode: []
  - BearerAuth: []

components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: >
        Machine-to-machine authentication using client credentials grant.
        Obtain client_id and client_secret from Canvas admin panel.
      flows:
        clientCredentials:
          tokenUrl: https://{canvas-instance}.canvasmedical.com/auth/token/
          scopes:
            system/*.read: Read all FHIR resources
            system/*.write: Write all FHIR resources
            system/Patient.read: Read Patient resources
            system/Patient.write: Write Patient resources
            system/Appointment.read: Read Appointment resources
            system/Appointment.write: Write Appointment resources
            system/Observation.read: Read Observation resources
            system/Observation.write: Write Observation resources
    OAuth2AuthCode:
      type: oauth2
      description: >
        User-delegated access using Authorization Code flow with SMART on FHIR
        scopes.
      flows:
        authorizationCode:
          authorizationUrl: https://{canvas-instance}.canvasmedical.com/auth/authorize/
          tokenUrl: https://{canvas-instance}.canvasmedical.com/auth/token/
          scopes:
            patient/*.read: Read patient-context FHIR resources
            user/*.read: Read user-context FHIR resources
            user/*.write: Write user-context FHIR resources
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    FHIRResource:
      type: object
      description: Base FHIR R4 resource properties
      properties:
        resourceType:
          type: string
          description: FHIR resource type name
        id:
          type: string
          description: Logical id of this artifact
        meta:
          $ref: '#/components/schemas/Meta'
        text:
          $ref: '#/components/schemas/Narrative'

    Meta:
      type: object
      properties:
        versionId:
          type: string
        lastUpdated:
          type: string
          format: date-time
        source:
          type: string
        profile:
          type: array
          items:
            type: string
        tag:
          type: array
          items:
            $ref: '#/components/schemas/Coding'

    Narrative:
      type: object
      properties:
        status:
          type: string
          enum: [generated, extensions, additional, empty]
        div:
          type: string

    Coding:
      type: object
      properties:
        system:
          type: string
        version:
          type: string
        code:
          type: string
        display:
          type: string
        userSelected:
          type: boolean

    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string

    Reference:
      type: object
      properties:
        reference:
          type: string
        type:
          type: string
        display:
          type: string

    Identifier:
      type: object
      properties:
        use:
          type: string
          enum: [usual, official, temp, secondary, old]
        type:
          $ref: '#/components/schemas/CodeableConcept'
        system:
          type: string
        value:
          type: string
        period:
          $ref: '#/components/schemas/Period'

    Period:
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time

    HumanName:
      type: object
      properties:
        use:
          type: string
          enum: [usual, official, temp, nickname, anonymous, old, maiden]
        text:
          type: string
        family:
          type: string
        given:
          type: array
          items:
            type: string
        prefix:
          type: array
          items:
            type: string
        suffix:
          type: array
          items:
            type: string

    Address:
      type: object
      properties:
        use:
          type: string
          enum: [home, work, temp, old, billing]
        type:
          type: string
          enum: [postal, physical, both]
        text:
          type: string
        line:
          type: array
          items:
            type: string
        city:
          type: string
        district:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string

    ContactPoint:
      type: object
      properties:
        system:
          type: string
          enum: [phone, fax, email, pager, url, sms, other]
        value:
          type: string
        use:
          type: string
          enum: [home, work, temp, old, mobile]

    Bundle:
      type: object
      properties:
        resourceType:
          type: string
          default: Bundle
        id:
          type: string
        type:
          type: string
          enum: [document, message, transaction, transaction-response, batch, batch-response, history, searchset, collection, subscription-notification]
        total:
          type: integer
        link:
          type: array
          items:
            type: object
            properties:
              relation:
                type: string
              url:
                type: string
        entry:
          type: array
          items:
            type: object
            properties:
              fullUrl:
                type: string
              resource:
                $ref: '#/components/schemas/FHIRResource'
              search:
                type: object
                properties:
                  mode:
                    type: string
                    enum: [match, include, outcome]

    OperationOutcome:
      type: object
      properties:
        resourceType:
          type: string
          default: OperationOutcome
        issue:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
                enum: [fatal, error, warning, information]
              code:
                type: string
              details:
                $ref: '#/components/schemas/CodeableConcept'
              diagnostics:
                type: string
              location:
                type: array
                items:
                  type: string

    Patient:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
          properties:
            resourceType:
              type: string
              default: Patient
            identifier:
              type: array
              items:
                $ref: '#/components/schemas/Identifier'
            active:
              type: boolean
            name:
              type: array
              items:
                $ref: '#/components/schemas/HumanName'
            telecom:
              type: array
              items:
                $ref: '#/components/schemas/ContactPoint'
            gender:
              type: string
              enum: [male, female, other, unknown]
            birthDate:
              type: string
              format: date
            deceasedBoolean:
              type: boolean
            deceasedDateTime:
              type: string
              format: date-time
            address:
              type: array
              items:
                $ref: '#/components/schemas/Address'
            extension:
              type: array
              items:
                type: object
              description: Canvas-specific extensions including us-core-race, us-core-ethnicity, us-core-birthsex, preferred-pharmacy

    Appointment:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
          properties:
            resourceType:
              type: string
              default: Appointment
            status:
              type: string
              enum: [proposed, pending, booked, arrived, fulfilled, cancelled, noshow, entered-in-error, checked-in, waitlist]
            serviceType:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            appointmentType:
              $ref: '#/components/schemas/CodeableConcept'
            reasonCode:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
            participant:
              type: array
              items:
                type: object
                properties:
                  actor:
                    $ref: '#/components/schemas/Reference'
                  status:
                    type: string
                    enum: [accepted, declined, tentative, needs-action]

    Observation:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - code
          properties:
            resourceType:
              type: string
              default: Observation
            status:
              type: string
              enum: [registered, preliminary, final, amended, corrected, cancelled, entered-in-error, unknown]
            category:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            code:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            effectiveDateTime:
              type: string
              format: date-time
            valueQuantity:
              type: object
              properties:
                value:
                  type: number
                unit:
                  type: string
                system:
                  type: string
                code:
                  type: string
            valueCodeableConcept:
              $ref: '#/components/schemas/CodeableConcept'
            valueString:
              type: string

    Condition:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - subject
          properties:
            resourceType:
              type: string
              default: Condition
            clinicalStatus:
              $ref: '#/components/schemas/CodeableConcept'
            verificationStatus:
              $ref: '#/components/schemas/CodeableConcept'
            category:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            code:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            onsetDateTime:
              type: string
              format: date-time
            abatementDateTime:
              type: string
              format: date-time

    MedicationRequest:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - intent
            - subject
          properties:
            resourceType:
              type: string
              default: MedicationRequest
            status:
              type: string
              enum: [active, on-hold, cancelled, completed, entered-in-error, stopped, draft, unknown]
            intent:
              type: string
              enum: [proposal, plan, order, original-order, reflex-order, filler-order, instance-order, option]
            medicationCodeableConcept:
              $ref: '#/components/schemas/CodeableConcept'
            medicationReference:
              $ref: '#/components/schemas/Reference'
            subject:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            authoredOn:
              type: string
              format: date-time
            requester:
              $ref: '#/components/schemas/Reference'

    AllergyIntolerance:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - patient
          properties:
            resourceType:
              type: string
              default: AllergyIntolerance
            clinicalStatus:
              $ref: '#/components/schemas/CodeableConcept'
            verificationStatus:
              $ref: '#/components/schemas/CodeableConcept'
            type:
              type: string
              enum: [allergy, intolerance]
            category:
              type: array
              items:
                type: string
                enum: [food, medication, environment, biologic]
            code:
              $ref: '#/components/schemas/CodeableConcept'
            patient:
              $ref: '#/components/schemas/Reference'
            reaction:
              type: array
              items:
                type: object
                properties:
                  manifestation:
                    type: array
                    items:
                      $ref: '#/components/schemas/CodeableConcept'
                  severity:
                    type: string
                    enum: [mild, moderate, severe]

    Encounter:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - class
          properties:
            resourceType:
              type: string
              default: Encounter
            status:
              type: string
              enum: [planned, arrived, triaged, in-progress, onleave, finished, cancelled, entered-in-error, unknown]
            class:
              $ref: '#/components/schemas/Coding'
            type:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            participant:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: array
                    items:
                      $ref: '#/components/schemas/CodeableConcept'
                  individual:
                    $ref: '#/components/schemas/Reference'
            period:
              $ref: '#/components/schemas/Period'

    Task:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - intent
          properties:
            resourceType:
              type: string
              default: Task
            status:
              type: string
              enum: [draft, requested, received, accepted, rejected, ready, cancelled, in-progress, on-hold, failed, completed, entered-in-error]
            intent:
              type: string
              enum: [unknown, proposal, plan, order, original-order, reflex-order, filler-order, instance-order, option]
            code:
              $ref: '#/components/schemas/CodeableConcept'
            description:
              type: string
            focus:
              $ref: '#/components/schemas/Reference'
            for:
              $ref: '#/components/schemas/Reference'
            authoredOn:
              type: string
              format: date-time
            owner:
              $ref: '#/components/schemas/Reference'

    DocumentReference:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - content
          properties:
            resourceType:
              type: string
              default: DocumentReference
            status:
              type: string
              enum: [current, superseded, entered-in-error]
            type:
              $ref: '#/components/schemas/CodeableConcept'
            category:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            date:
              type: string
              format: date-time
            content:
              type: array
              items:
                type: object
                properties:
                  attachment:
                    type: object
                    properties:
                      contentType:
                        type: string
                      data:
                        type: string
                        format: byte
                      url:
                        type: string
                      title:
                        type: string

    Immunization:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - vaccineCode
            - patient
            - occurrenceDateTime
          properties:
            resourceType:
              type: string
              default: Immunization
            status:
              type: string
              enum: [completed, entered-in-error, not-done]
            vaccineCode:
              $ref: '#/components/schemas/CodeableConcept'
            patient:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            occurrenceDateTime:
              type: string
              format: date-time
            primarySource:
              type: boolean

    Practitioner:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          properties:
            resourceType:
              type: string
              default: Practitioner
            identifier:
              type: array
              items:
                $ref: '#/components/schemas/Identifier'
            active:
              type: boolean
            name:
              type: array
              items:
                $ref: '#/components/schemas/HumanName'
            telecom:
              type: array
              items:
                $ref: '#/components/schemas/ContactPoint'
            address:
              type: array
              items:
                $ref: '#/components/schemas/Address'
            qualification:
              type: array
              items:
                type: object
                properties:
                  code:
                    $ref: '#/components/schemas/CodeableConcept'

    Organization:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          properties:
            resourceType:
              type: string
              default: Organization
            identifier:
              type: array
              items:
                $ref: '#/components/schemas/Identifier'
            active:
              type: boolean
            type:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            name:
              type: string
            telecom:
              type: array
              items:
                $ref: '#/components/schemas/ContactPoint'
            address:
              type: array
              items:
                $ref: '#/components/schemas/Address'

    Coverage:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - beneficiary
            - payor
          properties:
            resourceType:
              type: string
              default: Coverage
            status:
              type: string
              enum: [active, cancelled, draft, entered-in-error]
            type:
              $ref: '#/components/schemas/CodeableConcept'
            subscriber:
              $ref: '#/components/schemas/Reference'
            subscriberId:
              type: string
            beneficiary:
              $ref: '#/components/schemas/Reference'
            relationship:
              $ref: '#/components/schemas/CodeableConcept'
            period:
              $ref: '#/components/schemas/Period'
            payor:
              type: array
              items:
                $ref: '#/components/schemas/Reference'

    Goal:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - lifecycleStatus
            - subject
          properties:
            resourceType:
              type: string
              default: Goal
            lifecycleStatus:
              type: string
              enum: [proposed, planned, accepted, active, on-hold, completed, cancelled, entered-in-error, rejected]
            achievementStatus:
              $ref: '#/components/schemas/CodeableConcept'
            description:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            startDate:
              type: string
              format: date
            target:
              type: array
              items:
                type: object
                properties:
                  measure:
                    $ref: '#/components/schemas/CodeableConcept'
                  detailQuantity:
                    type: object
                    properties:
                      value:
                        type: number
                      unit:
                        type: string

    CarePlan:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - intent
            - subject
          properties:
            resourceType:
              type: string
              default: CarePlan
            status:
              type: string
              enum: [draft, active, on-hold, revoked, completed, entered-in-error, unknown]
            intent:
              type: string
              enum: [proposal, plan, order, option]
            title:
              type: string
            description:
              type: string
            subject:
              $ref: '#/components/schemas/Reference'
            period:
              $ref: '#/components/schemas/Period'
            activity:
              type: array
              items:
                type: object

    CareTeam:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          properties:
            resourceType:
              type: string
              default: CareTeam
            status:
              type: string
              enum: [proposed, active, suspended, inactive, entered-in-error]
            name:
              type: string
            subject:
              $ref: '#/components/schemas/Reference'
            participant:
              type: array
              items:
                type: object
                properties:
                  role:
                    type: array
                    items:
                      $ref: '#/components/schemas/CodeableConcept'
                  member:
                    $ref: '#/components/schemas/Reference'

    Questionnaire:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
          properties:
            resourceType:
              type: string
              default: Questionnaire
            url:
              type: string
            title:
              type: string
            status:
              type: string
              enum: [draft, active, retired, unknown]
            item:
              type: array
              items:
                type: object
                properties:
                  linkId:
                    type: string
                  text:
                    type: string
                  type:
                    type: string
                    enum: [group, display, boolean, decimal, integer, date, dateTime, time, string, text, url, choice, open-choice, attachment, reference, quantity]

    QuestionnaireResponse:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
          properties:
            resourceType:
              type: string
              default: QuestionnaireResponse
            questionnaire:
              type: string
            status:
              type: string
              enum: [in-progress, completed, amended, entered-in-error, stopped]
            subject:
              $ref: '#/components/schemas/Reference'
            authored:
              type: string
              format: date-time
            item:
              type: array
              items:
                type: object

    Claim:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - type
            - use
            - patient
            - created
            - provider
            - priority
            - insurance
          properties:
            resourceType:
              type: string
              default: Claim
            status:
              type: string
              enum: [active, cancelled, draft, entered-in-error]
            type:
              $ref: '#/components/schemas/CodeableConcept'
            use:
              type: string
              enum: [claim, preauthorization, predetermination]
            patient:
              $ref: '#/components/schemas/Reference'
            created:
              type: string
              format: date-time
            provider:
              $ref: '#/components/schemas/Reference'
            priority:
              $ref: '#/components/schemas/CodeableConcept'
            insurance:
              type: array
              items:
                type: object

    ServiceRequest:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - intent
            - subject
          properties:
            resourceType:
              type: string
              default: ServiceRequest
            status:
              type: string
              enum: [draft, active, on-hold, revoked, completed, entered-in-error, unknown]
            intent:
              type: string
              enum: [proposal, plan, directive, order, original-order, reflex-order, filler-order, instance-order, option]
            code:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            authoredOn:
              type: string
              format: date-time
            requester:
              $ref: '#/components/schemas/Reference'

    DiagnosticReport:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - code
          properties:
            resourceType:
              type: string
              default: DiagnosticReport
            status:
              type: string
              enum: [registered, partial, preliminary, final, amended, corrected, appended, cancelled, entered-in-error, unknown]
            category:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            code:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            effectiveDateTime:
              type: string
              format: date-time
            result:
              type: array
              items:
                $ref: '#/components/schemas/Reference'

    Location:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          properties:
            resourceType:
              type: string
              default: Location
            status:
              type: string
              enum: [active, suspended, inactive]
            name:
              type: string
            telecom:
              type: array
              items:
                $ref: '#/components/schemas/ContactPoint'
            address:
              $ref: '#/components/schemas/Address'

    Schedule:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - actor
          properties:
            resourceType:
              type: string
              default: Schedule
            active:
              type: boolean
            serviceType:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            actor:
              type: array
              items:
                $ref: '#/components/schemas/Reference'
            planningHorizon:
              $ref: '#/components/schemas/Period'

    Slot:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - schedule
            - status
            - start
            - end
          properties:
            resourceType:
              type: string
              default: Slot
            schedule:
              $ref: '#/components/schemas/Reference'
            status:
              type: string
              enum: [busy, free, busy-unavailable, busy-tentative, entered-in-error]
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time

    Procedure:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - subject
          properties:
            resourceType:
              type: string
              default: Procedure
            status:
              type: string
              enum: [preparation, in-progress, not-done, on-hold, stopped, completed, entered-in-error, unknown]
            code:
              $ref: '#/components/schemas/CodeableConcept'
            subject:
              $ref: '#/components/schemas/Reference'
            encounter:
              $ref: '#/components/schemas/Reference'
            performedDateTime:
              type: string
              format: date-time

    Communication:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
          properties:
            resourceType:
              type: string
              default: Communication
            status:
              type: string
              enum: [preparation, in-progress, not-done, on-hold, stopped, completed, entered-in-error, unknown]
            subject:
              $ref: '#/components/schemas/Reference'
            sent:
              type: string
              format: date-time
            received:
              type: string
              format: date-time
            payload:
              type: array
              items:
                type: object
                properties:
                  contentString:
                    type: string

    Consent:
      allOf:
        - $ref: '#/components/schemas/FHIRResource'
        - type: object
          required:
            - resourceType
            - status
            - scope
            - category
          properties:
            resourceType:
              type: string
              default: Consent
            status:
              type: string
              enum: [draft, proposed, active, rejected, inactive, entered-in-error]
            scope:
              $ref: '#/components/schemas/CodeableConcept'
            category:
              type: array
              items:
                $ref: '#/components/schemas/CodeableConcept'
            patient:
              $ref: '#/components/schemas/Reference'
            dateTime:
              type: string
              format: date-time

    CapabilityStatement:
      type: object
      properties:
        resourceType:
          type: string
          default: CapabilityStatement
        status:
          type: string
        date:
          type: string
          format: date-time
        fhirVersion:
          type: string
        format:
          type: array
          items:
            type: string
        rest:
          type: array
          items:
            type: object

  parameters:
    resourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Logical ID of the FHIR resource
    subject:
      name: subject
      in: query
      schema:
        type: string
      description: Filter by patient reference (e.g. Patient/123)
    patient:
      name: patient
      in: query
      schema:
        type: string
      description: Filter by patient ID or reference
    status:
      name: status
      in: query
      schema:
        type: string
      description: Filter by resource status
    date:
      name: date
      in: query
      schema:
        type: string
      description: Filter by date (FHIR date search parameter)
    count:
      name: _count
      in: query
      schema:
        type: integer
        default: 20
      description: Maximum number of results per page
    pageToken:
      name: _page_token
      in: query
      schema:
        type: string
      description: Pagination token for next page

  responses:
    ResourceNotFound:
      description: Resource not found
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Unauthorized:
      description: Authentication required
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    Forbidden:
      description: Insufficient permissions
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
    UnprocessableEntity:
      description: Validation error
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'

paths:
  /metadata:
    get:
      operationId: getCapabilityStatement
      summary: Get server capability statement
      description: Returns the FHIR CapabilityStatement for the Canvas Medical FHIR server
      tags:
        - Metadata
      security: []
      responses:
        '200':
          description: Capability statement
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/CapabilityStatement'

  /Patient:
    get:
      operationId: searchPatient
      summary: Search Patients
      description: Search for patient records. Supports search by name, birthdate, identifier, gender, and more.
      tags:
        - Patient
      parameters:
        - name: name
          in: query
          schema:
            type: string
          description: Search by patient name (family or given)
        - name: family
          in: query
          schema:
            type: string
        - name: given
          in: query
          schema:
            type: string
        - name: birthdate
          in: query
          schema:
            type: string
            format: date
        - name: gender
          in: query
          schema:
            type: string
            enum: [male, female, other, unknown]
        - name: identifier
          in: query
          schema:
            type: string
          description: Search by identifier (system|value)
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching patients
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPatient
      summary: Create Patient
      description: Create a new patient record in Canvas Medical
      tags:
        - Patient
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '201':
          description: Patient created
          headers:
            Location:
              schema:
                type: string
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Patient/{id}:
    get:
      operationId: readPatient
      summary: Read Patient
      description: Retrieve a specific patient by their logical ID
      tags:
        - Patient
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Patient resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updatePatient
      summary: Update Patient
      description: Update an existing patient record
      tags:
        - Patient
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '200':
          description: Patient updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Appointment:
    get:
      operationId: searchAppointment
      summary: Search Appointments
      description: Search for appointment records
      tags:
        - Appointment
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: date
          in: query
          schema:
            type: string
          description: Appointment date filter
        - name: practitioner
          in: query
          schema:
            type: string
        - name: location
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching appointments
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAppointment
      summary: Create Appointment
      description: Schedule a new appointment
      tags:
        - Appointment
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Appointment'
      responses:
        '201':
          description: Appointment created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Appointment/{id}:
    get:
      operationId: readAppointment
      summary: Read Appointment
      tags:
        - Appointment
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Appointment resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateAppointment
      summary: Update Appointment
      tags:
        - Appointment
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Appointment'
      responses:
        '200':
          description: Appointment updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Observation:
    get:
      operationId: searchObservation
      summary: Search Observations
      description: Search for clinical observations (vitals, lab results, social history)
      tags:
        - Observation
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: category
          in: query
          schema:
            type: string
          description: Observation category (vital-signs, laboratory, survey, etc.)
        - name: code
          in: query
          schema:
            type: string
          description: LOINC or SNOMED code
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching observations
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createObservation
      summary: Create Observation
      tags:
        - Observation
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Observation'
      responses:
        '201':
          description: Observation created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Observation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Observation/{id}:
    get:
      operationId: readObservation
      summary: Read Observation
      tags:
        - Observation
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Observation resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Observation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Condition:
    get:
      operationId: searchCondition
      summary: Search Conditions
      description: Search for patient conditions and problems
      tags:
        - Condition
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: category
          in: query
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching conditions
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCondition
      summary: Create Condition
      tags:
        - Condition
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Condition'
      responses:
        '201':
          description: Condition created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Condition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Condition/{id}:
    get:
      operationId: readCondition
      summary: Read Condition
      tags:
        - Condition
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Condition resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Condition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateCondition
      summary: Update Condition
      tags:
        - Condition
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Condition'
      responses:
        '200':
          description: Condition updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Condition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /MedicationRequest:
    get:
      operationId: searchMedicationRequest
      summary: Search MedicationRequests
      description: Search for medication prescriptions and orders
      tags:
        - MedicationRequest
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: intent
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching medication requests
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createMedicationRequest
      summary: Create MedicationRequest
      tags:
        - MedicationRequest
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/MedicationRequest'
      responses:
        '201':
          description: MedicationRequest created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /MedicationRequest/{id}:
    get:
      operationId: readMedicationRequest
      summary: Read MedicationRequest
      tags:
        - MedicationRequest
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: MedicationRequest resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateMedicationRequest
      summary: Update MedicationRequest
      tags:
        - MedicationRequest
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/MedicationRequest'
      responses:
        '200':
          description: MedicationRequest updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/MedicationRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /AllergyIntolerance:
    get:
      operationId: searchAllergyIntolerance
      summary: Search AllergyIntolerances
      tags:
        - AllergyIntolerance
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching allergy intolerances
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAllergyIntolerance
      summary: Create AllergyIntolerance
      tags:
        - AllergyIntolerance
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/AllergyIntolerance'
      responses:
        '201':
          description: AllergyIntolerance created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/AllergyIntolerance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /AllergyIntolerance/{id}:
    get:
      operationId: readAllergyIntolerance
      summary: Read AllergyIntolerance
      tags:
        - AllergyIntolerance
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: AllergyIntolerance resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/AllergyIntolerance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateAllergyIntolerance
      summary: Update AllergyIntolerance
      tags:
        - AllergyIntolerance
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/AllergyIntolerance'
      responses:
        '200':
          description: AllergyIntolerance updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/AllergyIntolerance'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Encounter:
    get:
      operationId: searchEncounter
      summary: Search Encounters
      tags:
        - Encounter
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching encounters
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEncounter
      summary: Create Encounter
      tags:
        - Encounter
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Encounter'
      responses:
        '201':
          description: Encounter created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Encounter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Encounter/{id}:
    get:
      operationId: readEncounter
      summary: Read Encounter
      tags:
        - Encounter
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Encounter resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Encounter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateEncounter
      summary: Update Encounter
      tags:
        - Encounter
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Encounter'
      responses:
        '200':
          description: Encounter updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Encounter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Task:
    get:
      operationId: searchTask
      summary: Search Tasks
      tags:
        - Task
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: owner
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching tasks
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTask
      summary: Create Task
      tags:
        - Task
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: Task created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Task/{id}:
    get:
      operationId: readTask
      summary: Read Task
      tags:
        - Task
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Task resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateTask
      summary: Update Task
      tags:
        - Task
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Task updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /DocumentReference:
    get:
      operationId: searchDocumentReference
      summary: Search DocumentReferences
      tags:
        - DocumentReference
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - name: type
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching document references
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDocumentReference
      summary: Create DocumentReference
      tags:
        - DocumentReference
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/DocumentReference'
      responses:
        '201':
          description: DocumentReference created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/DocumentReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /DocumentReference/{id}:
    get:
      operationId: readDocumentReference
      summary: Read DocumentReference
      tags:
        - DocumentReference
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: DocumentReference resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/DocumentReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Immunization:
    get:
      operationId: searchImmunization
      summary: Search Immunizations
      tags:
        - Immunization
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching immunizations
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createImmunization
      summary: Create Immunization
      tags:
        - Immunization
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Immunization'
      responses:
        '201':
          description: Immunization created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Immunization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Immunization/{id}:
    get:
      operationId: readImmunization
      summary: Read Immunization
      tags:
        - Immunization
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Immunization resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Immunization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateImmunization
      summary: Update Immunization
      tags:
        - Immunization
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Immunization'
      responses:
        '200':
          description: Immunization updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Immunization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Practitioner:
    get:
      operationId: searchPractitioner
      summary: Search Practitioners
      tags:
        - Practitioner
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: identifier
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching practitioners
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Practitioner/{id}:
    get:
      operationId: readPractitioner
      summary: Read Practitioner
      tags:
        - Practitioner
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Practitioner resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Practitioner'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Organization:
    get:
      operationId: searchOrganization
      summary: Search Organizations
      tags:
        - Organization
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching organizations
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Organization/{id}:
    get:
      operationId: readOrganization
      summary: Read Organization
      tags:
        - Organization
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Organization resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Coverage:
    get:
      operationId: searchCoverage
      summary: Search Coverage
      description: Search for insurance coverage records
      tags:
        - Coverage
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching coverage records
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCoverage
      summary: Create Coverage
      tags:
        - Coverage
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Coverage'
      responses:
        '201':
          description: Coverage created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Coverage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Coverage/{id}:
    get:
      operationId: readCoverage
      summary: Read Coverage
      tags:
        - Coverage
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Coverage resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Coverage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateCoverage
      summary: Update Coverage
      tags:
        - Coverage
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Coverage'
      responses:
        '200':
          description: Coverage updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Coverage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Goal:
    get:
      operationId: searchGoal
      summary: Search Goals
      tags:
        - Goal
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching goals
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGoal
      summary: Create Goal
      tags:
        - Goal
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Goal'
      responses:
        '201':
          description: Goal created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Goal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Goal/{id}:
    get:
      operationId: readGoal
      summary: Read Goal
      tags:
        - Goal
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Goal resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Goal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateGoal
      summary: Update Goal
      tags:
        - Goal
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Goal'
      responses:
        '200':
          description: Goal updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Goal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /CarePlan:
    get:
      operationId: searchCarePlan
      summary: Search CarePlans
      tags:
        - CarePlan
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching care plans
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /CarePlan/{id}:
    get:
      operationId: readCarePlan
      summary: Read CarePlan
      tags:
        - CarePlan
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: CarePlan resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/CarePlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /CareTeam:
    get:
      operationId: searchCareTeam
      summary: Search CareTeams
      tags:
        - CareTeam
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching care teams
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /CareTeam/{id}:
    get:
      operationId: readCareTeam
      summary: Read CareTeam
      tags:
        - CareTeam
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: CareTeam resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/CareTeam'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Questionnaire:
    get:
      operationId: searchQuestionnaire
      summary: Search Questionnaires
      tags:
        - Questionnaire
      parameters:
        - name: title
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching questionnaires
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createQuestionnaire
      summary: Create Questionnaire
      tags:
        - Questionnaire
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Questionnaire'
      responses:
        '201':
          description: Questionnaire created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Questionnaire'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Questionnaire/{id}:
    get:
      operationId: readQuestionnaire
      summary: Read Questionnaire
      tags:
        - Questionnaire
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Questionnaire resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Questionnaire'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /QuestionnaireResponse:
    get:
      operationId: searchQuestionnaireResponse
      summary: Search QuestionnaireResponses
      tags:
        - QuestionnaireResponse
      parameters:
        - $ref: '#/components/parameters/patient'
        - name: questionnaire
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching questionnaire responses
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createQuestionnaireResponse
      summary: Create QuestionnaireResponse
      tags:
        - QuestionnaireResponse
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/QuestionnaireResponse'
      responses:
        '201':
          description: QuestionnaireResponse created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/QuestionnaireResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /QuestionnaireResponse/{id}:
    get:
      operationId: readQuestionnaireResponse
      summary: Read QuestionnaireResponse
      tags:
        - QuestionnaireResponse
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: QuestionnaireResponse resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/QuestionnaireResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /DiagnosticReport:
    get:
      operationId: searchDiagnosticReport
      summary: Search DiagnosticReports
      tags:
        - DiagnosticReport
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching diagnostic reports
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /DiagnosticReport/{id}:
    get:
      operationId: readDiagnosticReport
      summary: Read DiagnosticReport
      tags:
        - DiagnosticReport
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: DiagnosticReport resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/DiagnosticReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /ServiceRequest:
    get:
      operationId: searchServiceRequest
      summary: Search ServiceRequests
      tags:
        - ServiceRequest
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching service requests
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createServiceRequest
      summary: Create ServiceRequest
      tags:
        - ServiceRequest
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '201':
          description: ServiceRequest created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /ServiceRequest/{id}:
    get:
      operationId: readServiceRequest
      summary: Read ServiceRequest
      tags:
        - ServiceRequest
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: ServiceRequest resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    put:
      operationId: updateServiceRequest
      summary: Update ServiceRequest
      tags:
        - ServiceRequest
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '200':
          description: ServiceRequest updated
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/ServiceRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Procedure:
    get:
      operationId: searchProcedure
      summary: Search Procedures
      tags:
        - Procedure
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching procedures
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProcedure
      summary: Create Procedure
      tags:
        - Procedure
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Procedure'
      responses:
        '201':
          description: Procedure created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Procedure'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Procedure/{id}:
    get:
      operationId: readProcedure
      summary: Read Procedure
      tags:
        - Procedure
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Procedure resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Procedure'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Communication:
    get:
      operationId: searchCommunication
      summary: Search Communications
      tags:
        - Communication
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching communications
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCommunication
      summary: Create Communication
      tags:
        - Communication
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Communication'
      responses:
        '201':
          description: Communication created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Communication'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Communication/{id}:
    get:
      operationId: readCommunication
      summary: Read Communication
      tags:
        - Communication
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Communication resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Communication'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Location:
    get:
      operationId: searchLocation
      summary: Search Locations
      tags:
        - Location
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching locations
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Location/{id}:
    get:
      operationId: readLocation
      summary: Read Location
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Location resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Schedule:
    get:
      operationId: searchSchedule
      summary: Search Schedules
      tags:
        - Schedule
      parameters:
        - name: actor
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching schedules
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Schedule/{id}:
    get:
      operationId: readSchedule
      summary: Read Schedule
      tags:
        - Schedule
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Schedule resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Slot:
    get:
      operationId: searchSlot
      summary: Search Slots
      description: Search for available appointment slots
      tags:
        - Slot
      parameters:
        - name: schedule
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching slots
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /Slot/{id}:
    get:
      operationId: readSlot
      summary: Read Slot
      tags:
        - Slot
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Slot resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Slot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Claim:
    get:
      operationId: searchClaim
      summary: Search Claims
      tags:
        - Claim
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching claims
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createClaim
      summary: Create Claim
      tags:
        - Claim
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Claim'
      responses:
        '201':
          description: Claim created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Claim'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Claim/{id}:
    get:
      operationId: readClaim
      summary: Read Claim
      tags:
        - Claim
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Claim resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Claim'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

  /Consent:
    get:
      operationId: searchConsent
      summary: Search Consents
      tags:
        - Consent
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Bundle of matching consents
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createConsent
      summary: Create Consent
      tags:
        - Consent
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Consent'
      responses:
        '201':
          description: Consent created
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Consent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'

  /Consent/{id}:
    get:
      operationId: readConsent
      summary: Read Consent
      tags:
        - Consent
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Consent resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Consent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'

tags:
  - name: Metadata
    description: FHIR server capabilities
  - name: Patient
    description: Patient demographic and administrative data
  - name: Appointment
    description: Appointment scheduling and management
  - name: Observation
    description: Clinical observations, vitals, and lab results
  - name: Condition
    description: Patient conditions, problems, and diagnoses
  - name: MedicationRequest
    description: Medication prescriptions and orders
  - name: AllergyIntolerance
    description: Allergy and intolerance records
  - name: Encounter
    description: Clinical encounters and visits
  - name: Task
    description: Clinical and administrative tasks
  - name: DocumentReference
    description: Clinical documents and attachments
  - name: Immunization
    description: Immunization records
  - name: Practitioner
    description: Healthcare provider information
  - name: Organization
    description: Healthcare organization information
  - name: Coverage
    description: Insurance coverage records
  - name: Goal
    description: Patient care goals
  - name: CarePlan
    description: Care plan management
  - name: CareTeam
    description: Care team coordination
  - name: Questionnaire
    description: Structured data collection forms
  - name: QuestionnaireResponse
    description: Patient responses to questionnaires
  - name: DiagnosticReport
    description: Diagnostic test reports
  - name: ServiceRequest
    description: Orders for laboratory, imaging, and referrals
  - name: Procedure
    description: Clinical procedures performed
  - name: Communication
    description: Communications with or about a patient
  - name: Location
    description: Physical practice locations
  - name: Schedule
    description: Practitioner availability schedules
  - name: Slot
    description: Available appointment time slots
  - name: Claim
    description: Insurance claims and billing
  - name: Consent
    description: Patient consent records