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
  - name: ADT
    description: Inpatient admission, transfer, and discharge operations on Encounter.
  - name: Orders
    description: CPOE order entry via ServiceRequest.
  - name: Bed Management
    description: Ward, room, and bed inventory and occupancy via Location.
  - name: Audit
    description: Security audit log (AuditEvent) for ONC (g)(10) certification.
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
  /Encounter/$admit:
    post:
      tags: [ADT]
      summary: Admit patient (create inpatient Encounter)
      description: |
        Admit a patient to inpatient care. Creates an Encounter with class `inpatient`
        and status `in-progress`, sets the admission timestamp, and — when a bed
        `location` is supplied — marks that Location's operational status `Occupied`.
      security:
        - bearerAuth: [cms.fhir.rest.write, user/Encounter.write]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { $ref: '#/components/schemas/AdmitRequest' }
            example:
              patient: Patient/123
              location: Location/45
              reason: Community-acquired pneumonia
              priority: urgent
              type: { code: IMP, display: inpatient encounter }
      responses:
        '201':
          description: Inpatient Encounter created
          headers:
            Location:
              schema: { type: string }
              description: Canonical URL of the new Encounter
        '422': { $ref: '#/components/responses/OperationOutcome' }
  /Encounter/{id}/$transfer:
    post:
      tags: [ADT]
      summary: Transfer an admitted patient
      description: |
        Move an in-progress inpatient Encounter to a new bed/unit. Frees the
        `from` Location (set to `Housekeeping`) and occupies the `to` Location.
      security:
        - bearerAuth: [cms.fhir.rest.write, user/Encounter.write]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { $ref: '#/components/schemas/TransferRequest' }
            example: { from: Location/45, to: Location/46, reason: step-down }
      responses:
        '200':
          description: Encounter after transfer
        '409':
          description: Encounter is not in a transferable state
        '422': { $ref: '#/components/responses/OperationOutcome' }
  /Encounter/{id}/$discharge:
    post:
      tags: [ADT]
      summary: Discharge an admitted patient
      description: |
        Finish an inpatient Encounter. Sets status `finished`, records the discharge
        timestamp and length of stay, and frees the bed (Location → `Housekeeping`).
      security:
        - bearerAuth: [cms.fhir.rest.write, user/Encounter.write]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/fhir+json:
            schema: { $ref: '#/components/schemas/DischargeRequest' }
            example: { location: Location/46, disposition: home }
      responses:
        '200':
          description: Discharged Encounter
        '422': { $ref: '#/components/responses/OperationOutcome' }
  /ServiceRequest:
    post:
      tags: [Orders]
      summary: Place an order (CPOE)
      description: |
        Create a ServiceRequest for a lab, imaging study, procedure, or nursing
        order. `subject` (Patient) and `code` are required; `requester` defaults to
        the authenticated practitioner when omitted.
      security:
        - bearerAuth: [cms.fhir.rest.write, user/ServiceRequest.write]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
              description: FHIR R4 ServiceRequest resource
            example:
              resourceType: ServiceRequest
              status: active
              intent: order
              priority: routine
              category: [{ coding: [{ code: '108252007', display: Laboratory procedure }] }]
              code: { coding: [{ system: 'http://loinc.org', code: '58410-2', display: CBC panel }] }
              subject: { reference: Patient/123 }
              encounter: { reference: Encounter/456 }
      responses:
        '201':
          description: ServiceRequest created
          headers:
            Location:
              schema: { type: string }
        '422': { $ref: '#/components/responses/OperationOutcome' }
  /Location:
    post:
      tags: [Bed Management]
      summary: Create a Location (facility, ward, room, or bed)
      security:
        - bearerAuth: [cms.fhir.rest.write, user/Location.write]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
              description: FHIR R4 Location resource
            example:
              resourceType: Location
              status: active
              name: 4 West - Bed 12A
              mode: instance
              physicalType: { coding: [{ code: bd, display: Bed }] }
              operationalStatus: { code: U, display: Unoccupied }
              partOf: { reference: Location/20 }
      responses:
        '201':
          description: Location created
          headers:
            Location:
              schema: { type: string }
        '422': { $ref: '#/components/responses/OperationOutcome' }
  /Location/{id}:
    patch:
      tags: [Bed Management]
      summary: Update a Location (bed status)
      description: |
        Update a Location — primarily to change bed occupancy. Accepts a compact
        `operationalStatus` shorthand (`occupied`, `unoccupied`, `housekeeping`,
        `closed`, `contaminated`, `isolated`) or a full FHIR CodeableConcept.
      security:
        - bearerAuth: [cms.fhir.rest.write, user/Location.write]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
            examples:
              occupyBed:
                summary: Occupy a bed
                value: { operationalStatus: occupied }
              closeBed:
                summary: Take a bed out of service
                value: { status: inactive, operationalStatus: closed }
      responses:
        '200':
          description: Updated Location
        '404': { $ref: '#/components/responses/OperationOutcome' }
  /AuditEvent:
    get:
      tags: [Audit]
      summary: Search AuditEvents
      description: |
        Query the security audit log. AuditEvent records who accessed or acted on
        the system, when, and from where — the audit trail required for ONC (g)(10).
      security:
        - bearerAuth: [cms.fhir.r4.read, user/AuditEvent.read]
      parameters:
        - name: entity
          in: query
          schema: { type: string }
          description: 'Affected resource, e.g. Patient/123'
        - name: agent
          in: query
          schema: { type: string }
          description: 'Acting practitioner, e.g. Practitioner/7'
        - name: action
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string, format: date-time }
        - name: outcome
          in: query
          schema: { type: string, enum: ['0', '4', '8', '12'] }
          description: '0 = success; non-zero = minor/serious/major failure'
      responses:
        '200':
          description: Bundle of AuditEvent resources
  /AuditEvent/{id}:
    get:
      tags: [Audit]
      summary: Read AuditEvent
      security:
        - bearerAuth: [cms.fhir.r4.read, user/AuditEvent.read]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: AuditEvent resource
        '404': { $ref: '#/components/responses/OperationOutcome' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    OperationOutcome:
      description: FHIR OperationOutcome describing the error
      content:
        application/fhir+json:
          schema:
            type: object
            properties:
              resourceType: { type: string, example: OperationOutcome }
              issue:
                type: array
                items:
                  type: object
                  properties:
                    severity: { type: string, example: error }
                    code: { type: string, example: required }
                    details:
                      type: object
                      properties:
                        text: { type: string }
  schemas:
    AdmitRequest:
      type: object
      required: [patient]
      properties:
        patient: { type: string, description: 'Patient reference, e.g. Patient/123' }
        location: { type: string, description: 'Bed Location reference to occupy, e.g. Location/45' }
        reason: { type: string }
        priority: { type: string, enum: [routine, urgent, asap, stat] }
        type:
          type: object
          properties:
            code: { type: string }
            display: { type: string }
    TransferRequest:
      type: object
      required: [to]
      properties:
        from: { type: string, description: 'Current bed Location reference' }
        to: { type: string, description: 'Destination bed Location reference' }
        reason: { type: string }
    DischargeRequest:
      type: object
      properties:
        location: { type: string, description: 'Bed Location reference to free' }
        disposition: { type: string, description: 'Discharge disposition, e.g. home, snf, ama, expired' }
