openapi: 3.1.0
info:
  title: Apex CMS Health Tech Ecosystem API
  version: 1.0.0
  summary: CMS partner onboarding, GPID issuance, FHIR artifact catalog, and SDK distribution
  description: |
    OpenAPI contract for Apex CMS Health Tech Ecosystem endpoints.
    Covers partner onboarding, ecosystem approvals, GPID-aware patient resolution,
    dual-verified data exchange, FHIR artifact catalog, and SDK distribution.
servers:
  - url: https://cms.nexus.parkerapex.com/api/v1
    description: Production
  - url: https://sandbox.cms.parkerapex.com/api/v1
    description: Sandbox
tags:
  - name: Partners
  - name: Ecosystem
  - name: SDK
  - name: FHIR
security:
  - OAuth2: []
paths:
  /cms-ecosystem/sdk-catalog:
    get:
      tags: [SDK]
      operationId: getCmsSdkCatalog
      summary: List CMS Health Tech Ecosystem SDKs
      description: |
        Returns the SDK catalog for the CMS Health Tech Ecosystem, including
        TypeScript, Python, and Java packages with GPID-aware patient resolution
        and dual-verified data helpers.
      security:
        - OAuth2:
            - cms.sdk.read
      responses:
        '200':
          description: SDK catalog returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CmsSdkCatalogResponse'
              example:
                catalog: cms-health-tech-ecosystem
                version: '1.0.0'
                sdks:
                  - language: typescript
                    package_name: '@parkerapex/cms-health-sdk'
                    registry: npm
                    install_command: 'npm install @parkerapex/cms-health-sdk'
                    version: '1.0.0'
                    released_at: '2026-04-08'
                    features:
                      - FHIR R4/R5 bundle support
                      - GPID-aware patient resolution
                      - Dual-verified data helpers
                  - language: python
                    package_name: parkerapex-cms-health-sdk
                    registry: pypi
                    install_command: 'pip install parkerapex-cms-health-sdk'
                    version: '1.0.0'
                    released_at: '2026-04-08'
                    features:
                      - FHIR R4/R5 bundle support
                      - GPID-aware patient resolution
                      - Dual-verified data helpers
                  - language: java
                    package_name: 'com.parkerapex:cms-health-sdk'
                    registry: maven-central
                    install_command: "implementation 'com.parkerapex:cms-health-sdk:1.0.0'"
                    version: '1.0.0'
                    released_at: '2026-04-08'
                    features:
                      - FHIR R4/R5 bundle support
                      - GPID-aware patient resolution
                      - Dual-verified data helpers
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /cms-ecosystem/partners:
    post:
      tags: [Partners]
      operationId: applyAsPartner
      summary: Submit a CMS partner application
      description: |
        Self-service partner onboarding. Creates a pending GPID for the
        applicant organization and enqueues it for ecosystem approval.
      security:
        - OAuth2:
            - cms.partner.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerApplicationRequest'
      responses:
        '201':
          description: Application submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerApplicationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
  /cms-ecosystem/partners/{gpid}:
    get:
      tags: [Partners]
      operationId: getPartnerInfo
      summary: Get partner info by GPID
      description: Returns partner details and lifecycle events.
      security:
        - OAuth2:
            - cms.partner.read
      parameters:
        - name: gpid
          in: path
          required: true
          schema:
            type: string
          description: The partner GPID value
      responses:
        '200':
          description: Partner info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.parkerapex.com/oauth2/token
          scopes:
            cms.sdk.read: Read SDK catalog
            cms.partner.read: Read partner info
            cms.partner.write: Submit partner applications
  schemas:
    CmsSdkCatalogResponse:
      type: object
      required: [catalog, version, sdks]
      properties:
        catalog:
          type: string
          example: cms-health-tech-ecosystem
        version:
          type: string
          example: '1.0.0'
        sdks:
          type: array
          items:
            $ref: '#/components/schemas/SdkEntry'
    SdkEntry:
      type: object
      required: [language, package_name, registry, install_command, version, released_at]
      properties:
        language:
          type: string
          enum: [typescript, python, java]
        package_name:
          type: string
        registry:
          type: string
          enum: [npm, pypi, maven-central]
        install_command:
          type: string
        repository_url:
          type: string
          format: uri
        version:
          type: string
        released_at:
          type: string
          format: date
        openapi_spec:
          type: string
        features:
          type: array
          items:
            type: string
    PartnerApplicationRequest:
      type: object
      required: [organization_name, contact_email]
      properties:
        organization_name:
          type: string
        contact_email:
          type: string
          format: email
        use_case:
          type: string
    PartnerApplicationResponse:
      type: object
      properties:
        gpid:
          type: string
        display_name:
          type: string
        status:
          type: string
          enum: [pending, approved, rejected]
    PartnerInfoResponse:
      type: object
      properties:
        gpid:
          type: string
        display_name:
          type: string
        status:
          type: string
        lifecycle_events:
          type: array
          items:
            type: object
            properties:
              event_type:
                type: string
              timestamp:
                type: string
                format: date-time
              actor:
                type: string
    Error:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
