openapi: 3.1.0
info:
  title: Orion Health FHIR Alerts Routes API
  description: The Orion Health FHIR API provides standards-based access to healthcare data using the HL7 FHIR (Fast Healthcare Interoperability Resources) specification. It enables healthcare organizations to read, search, create, and update clinical resources including patients, encounters, observations, conditions, medications, allergies, procedures, diagnostic reports, and care plans. The API conforms to FHIR R4 (v4.0.1) and supports both JSON and XML representations.
  version: 1.0.0
  contact:
    name: Orion Health API Support
    email: apisupport@orionhealth.com
    url: https://www.orionhealth.com/support
  license:
    name: Proprietary
    url: https://www.orionhealth.com/terms-of-service
  termsOfService: https://www.orionhealth.com/terms-of-service
servers:
- url: https://api.orionhealth.com/fhir
  description: Production FHIR Server
- url: https://sandbox.orionhealth.com/fhir
  description: Sandbox FHIR Server
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Routes
  description: Integration route management
paths:
  /routes:
    get:
      operationId: listRoutes
      summary: Orion Health List integration routes
      description: Retrieve all integration routes configured in the Rhapsody engine, including their current operational status.
      tags:
      - Routes
      parameters:
      - name: status
        in: query
        description: Filter by route status
        schema:
          type: string
          enum:
          - started
          - stopped
          - error
          - disabled
      - name: folder
        in: query
        description: Filter by route folder path
        schema:
          type: string
      - name: search
        in: query
        description: Search routes by name
        schema:
          type: string
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      responses:
        '200':
          description: List of integration routes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Route'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /routes/{routeId}:
    get:
      operationId: getRoute
      summary: Orion Health Get route details
      description: Retrieve detailed information about a specific integration route.
      tags:
      - Routes
      parameters:
      - name: routeId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Route details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /routes/{routeId}/start:
    post:
      operationId: startRoute
      summary: Orion Health Start a route
      description: Start a stopped integration route to begin processing messages.
      tags:
      - Routes
      parameters:
      - name: routeId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Route started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Route already started or in error state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /routes/{routeId}/stop:
    post:
      operationId: stopRoute
      summary: Orion Health Stop a route
      description: Stop an active integration route from processing messages.
      tags:
      - Routes
      parameters:
      - name: routeId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Route stopped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /routes/{routeId}/restart:
    post:
      operationId: restartRoute
      summary: Orion Health Restart a route
      description: Restart an integration route by stopping and starting it.
      tags:
      - Routes
      parameters:
      - name: routeId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Route restarted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /routes/{routeId}/statistics:
    get:
      operationId: getRouteStatistics
      summary: Orion Health Get route processing statistics
      description: Retrieve message processing statistics for a specific route including throughput, error rates, and processing times.
      tags:
      - Routes
      parameters:
      - name: routeId
        in: path
        required: true
        schema:
          type: integer
      - name: periodStart
        in: query
        schema:
          type: string
          format: date-time
      - name: periodEnd
        in: query
        schema:
          type: string
          format: date-time
      - name: interval
        in: query
        description: Statistics aggregation interval
        schema:
          type: string
          enum:
          - minute
          - hour
          - day
          - week
      responses:
        '200':
          description: Route statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteStatistics'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CommunicationPoint:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum:
          - input
          - output
          - bidirectional
        protocol:
          type: string
          enum:
          - tcp
          - http
          - https
          - sftp
          - database
          - file
          - web-service
          - mllp
          - smtp
          - pop3
        status:
          type: string
          enum:
          - started
          - stopped
          - error
          - disabled
        routeId:
          type: integer
        connectionCount:
          type: integer
    RouteStatus:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string
          enum:
          - started
          - stopped
          - error
          - disabled
        statusChangedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Route:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        folderPath:
          type: string
        status:
          type: string
          enum:
          - started
          - stopped
          - error
          - disabled
        inputCommPointCount:
          type: integer
        outputCommPointCount:
          type: integer
        filterCount:
          type: integer
        messagesProcessed:
          type: integer
          description: Total messages processed since last restart
        errorCount:
          type: integer
        lastMessageTime:
          type: string
          format: date-time
    RouteDetail:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        folderPath:
          type: string
        status:
          type: string
          enum:
          - started
          - stopped
          - error
          - disabled
        inputCommunicationPoints:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationPoint'
        outputCommunicationPoints:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationPoint'
        filters:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              type:
                type: string
              order:
                type: integer
        messagesProcessed:
          type: integer
        errorCount:
          type: integer
        averageProcessingTimeMs:
          type: number
        lastMessageTime:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
    RouteStatistics:
      type: object
      properties:
        routeId:
          type: integer
        routeName:
          type: string
        period:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        totalMessages:
          type: integer
        successfulMessages:
          type: integer
        errorMessages:
          type: integer
        averageProcessingTimeMs:
          type: number
        maxProcessingTimeMs:
          type: number
        messagesPerSecond:
          type: number
        timeline:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
              messagesProcessed:
                type: integer
              errors:
                type: integer
              avgProcessingTimeMs:
                type: number
    Pagination:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PageLimit:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageOffset:
      name: offset
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
        default: 0
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using SMART on FHIR
      flows:
        authorizationCode:
          authorizationUrl: https://auth.orionhealth.com/oauth2/authorize
          tokenUrl: https://auth.orionhealth.com/oauth2/token
          scopes:
            patient/*.read: Read access to all patient data
            patient/*.write: Write access to all patient data
            patient/Patient.read: Read access to Patient resources
            patient/Observation.read: Read access to Observation resources
            patient/Condition.read: Read access to Condition resources
            patient/MedicationRequest.read: Read access to MedicationRequest resources
            launch: Launch context
            openid: OpenID Connect
            fhirUser: FHIR user identity
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT