BodyTrace Observations API

openapi: 3.0.3
info:
  title: BodyTrace RPM Data Alerts Observations 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: Observations
  description: Confirmed pull surface for device readings (data values).
paths:
  /device/{imei}/datavalues:
    parameters:
    - $ref: '#/components/parameters/Imei'
    get:
      operationId: getDeviceDataValues
      tags:
      - Observations
      summary: Get device data values (readings)
      description: Retrieve the latest and historical readings for a device by IMEI. Use the `names` query parameter to select which values to return - for example `values/weight`, `values/systolic`, `values/diastolic`, `values/pulse`, `batteryVoltage`, and `signalStrength` - and optionally bound the results with a time range. This is the confirmed, publicly documented BodyTrace pull endpoint.
      x-endpoint-status: confirmed
      parameters:
      - name: names
        in: query
        required: false
        description: Comma-separated list of value names to return, e.g. `batteryVoltage,signalStrength,values/weight,values/unit`. For blood pressure use `values/systolic,values/diastolic,values/pulse`.
        schema:
          type: string
          example: batteryVoltage,signalStrength,values/weight,values/unit
      - name: from
        in: query
        required: false
        description: Start of the time window, epoch milliseconds (UTC).
        schema:
          type: integer
          format: int64
      - name: to
        in: query
        required: false
        description: End of the time window, epoch milliseconds (UTC).
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        required: false
        description: Maximum number of readings to return.
        schema:
          type: integer
      responses:
        '200':
          description: The requested device readings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataValue'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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'
    NotFound:
      description: The device or resource was not found / not registered.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Values:
      type: object
      description: Measurement payload. The populated fields depend on the device type. A scale reports weight/tare; a blood pressure monitor reports systolic/diastolic/pulse; a pulse oximeter reports spo2/pulse. An empty values object indicates a heartbeat / connectivity message.
      properties:
        unit:
          type: integer
          description: Unit setting for the measurement (device-defined).
        weight:
          type: integer
          description: Body weight in grams (scale).
        tare:
          type: integer
          description: Tare / calibration offset in grams (scale).
        systolic:
          type: integer
          description: Systolic blood pressure in mmHg (BP monitor).
        diastolic:
          type: integer
          description: Diastolic blood pressure in mmHg (BP monitor).
        pulse:
          type: integer
          description: Pulse in beats per minute (BP monitor / pulse oximeter).
        spo2:
          type: integer
          description: Blood oxygen saturation as a percentage (pulse oximeter).
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    DataValue:
      type: object
      description: A single reading returned by the data values endpoint.
      properties:
        ts:
          type: integer
          format: int64
          description: Measurement timestamp, epoch milliseconds (UTC).
        batteryVoltage:
          type: integer
          description: Battery voltage in millivolts.
        signalStrength:
          type: integer
          description: Cellular signal strength.
        rssi:
          type: integer
          description: Signal strength in negative dBm (raw radio metric).
        values:
          $ref: '#/components/schemas/Values'
  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).