openapi: 3.1.0
info:
  title: Apex Sightline Vision EHR API
  version: 1.0.0
  summary: FHIR R4 partner API for Apex Sightline — optometry and ophthalmology workflows
  description: |
    **Apex Sightline™** is Parker Apex's FHIR-first Vision EHR product line. Partners integrate via
    the shared gateway at `api.parkerapex.com/fhir/R4` with GPID-scoped OAuth and required headers.

    All clinical, eligibility, and billing records map to standard FHIR R4 resources. Specialty
    workflows include refraction, visual acuity, IOP, retinal imaging, OCT, visual field,
    `VisionPrescription` lifecycle, optical fulfillment, and vision claim type (`vision`).

    **Golden bundle:** `docs/schemas/specialty/sightline-golden-bundle.r4.json`
    **Product code:** `sightline` · **Claim type:** `vision`

    Required partner headers on every write:
    - `X-Apex-Actor-GPID` — organizational actor GPID
    - `X-Apex-Subject-GPID` — patient GPID
    - `X-Apex-Source` — integration source identifier
servers:
  - url: https://api.parkerapex.com/fhir/R4
    description: Production FHIR gateway (Sightline scope)
  - url: https://lake.parkerapex.com/fhir/R4
    description: FHIR Data Lake (longitudinal store)
  - url: https://sandbox.api.parkerapex.com/fhir/R4
    description: Sandbox
tags:
  - name: Identity
  - name: Scheduling
  - name: Clinical
  - name: Diagnostics
  - name: Prescriptions
  - name: Financial
  - name: Conformance
security:
  - OAuth2: []
paths:
  /metadata:
    get:
      tags: [Conformance]
      operationId: sightlineCapabilityStatement
      summary: FHIR CapabilityStatement (includes VisionPrescription)
      security: []
      responses:
        '200':
          description: CapabilityStatement (application/fhir+json)
  /Patient:
    get:
      tags: [Identity]
      operationId: searchSightlinePatients
      summary: Search vision patients by GPID or demographics
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - name: identifier
          in: query
          schema: { type: string }
          description: GPID identifier (system https://parkerapex.com/gpid)
      responses:
        '200':
          description: Bundle of Patient resources
    post:
      tags: [Identity]
      operationId: createSightlinePatient
      summary: Create patient (IdentityResolver required)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
              description: FHIR Patient with GPID identifier
      responses:
        '201':
          description: Patient created
  /Appointment:
    get:
      tags: [Scheduling]
      operationId: searchSightlineAppointments
      summary: Search exam appointments and recall slots
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Appointment resources
    post:
      tags: [Scheduling]
      operationId: createSightlineAppointment
      summary: Book vision exam appointment
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Appointment created
  /Encounter:
    get:
      tags: [Clinical]
      operationId: searchSightlineEncounters
      summary: Search vision exam encounters
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Encounter resources
    post:
      tags: [Clinical]
      operationId: createSightlineEncounter
      summary: Open vision exam encounter
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Encounter created
  /Observation:
    get:
      tags: [Clinical]
      operationId: searchSightlineObservations
      summary: Search refraction, VA, IOP, and clinical observations
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string, enum: [exam, vital-signs, imaging] }
        - name: code
          in: query
          schema: { type: string }
          description: LOINC code (e.g. visual acuity, refraction sphere)
      responses:
        '200':
          description: Bundle of Observation resources
    post:
      tags: [Clinical]
      operationId: createSightlineObservation
      summary: Record refraction, visual acuity, IOP, or exam finding
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Observation created
  /DiagnosticReport:
    get:
      tags: [Diagnostics]
      operationId: searchSightlineDiagnosticReports
      summary: Search OCT, visual field, and retinal imaging reports
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of DiagnosticReport resources
    post:
      tags: [Diagnostics]
      operationId: createSightlineDiagnosticReport
      summary: Submit grouped diagnostic interpretation (OCT, visual field, fundus)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: DiagnosticReport created
  /VisionPrescription:
    get:
      tags: [Prescriptions]
      operationId: searchSightlineVisionPrescriptions
      summary: Search glasses and contact lens prescriptions
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of VisionPrescription resources
    post:
      tags: [Prescriptions]
      operationId: createSightlineVisionPrescription
      summary: Create glasses or contact lens prescription
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
            examples:
              glassesRx:
                summary: Bifocal lens prescription
                value:
                  resourceType: VisionPrescription
                  status: active
                  created: '2026-06-12T14:00:00Z'
                  patient: { reference: 'Patient/sightline-patient' }
                  dateWritten: '2026-06-12'
                  prescriber: { reference: 'Practitioner/sightline-practitioner' }
                  lensSpecification:
                    - eye: right
                      sphere: -2.25
                      cylinder: -0.75
                      axis: 90
                      add: 2.00
                    - eye: left
                      sphere: -2.00
                      cylinder: -0.50
                      axis: 85
                      add: 2.00
      responses:
        '201':
          description: VisionPrescription created
  /DeviceRequest:
    post:
      tags: [Prescriptions]
      operationId: createSightlineDeviceRequest
      summary: Order frames, lenses, or optical fulfillment
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: DeviceRequest created
  /CoverageEligibilityRequest:
    post:
      tags: [Financial]
      operationId: createSightlineEligibilityRequest
      summary: Vision benefits check (exam, materials, lenses, contacts)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: CoverageEligibilityRequest created
  /Claim:
    post:
      tags: [Financial]
      operationId: createSightlineClaim
      summary: Submit vision claim or preauthorization (Claim.type = vision)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Claim created
  /ClaimResponse:
    get:
      tags: [Financial]
      operationId: readSightlineClaimResponse
      summary: Read payer adjudication for vision claim
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: _id
          in: query
          schema: { type: string }
      responses:
        '200':
          description: ClaimResponse resource
  /ExplanationOfBenefit:
    get:
      tags: [Financial]
      operationId: searchSightlineEob
      summary: Search vision EOBs for patient
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bundle of ExplanationOfBenefit resources

  /sightline/v1/exams:
    get:
      tags: [Operational]
      operationId: listSightlineExams
      summary: List vision exams for patient
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient_gpid
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Exam list with refraction summary
    post:
      tags: [Operational]
      operationId: createSightlineExam
      summary: Open vision exam session
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      responses:
        '201':
          description: Exam created
  /sightline/v1/exams/{examId}/refraction:
    post:
      tags: [Operational]
      operationId: postSightlineRefraction
      summary: Record refraction measurements (creates FHIR Observations)
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: examId
          in: path
          required: true
          schema: { type: string }
      responses:
        '201':
          description: Refraction saved
  /sightline/v1/prescriptions/{id}/fulfill:
    post:
      tags: [Operational]
      operationId: fulfillSightlinePrescription
      summary: Mark optical order fulfilled (frames/lenses/contacts)
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Fulfillment updated
  /sightline/v1/imaging/studies:
    post:
      tags: [Operational]
      operationId: ingestSightlineImaging
      summary: Ingest OCT, visual field, or retinal imaging study
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
      responses:
        '202':
          description: Imaging ingest accepted

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.parkerapex.com/oauth/token
          scopes:
            user/Patient.read: Read patients
            user/Patient.write: Create/update patients
            user/Observation.read: Read clinical observations
            user/Observation.write: Write observations
            user/VisionPrescription.read: Read prescriptions
            user/VisionPrescription.write: Write prescriptions
            user/Claim.write: Submit claims
  parameters:
    XApexActorGpid:
      name: X-Apex-Actor-GPID
      in: header
      required: true
      schema: { type: string }
      description: Partner organizational actor GPID (PLX-…)
    XApexSubjectGpid:
      name: X-Apex-Subject-GPID
      in: header
      required: true
      schema: { type: string }
      description: Patient GPID (APX-…)
    XApexSource:
      name: X-Apex-Source
      in: header
      required: true
      schema: { type: string }
      description: Integration source identifier (e.g. sightline-partner-001)
