openapi: 3.0.3
info:
  title: Apex FHIR R4 REST API
  version: 4.0.1
  description: |
    HL7 FHIR R4 RESTful API served from the APEX Nexus gateway and FHIR Data Lake.
    Supports SMART on FHIR OAuth 2.0, bulk $export, and 300+ resource types.
  contact:
    name: Parker Apex Developer Support
    url: https://developers.parkerapex.com
servers:
  - url: https://api.parkerapex.com/fhir/R4
    description: Production API Gateway
  - url: https://sandbox.api.parkerapex.com/fhir/R4
    description: Sandbox
  - url: https://lake.parkerapex.com/fhir/R4
    description: FHIR Data Lake (HAPI)
tags:
  - name: Conformance
  - name: Patient
  - name: Observation
  - name: Bundle
  - name: Bulk Export
  - name: SMART
paths:
  /metadata:
    get:
      tags: [Conformance]
      summary: CapabilityStatement
      description: FHIR conformance metadata — supported resource types, interactions, and search parameters.
      responses:
        '200':
          description: CapabilityStatement resource
  /.well-known/smart-configuration:
    get:
      tags: [SMART]
      summary: SMART on FHIR configuration
      description: OAuth authorization and token endpoints, supported scopes, and launch capabilities.
      servers:
        - url: https://api.parkerapex.com/fhir/R4
      responses:
        '200':
          description: SMART configuration JSON
  /Patient:
    get:
      tags: [Patient]
      summary: Search Patients
      description: Search Patient resources by name, identifier (GPID), birthdate, and other search parameters.
      security:
        - bearerAuth: [cms.fhir.r4.read, patient/Patient.read]
      parameters:
        - name: name
          in: query
          schema: { type: string }
        - name: identifier
          in: query
          schema: { type: string }
          description: 'GPID identifier, e.g. https://parkerapex.com/gpid|APX-EXAMPLE'
        - name: birthdate
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Bundle of Patient resources
    post:
      tags: [Patient]
      summary: Create Patient
      security:
        - bearerAuth: [cms.fhir.rest.write]
      responses:
        '201':
          description: Patient created
  /Patient/{id}:
    get:
      tags: [Patient]
      summary: Read Patient
      security:
        - bearerAuth: [cms.fhir.r4.read, patient/Patient.read]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Patient resource
  /Observation:
    get:
      tags: [Observation]
      summary: Search Observations
      security:
        - bearerAuth: [cms.fhir.r4.read, patient/Observation.read]
      parameters:
        - name: patient
          in: query
          schema: { type: string }
        - name: code
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Observation resources
  /:
    post:
      tags: [Bundle]
      summary: Submit FHIR Bundle
      description: Transaction or batch Bundle for multi-resource ingest.
      security:
        - bearerAuth: [cms.fhir.bundle.push, system/*.write]
      responses:
        '200':
          description: Bundle response
  /$export:
    get:
      tags: [Bulk Export]
      summary: Bulk Data Export
      description: Initiate async bulk FHIR export (SMART Backend Services). Returns 202 with Content-Location polling URL.
      security:
        - bearerAuth: [system/*.read, system/Patient.read]
      parameters:
        - name: _type
          in: query
          schema: { type: string }
        - name: _since
          in: query
          schema: { type: string, format: date-time }
      responses:
        '202':
          description: Export job accepted
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
