openapi: 3.0.3
info:
  title: BodyTrace RPM Data Alerts Provisioning API
  description: 'HTTP API for BodyTrace cellular-connected remote patient monitoring (RPM) devices - blood pressure monitors, body-weight scales, and pulse oximeters. Devices transmit measurements directly over the cellular network to the BodyTrace platform; healthcare organizations then read those readings over this API. Authentication is HTTP Basic using credentials issued by BodyTrace.

    Scope and honesty note: BodyTrace does not publish an open, self-serve developer portal - device provisioning and API credentials are arranged through BodyTrace sales, and the reference docs live behind partner onboarding (BodyTrace''s own docs plus integrator guides such as Validic). The one endpoint publicly and repeatedly documented in the wild is the data values pull, `GET /1/device/{imei}/datavalues`, and the device push message payload. Those are marked CONFIRMED below. The remaining operations (raw data messages, device listing/status, alerts, and provisioning) are HONESTLY MODELED from BodyTrace''s documented IMEI-centric data model and RPM feature set; their exact paths and parameters should be verified against the partner documentation you receive with credentials. Modeled operations carry `x-endpoint-status: modeled`; confirmed ones carry `x-endpoint-status: confirmed`.

    Delivery model: readings can be pulled from the data values endpoint on a polling loop, or pushed by BodyTrace to a customer-hosted HTTP endpoint (a webhook you host and secure). There is no documented public WebSocket surface.'
  version: '1.0'
  contact:
    name: BodyTrace
    url: https://www.bodytrace.com
  license:
    name: Proprietary
    url: https://www.bodytrace.com
servers:
- url: https://us.data.bodytrace.com/1
  description: BodyTrace US data region
- url: https://eu.data.bodytrace.com/1
  description: BodyTrace EU data region (region assigned by BodyTrace)
security:
- basicAuth: []
tags:
- name: Provisioning
  description: Modeled device enrollment and delivery configuration.
paths:
  /device/{imei}/provision:
    parameters:
    - $ref: '#/components/parameters/Imei'
    post:
      operationId: provisionDevice
      tags:
      - Provisioning
      summary: Provision a device
      description: Associate a device (by IMEI) with an account, patient, or program and configure where its measurements are delivered - including an optional pushed HTTP endpoint (webhook) that BodyTrace should POST readings to. MODELED from BodyTrace's documented onboarding flow; provisioning is completed with BodyTrace and gated behind credentials.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionInput'
      responses:
        '200':
          description: The provisioned device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ProvisionInput:
      type: object
      required:
      - imei
      properties:
        imei:
          type: string
          description: The device IMEI to provision.
        deviceType:
          type: string
          enum:
          - scale
          - bloodPressure
          - pulseOximeter
        externalId:
          type: string
          description: Your patient/program identifier to associate with the device.
        pushUrl:
          type: string
          format: uri
          description: Optional customer-hosted HTTPS endpoint BodyTrace should POST each measurement to (secured with HTTP Basic credentials you provide).
    Device:
      type: object
      description: A provisioned cellular device.
      properties:
        imei:
          type: string
        deviceType:
          type: string
          description: Device family, e.g. scale, bloodPressure, pulseOximeter.
          enum:
          - scale
          - bloodPressure
          - pulseOximeter
        lastSeen:
          type: integer
          format: int64
          description: Last transmission timestamp, epoch milliseconds (UTC).
        batteryVoltage:
          type: integer
        signalStrength:
          type: integer
        provisioned:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  parameters:
    Imei:
      name: imei
      in: path
      required: true
      description: The device IMEI (serial). BodyTrace documents this as the IMEI without leading zeros and without the final check digit.
      schema:
        type: string
      example: '357872040012345'
  responses:
    Unauthorized:
      description: Missing or invalid HTTP Basic credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the username and password issued by BodyTrace for your account. The same credential model secures the customer-hosted push endpoint (you define the username/password BodyTrace uses when POSTing measurements to you).