openapi: 3.0.3
info:
  title: Tebra Data Clinical API
  description: 'Read-only REST access to a patient''s clinical health information held in the Tebra (formerly Kareo + PatientPop) platform. This is Tebra''s ONC / 21st Century Cures Act "patient access" API surface (published under tebra.com/macra), exposing USCDI-aligned clinical resources for a single authenticated patient. Every request is authenticated with an API Key passed in the `X-Api-Key` header; the key is generated by the patient from the Tebra Patient Portal under My Account > API Access Key. Connections must use HTTPS (TLS) and callers are asked to limit connection frequency to what their use case requires.

    The resource paths and the X-Api-Key authentication in this document are confirmed from Tebra''s official "General API Documentation" (Oct 2023). The request query parameters and response schemas below are MODELED to reflect typical USCDI / FHIR-flavored patient-access payloads and should be verified against the current Tebra API documentation before production use.'
  version: '1.0'
  contact:
    name: Tebra
    url: https://www.tebra.com/macra
  license:
    name: Proprietary (Tebra API Terms of Use)
    url: https://www.tebra.com
servers:
- url: https://api.tebra.com/clinical/v1/api
  description: Tebra Clinical Data API (production)
security:
- apiKeyAuth: []
tags:
- name: Clinical
  description: USCDI-aligned clinical data classes for the authenticated patient.
paths:
  /patient/allergyIntolerance/medication:
    get:
      tags:
      - Clinical
      summary: Get medication allergies and intolerances
      description: Retrieves allergy and intolerance records associated with the patient. Confirmed endpoint; response is modeled as a USCDI AllergyIntolerance list.
      operationId: getAllergyIntolerance
      responses:
        '200':
          description: Allergy / intolerance list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/carePlan:
    get:
      tags:
      - Clinical
      summary: Get care plan
      description: Retrieves care plan entries for the patient. Confirmed endpoint; response modeled.
      operationId: getCarePlan
      responses:
        '200':
          description: Care plan list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/condition/problemList:
    get:
      tags:
      - Clinical
      summary: Get problem list conditions
      description: Retrieves problem-list conditions for the patient. Confirmed endpoint; response modeled.
      operationId: getProblemList
      responses:
        '200':
          description: Condition list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/device:
    get:
      tags:
      - Clinical
      summary: Get implantable devices
      description: Retrieves device records associated with the patient. Confirmed endpoint; response modeled.
      operationId: getDevice
      responses:
        '200':
          description: Device list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/diagnosticReport:
    get:
      tags:
      - Clinical
      summary: Get diagnostic reports
      description: Retrieves diagnostic report records for the patient. Confirmed endpoint; response modeled.
      operationId: getDiagnosticReport
      responses:
        '200':
          description: Diagnostic report list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/encounter:
    get:
      tags:
      - Clinical
      summary: Get encounters
      description: Retrieves encounter records associated with the patient. Confirmed endpoint; response modeled.
      operationId: getEncounter
      responses:
        '200':
          description: Encounter list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/goal:
    get:
      tags:
      - Clinical
      summary: Get goals
      description: Retrieves care goals for the patient. Confirmed endpoint; response modeled.
      operationId: getGoal
      responses:
        '200':
          description: Goal list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/immunization:
    get:
      tags:
      - Clinical
      summary: Get immunizations
      description: Retrieves immunization records for the patient. Confirmed endpoint; response modeled.
      operationId: getImmunization
      responses:
        '200':
          description: Immunization list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/medicationStatement:
    get:
      tags:
      - Clinical
      summary: Get medications
      description: Retrieves medication statement records for the patient. Confirmed endpoint; response modeled.
      operationId: getMedicationStatement
      responses:
        '200':
          description: Medication statement list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/observation/vitalSigns:
    get:
      tags:
      - Clinical
      summary: Get vital signs
      description: Retrieves vital sign observations for the patient. Confirmed endpoint; response modeled.
      operationId: getVitalSigns
      responses:
        '200':
          description: Vital sign observation list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/procedure:
    get:
      tags:
      - Clinical
      summary: Get procedures
      description: Retrieves procedure records for the patient. Confirmed endpoint; response modeled.
      operationId: getProcedure
      responses:
        '200':
          description: Procedure list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /patient/smokingStatus:
    get:
      tags:
      - Clinical
      summary: Get smoking status
      description: Retrieves the patient's smoking status observation. Confirmed endpoint; response modeled.
      operationId: getSmokingStatus
      responses:
        '200':
          description: Smoking status observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Error:
      type: object
      properties:
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Unauthorized
    ResourceList:
      type: object
      description: Generic container for a list of USCDI-aligned clinical resources (modeled). Actual payloads follow Tebra's clinical data format.
      properties:
        resourceType:
          type: string
        entry:
          type: array
          items:
            type: object
            additionalProperties: true
  responses:
    Unauthorized:
      description: The API Key is missing, revoked, or otherwise not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Patient-generated API Key from the Tebra Patient Portal (My Account > API Access Key). A missing, revoked, or invalid key returns 401 Unauthorized.