---
title: "Sync telemetry and fitness data"
method: POST
path: "/api/v1/sync"
tags: ["Sync"]
---

# Sync telemetry and fitness data

`POST /api/v1/sync`

## Request

- Base URL: `https://api.hiyd.ai`
- URL: `https://api.hiyd.ai/api/v1/sync`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Receives and processes data from smartwatch devices or fitness trackers.
Supports three formats:
1. **FitnessTrackerData (NEW)**: Complete daily fitness summary with time-series, workouts, and sleep - idempotent by user+date
2. **Device batch format**: Send multiple telemetry readings in the `items` array - efficient for offline sync
3. **Device direct format**: Send single reading as direct object properties - simpler for real-time data

## Request body

- union
  - FitnessTrackerData: Complete daily fitness summary with time-series metrics, workouts, and sleep data. Idempotent by user + device + date. Note: user_id is extracted from JWT token.
    - `device_id` string, required: Unique device/smartwatch identifier (e.g., watch serial number, IMEI, or custom ID)
    - `date` string, date, required: Date for this daily summary (YYYY-MM-DD)
    - `time_series_metrics` object[]: Array of time-series health metrics throughout the day
      - `timestamp` string, date-time, required: Timestamp of the metric reading
      - `heart_rate` integer: Heart rate in BPM
      - `steps` integer: Step delta for this timestamp
      - `hrv` integer: Heart Rate Variability in milliseconds
      - `respiratory_rate` number: Breaths per minute
      - `spo2` integer: Blood oxygen saturation percentage (0-100)
    - `daily_cumulatives` object: Cumulative daily metrics
      - `steps` integer: Total steps taken
      - `total_calories_burned` integer: Total calories burned (kcal)
      - `active_calories_burned` integer: Active calories burned during workouts (kcal)
      - `distance_meters` number: Total distance traveled in meters
      - `floors_climbed` integer: Number of floors climbed
    - `detected_workouts` object[]: Array of detected workout sessions
      - `workout_type` 'run' | 'walk' | 'cycling' | 'swimming' | 'hiit' | 'other', required: Type of workout
      - `start_time` string, date-time, required: Workout start time
      - `end_time` string, date-time, required: Workout end time
      - `average_heart_rate` integer: Average heart rate during workout (BPM)
      - `calories_burned` integer: Calories burned during workout (kcal)
      - `intensity_score` number: Workout intensity score (0-10)
    - `sleep_data` object: Sleep summary for the night/day
      - `total_sleep_duration_minutes` integer: Total sleep duration in minutes
      - `sleep_score` integer: Overall sleep quality score (0-100)
      - `stages` object: Sleep stage breakdown
        - `rem_minutes` integer: REM sleep duration in minutes
        - `deep_minutes` integer: Deep sleep duration in minutes
        - `light_minutes` integer: Light sleep duration in minutes
        - `awake_minutes` integer: Time awake in minutes
      - `bedtime` string, date-time: Time went to bed
      - `wakeup_time` string, date-time: Time woke up
  - DeviceSyncRequest
    - `deviceId` string, required: Unique device identifier
    - `batchClientId` string: Optional batch client identifier
    - `timestamp` string, date-time: Timestamp of the telemetry data
    - `ppg` object: Photoplethysmography data
      - `heartRate` number: Heart rate in BPM
      - `spO2` number: Blood oxygen saturation percentage
    - `bloodPressure` object: Blood pressure measurements
      - `systolic_mmHg` number: Systolic pressure in mmHg
      - `diastolic_mmHg` number: Diastolic pressure in mmHg
    - `imu` object: Inertial Measurement Unit data
      - `accelerometer` object: Accelerometer readings in g
        - `x` number
        - `y` number
        - `z` number
      - `gyroscope` object: Gyroscope readings in degrees/second
        - `x` number
        - `y` number
        - `z` number
    - `environment` object: Environmental sensor data
      - `pressure_hPa` number: Atmospheric pressure in hPa
      - `temperature_C` number: Temperature in Celsius
    - `deviceStatus` object: Device status information
      - `batteryLevel` number: Battery level percentage
      - `bleConnection` 'connected' | 'disconnected' | 'connecting': Bluetooth connection status
    - `items` object[]: Legacy format: Array of telemetry items (optional, for backward compatibility)
      - `timestamp` string, date-time
      - `ppg` Ppg (unresolved $ref)
      - `bloodPressure` BloodPressure (unresolved $ref)
      - `imu` Imu (unresolved $ref)
      - `environment` Environment (unresolved $ref)
      - `deviceStatus` DeviceStatus (unresolved $ref)

## Response `200`

Sync successful

- union
  - object
    - `status` string
    - `type` string
    - `user_id` string
    - `date` string
    - `batchId` string, uuid
  - object
    - `status` string
    - `type` string
    - `batchId` string, uuid

## Other responses

- `400`: Bad request - validation error
- `500`: Internal server error

---

[API](https://skmtc.dev/hiyd/apis/hiyd-backend-api.md) - [All operations](https://skmtc.dev/hiyd/apis/hiyd-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hiyd/apis/hiyd-backend-api/revisions/23598d347e1b?raw)