openapi: 3.0.3
info:
  title: Apex Ingest and Boundaries Contract
  version: 2026-03-06
  description: >
    Contract for currently implemented Beacon ingest endpoints and SMART
    Health Card/SMART Health Link ingest endpoints.
servers:
  - url: https://prod.parkerapex.com
    description: Production
  - url: https://dev.parkerapex.com
    description: Development
  - url: https://beacon.parkerapex.com
    description: Beacon services

paths:
  /beacon/api/uploads/signed-url:
    post:
      tags:
        - Beacon Ingest
      summary: Request a direct upload URL
      description: >
        Requires Beacon auth and `patient/*.write` permission.
        Generates a short-lived GCS PUT URL for direct browser upload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignedUrlRequest'
            examples:
              pdf:
                value:
                  filename: example-lab-report.pdf
                  mime_type: application/pdf
                  file_size_bytes: 1827342
      responses:
        '200':
          description: Signed URL issued (or upload fallback flag)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedUrlResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Upload signing service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /beacon/api/uploads/finalize:
    post:
      tags:
        - Beacon Ingest
      summary: Finalize a direct upload
      description: >
        Creates Beacon document metadata and enqueues the processing pipeline.
        Requires Beacon auth and `patient/*.write` permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizeUploadRequest'
            examples:
              finalize:
                value:
                  blob_name: documents/2026/03/06/direct-abcd1234.pdf
                  gcs_uri: gs://apex-beacon-documents/documents/2026/03/06/direct-abcd1234.pdf
                  mime_type: application/pdf
                  file_size_bytes: 1827342
                  document_type: lab_report
                  source_system: lab_portal
      responses:
        '200':
          description: Upload finalized and document created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinalizeUploadResponse'
        '400':
          description: Invalid metadata or payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Uploaded object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Finalization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/smart-health-cards/ingest:
    post:
      tags:
        - SMART Health Cards
      summary: SMART Health Card ingest verification (Implemented)
      x-implementation-status: implemented
      description: >
        Verifies SMART Health Card/SMART Health Link payloads, checks temporal constraints,
        records each verification decision, and returns a deterministic `verification_id`
        for readback. In production, set `SMART_HEALTH_CARD_VERIFY_MODE=strict`
        and enforce issuer allow-listing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmartHealthCardIngestRequest'
            examples:
              sample:
                value:
                  jws: eyJraWQiOiJuMCIsImFsZyI6IlJTMjU2In0...
      responses:
        '200':
          description: Verification attempt completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartHealthCardVerificationResult'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Processing failure in boundary service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/smart-health-cards/verification:
    get:
      tags:
        - SMART Health Cards
      summary: SMART Health Card verification status
      x-implementation-status: implemented
      description: >
        Retrieve deterministic verification status and evidence for a prior ingest request.
      responses:
        '200':
          description: Verification status found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartHealthCardVerificationResult'
        '400':
          description: Missing or invalid verification identifier
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Verification identifier not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Missing query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    SignedUrlRequest:
      type: object
      required:
        - filename
        - file_size_bytes
      properties:
        filename:
          type: string
          example: example-lab-report.pdf
        mime_type:
          type: string
          example: application/pdf
        file_size_bytes:
          type: integer
          minimum: 1
          example: 1827342

    SignedUrlResponse:
      type: object
      required:
        - ok
        - method
        - upload_url
      properties:
        ok:
          type: boolean
          example: true
        method:
          type: string
          enum:
            - PUT
            - PATCH
        upload_url:
          type: string
          format: uri
        blob_name:
          type: string
          example: documents/2026/03/06/direct-abcd1234.pdf
        gcs_uri:
          type: string
          example: gs://apex-beacon-documents/documents/2026/03/06/direct-abcd1234.pdf
        required_headers:
          type: object
          additionalProperties:
            type: string
          example:
            Content-Type: application/pdf
        fallback:
          type: boolean
          example: false
        reason:
          type: string
          example: direct_upload_unavailable
        fallback_max_bytes:
          type: integer
          example: 33554432

    FinalizeUploadRequest:
      type: object
      required:
        - blob_name
      properties:
        blob_name:
          type: string
          example: documents/2026/03/06/direct-abcd1234.pdf
        gcs_uri:
          type: string
          example: gs://apex-beacon-documents/documents/2026/03/06/direct-abcd1234.pdf
        original_filename:
          type: string
          example: example-lab-report.pdf
        mime_type:
          type: string
          example: application/pdf
        file_size_bytes:
          type: integer
          example: 1827342
        file_hash_sha256:
          type: string
          example: b4f9...
        document_type:
          type: string
          example: lab_report
        source_system:
          type: string
          example: lab_portal
        source_organization:
          type: string
          example: Mercy Care
        patient_id:
          type: integer
          example: 1234
        gpid:
          type: string
          example: APX-12AB34CD
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        dob:
          type: string
          format: date
        sex:
          type: string
          enum: [male, female, other, unknown]
        gender:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string

    FinalizeUploadResponse:
      type: object
      required:
        - ok
        - document_id
      properties:
        ok:
          type: boolean
          example: true
        document_id:
          type: string
          example: BEACON-12345
        gpid:
          type: string
          example: APX-12AB34CD
        match_status:
          type: string
          example: matched
        match_score:
          type: number
          format: float
        match_reason:
          type: string
          example: deterministic_match
        is_duplicate:
          type: boolean
          example: false
        duplicate_of_document_id:
          type: string
          nullable: true
          example: BEACON-12234
        redirect_url:
          type: string
          format: uri

    BoundaryPlannedResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum: [planned]
          example: planned
        message:
          type: string
          example: Boundary-planned API contract for future expansion.
        implementation_reference:
          type: string
          example: docs/FHIR_COMPLIANCE_BOUNDARIES_2026-03-06.md

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: invalid request

    SmartHealthCardIngestRequest:
      type: object
      required:
        - jws
      properties:
        jws:
          type: string
          description: Compact JWS from SMART Health Card payload or SHC numeric payload
          example: eyJraWQiOiJuMCIsImFsZyI6IlJTMjU2In0...
        smart_health_card:
          type: string
          description: Alias for payload (accepted for compatibility)
          example: shc:/567629095243...
        note:
          type: string
          example: Optional tracking/reference note for ingest workflow

    SmartHealthCardVerificationResult:
      type: object
      required:
        - accepted
        - status
        - verification_id
      properties:
        accepted:
          type: boolean
        status:
          type: string
          enum: [accepted, rejected]
        verification_id:
          type: string
          example: 9f8b6b1a9f2d4b2fa7f4c3c8e9a7a5ff
        verification_mode:
          type: string
          enum: [disabled, warn, strict]
          example: warn
        signature_verified:
          type: boolean
        issuer:
          type: string
          nullable: true
          example: https://smarthealth.cards
        reasons:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
        error:
          type: string
        resource_summary:
          type: object
          additionalProperties: true
