openapi: 3.1.0
info:
  title: APEX Nexus Platform API
  version: 1.0.0
  summary: Flagship EHR platform — FHIR R4, mobile, semantic layer, identity, and clinical workflows
  description: |
    OpenAPI contract for **APEX Nexus**, Parker Apex's flagship clinical platform (EHR + integrations).

    Nexus is the production backbone behind `cms.prod.parkerapex.com` and the partner gateway at
    `api.parkerapex.com`. It exposes FHIR R4 (96.7% coverage), SMART on FHIR OAuth 2.0, bulk `$export`,
    mobile-optimized REST, semantic federated queries, GPID identity resolution, and clinical modules.

    **Related products:** Pulse PHR consumes `/mobile/api/*`; partners integrate via OAuth scopes documented
    in the [developer portal](https://developers.parkerapex.com/guides/first-fhir-read).
servers:
  - url: https://api.parkerapex.com
    description: Production API gateway
  - url: https://cms.prod.parkerapex.com
    description: Nexus CMS production host
  - url: https://sandbox.api.parkerapex.com
    description: Sandbox
tags:
  - name: Platform
  - name: FHIR R4
  - name: SMART
  - name: Mobile
  - name: Identity
  - name: Semantic
  - name: Clinical
security:
  - OAuth2: []
paths:
  /health:
    get:
      tags: [Platform]
      operationId: nexusHealth
      summary: Platform health
      security: []
      responses:
        '200':
          description: Service healthy
  /ready:
    get:
      tags: [Platform]
      operationId: nexusReady
      summary: Readiness probe
      security: []
      responses:
        '200':
          description: Ready to serve traffic
  /fhir/R4/metadata:
    get:
      tags: [FHIR R4]
      operationId: fhirCapabilityStatement
      summary: FHIR R4 CapabilityStatement
      description: Describes supported resources, search parameters, and operations.
      security: []
      responses:
        '200':
          description: CapabilityStatement (application/fhir+json)
  /fhir/R4/.well-known/smart-configuration:
    get:
      tags: [SMART]
      operationId: smartConfiguration
      summary: SMART on FHIR discovery
      security: []
      responses:
        '200':
          description: SMART configuration JSON
  /oauth/token:
    post:
      tags: [SMART]
      operationId: oauthToken
      summary: OAuth 2.0 token endpoint
      description: Client credentials and authorization code grants for SMART and partner integrations.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials, authorization_code, refresh_token]
                client_id:
                  type: string
                client_secret:
                  type: string
                scope:
                  type: string
      responses:
        '200':
          description: Token response
        '401':
          description: Invalid client credentials
  /fhir/R4/Patient:
    get:
      tags: [FHIR R4]
      operationId: searchPatients
      summary: Search Patient resources
      security:
        - OAuth2: [cms.fhir.r4.read]
      parameters:
        - name: identifier
          in: query
          schema:
            type: string
          description: GPID or MRN identifier (e.g. `https://parkerapex.com/fhir/identifier/gpid|APX-12345678`)
        - name: name
          in: query
          schema:
            type: string
        - name: birthdate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: FHIR Bundle search set
    post:
      tags: [FHIR R4]
      operationId: createPatient
      summary: Create Patient resource
      security:
        - OAuth2: [cms.fhir.rest.write]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
      responses:
        '201':
          description: Patient created
  /fhir/R4/Patient/{id}:
    get:
      tags: [FHIR R4]
      operationId: readPatient
      summary: Read Patient by id
      security:
        - OAuth2: [cms.fhir.r4.read]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Patient resource
        '404':
          description: Not found
  /fhir/R4/Observation:
    get:
      tags: [FHIR R4]
      operationId: searchObservations
      summary: Search Observation resources
      security:
        - OAuth2: [cms.fhir.r4.read]
      parameters:
        - name: patient
          in: query
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
      responses:
        '200':
          description: FHIR Bundle
  /fhir/R4:
    post:
      tags: [FHIR R4]
      operationId: fhirTransactionBundle
      summary: Process FHIR transaction Bundle
      security:
        - OAuth2: [cms.fhir.bundle.push]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
      responses:
        '200':
          description: Transaction response Bundle
  /fhir/R4/$export:
    get:
      tags: [FHIR R4]
      operationId: bulkExport
      summary: Bulk FHIR data export ($export)
      description: Initiates asynchronous NDJSON bulk export. Poll `Content-Location` until complete.
      security:
        - OAuth2: [cms.fhir.r4.read]
      parameters:
        - name: _type
          in: query
          schema:
            type: string
          description: Comma-separated resource types
        - name: _since
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '202':
          description: Export job accepted
  /mobile/api/patient/dashboard:
    get:
      tags: [Mobile]
      operationId: patientDashboard
      summary: Patient mobile dashboard (Pulse PHR)
      security:
        - OAuth2: [patient/*.read]
      responses:
        '200':
          description: Aggregated patient dashboard payload
  /mobile/api/patient/appointments:
    get:
      tags: [Mobile]
      operationId: patientAppointments
      summary: List patient appointments
      security:
        - OAuth2: [patient/Appointment.read]
      responses:
        '200':
          description: Appointments list
  /mobile/api/patient/medical-records:
    get:
      tags: [Mobile]
      operationId: patientMedicalRecords
      summary: Patient medical records summary
      security:
        - OAuth2: [patient/*.read]
      responses:
        '200':
          description: Medical records bundle
  /api/identity/resolve:
    post:
      tags: [Identity]
      operationId: resolveGpid
      summary: Resolve or create GPID from demographics
      security:
        - OAuth2: [cms.identity.resolve]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [given_name, family_name, birth_date]
              properties:
                given_name:
                  type: string
                family_name:
                  type: string
                birth_date:
                  type: string
                  format: date
                source:
                  type: string
                  enum: [nexus, pulse, cms, beacon, prime, lake, catalyst, tefca]
      responses:
        '200':
          description: GPID resolution result
  /api/semantic/query:
    post:
      tags: [Semantic]
      operationId: semanticQuery
      summary: Federated semantic data query
      description: POST structured resource blocks; fans out to registered Nexus adapters with purpose-of-use enforcement.
      security:
        - OAuth2: [cms.semantic.read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [purpose_of_use, resources]
              properties:
                purpose_of_use:
                  type: string
                  enum: [treatment, payment, operations, research, audit, public_health]
                resources:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: Query envelope with adapter results
  /api/semantic/schema:
    get:
      tags: [Semantic]
      operationId: semanticSchema
      summary: Discover semantic adapter resource types
      security:
        - OAuth2: [cms.semantic.read]
      responses:
        '200':
          description: Registered services and resource types
  /api/cohort/count:
    post:
      tags: [Clinical]
      operationId: cohortCount
      summary: Validate cohort criteria DSL and return match count
      description: Returns `501` with `criteria_valid` until lake-backed matching engine ships (Phase 2).
      security:
        - OAuth2: [cms.cohort.read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Cohort count (when engine available)
        '501':
          description: Criteria valid; matching engine pending
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.parkerapex.com/oauth/token
          scopes:
            cms.fhir.r4.read: Read FHIR R4 resources
            cms.fhir.rest.write: Write FHIR resources
            cms.fhir.bundle.push: Submit FHIR transaction bundles
            cms.identity.resolve: GPID resolve and create
            cms.identity.match: Demographics match (read-only)
            cms.semantic.read: Semantic federated queries
            cms.cohort.read: Cohort criteria validation
            patient/*.read: Patient-facing mobile API read
            patient/Appointment.read: Patient appointments
