REST API v1

The VitalTrends API lets you query your own health data programmatically. Build scripts, notebooks, automations, or pipe your data into any tool you like.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Regenerate it from the Developer settings page if it is ever exposed.

Base URL

https://vitaltrends.net/api/v1

All public REST endpoints are versioned by URL path. The current stable version is v1.

All endpoints return JSON. Dates are ISO 8601 strings (YYYY-MM-DD). Timestamps are UTC unless a field is explicitly documented as a local date.

Versioning

v1 changelog

Endpoints

Workouts

curl -s "https://vitaltrends.net/api/v1/workouts/hevy?start=2026-05-01&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

WHOOP

Oura

Withings

Apple Health

Daily summary, one request for a full picture

Use this when you want the morning-dashboard shape: every metric for a given date, including a sleep stage breakdown (deep, rem, core, awake, in_bed) and full workout metadata (sport, duration, HR min/avg/max, energy, flights climbed).

curl -s "https://vitaltrends.net/api/v1/apple-health/daily-summary?date=2026-04-21" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": {
    "date": "2026-04-21",
    "activity": {
      "steps": 12500,
      "distance_km": 8.234,
      "active_energy_kcal": 487.2,
      "basal_energy_kcal": 1789.4,
      "apple_move_time_min": 45,
      "apple_exercise_time_min": 28,
      "apple_stand_time_min": 180,
      "flights_climbed": 12,
      "time_in_daylight_min": 87,
      "apple_stand_hours": 12
    },
    "heart": {
      "avg_heart_rate": 68,
      "min_heart_rate": 52,
      "max_heart_rate": 134,
      "resting_heart_rate": 56,
      "hrv_ms": 45.2,
      "respiratory_rate": 14.2,
      "spo2_pct": 97.8,
      "vo2_max": 42.5
    },
    "sleep": {
      "total_minutes": 452,
      "start_time": "2026-04-20T23:14:00+00:00",
      "end_time": "2026-04-21T06:46:00+00:00",
      "stages": {
        "deep_min": 68,
        "rem_min": 92,
        "core_min": 256,
        "light_min": 0,
        "awake_min": 36,
        "in_bed_min": 480,
        "unknown_min": 0
      },
      "sources": ["Apple Watch"]
    },
    "body": {
      "weight_kg": 75.20,
      "body_fat_pct": 18.40,
      "lean_body_mass_kg": 61.30,
      "bmi": 23.4,
      "height_m": 1.79,
      "body_comp_date": "2026-04-18"
    },
    "workouts": [
      {
        "uuid": "018f0a3b-1c7e-7d9a-8a2b-8c5c47b3d401",
        "type": "Functional Strength Training",
        "sport_key": "functional_strength_training",
        "start_time": "2026-04-21T07:02:00+00:00",
        "end_time": "2026-04-21T07:47:00+00:00",
        "duration_min": 45,
        "active_energy_kcal": 320,
        "distance_m": null,
        "avg_heart_rate": 132,
        "min_heart_rate": 85,
        "max_heart_rate": 165,
        "flights_climbed": 3,
        "elevation_gain_m": null,
        "source": "Apple Watch"
      }
    ]
  }
}

Per-type time series, with optional metadata

Use this when you want raw samples, a date range, or per-segment sleep stages. Pass include=metadata to reveal the metadata field (sleep stage, workout type, labels).

curl -s "https://vitaltrends.net/api/v1/apple-health?type=sleep&start=2026-04-20&end=2026-04-21&include=metadata" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": [
    {
      "data_type": "sleep",
      "date": "2026-04-20",
      "start_time": "2026-04-21T01:45:00+00:00",
      "end_time": "2026-04-21T05:45:00+00:00",
      "value": 0,
      "value_min": null,
      "value_max": null,
      "sample_count": 1,
      "unit": "hr",
      "source": "Apple Watch",
      "metadata": { "stage": "core" }
    },
    {
      "data_type": "sleep",
      "date": "2026-04-20",
      "start_time": "2026-04-20T23:15:00+00:00",
      "end_time": "2026-04-21T00:15:00+00:00",
      "value": 0,
      "value_min": null,
      "value_max": null,
      "sample_count": 1,
      "unit": "hr",
      "source": "Apple Watch",
      "metadata": { "stage": "deep" }
    }
  ],
  "links": { "first": "...", "last": null, "prev": null, "next": null },
  "meta": { "current_page": 1, "from": 1, "path": "...", "per_page": 50, "to": 2 }
}

Valid type values

Availability depends on which HealthKit sensors and iOS version your device supports. Types that are defined but not yet ingested by the VitalTrends iOS companion app are listed in meta.unavailable_types on the daily summary response.

Query parameters

All list endpoints support the following parameters:

For timestamp-backed endpoints, date-only start and end values are interpreted as full calendar-day boundaries in your profile timezone. Date-backed Apple Health aggregate endpoints and Oura daily endpoints compare against the stored date value directly.

On /whoop/daily, date remains the legacy cycle-end date for closed cycles; use cycle_start_date and cycle_end_date when you need explicit local cycle dates. If the user's current local-day cycle is still open, the endpoint may include it with is_partial: true and cycle_end_date: null. For morning automations, /whoop/daily is the canonical endpoint for deciding whether today's WHOOP recovery and sleep row is usable: select the row where cycle_start_date equals the user's local date and require both recovery_score and sleep_duration_minutes.

WHOOP recovery freshness

Use /whoop/recovery-status as advisory sync metadata only. It is useful when an automation needs to know whether VitalTrends recently checked, changed, or received upstream recovery data, but it is not a current-day completeness gate. Its latest_recovery and latest_cycle summaries use raw WHOOP cycle timestamps and do not apply the /whoop/daily sleep wake-day normalization for open cycles. last_recovery_data_changed_at advances only when stored recovery values change. last_recovery_synced_at advances when VitalTrends checks/applies recovery data, even if values are unchanged.

curl -s "https://vitaltrends.net/api/v1/whoop/recovery-status" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

{
  "data": {
    "connected": true,
    "needs_reconnection": false,
    "latest_recovery": {
      "cycle_id": "123e4567-e89b-12d3-a456-426614174000",
      "cycle_start_date": "2026-05-08",
      "cycle_end_date": "2026-05-09",
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "recovery_synced_at": "2026-05-09T07:06:00+00:00",
      "recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
      "whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00"
    },
    "latest_cycle": {
      "cycle_id": "123e4567-e89b-12d3-a456-426614174000",
      "cycle_start_date": "2026-05-08",
      "cycle_end_date": "2026-05-09",
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "recovery_synced_at": "2026-05-09T07:06:00+00:00",
      "recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
      "whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00"
    },
    "last_recovery_synced_at": "2026-05-09T07:06:00+00:00",
    "last_recovery_data_changed_at": "2026-05-09T07:06:00+00:00",
    "last_whoop_recovery_updated_at": "2026-05-09T07:05:00+00:00",
    "is_recovery_data_stale": false,
    "stale_after_hours": 24
  }
}

If is_recovery_data_stale is true or last_recovery_data_changed_at is more than 24 hours old, treat recovery freshness as uncertain and try again later. Do not conclude that today's recovery or sleep row is missing until you have checked /whoop/daily for the user's current local cycle_start_date. Opening the VitalTrends WHOOP dashboard also triggers a small recent-window WHOOP refresh when the latest recovery appears stale.

WHOOP daily date is the legacy cycle-end date for closed cycles; use cycle_start_date, cycle_end_date, and is_partial when you need explicit local cycle boundaries. WHOOP workout fields ending in _milli are durations in milliseconds, and kilojoule is energy in kilojoules.

Oura duration fields are returned in the units provided by Oura. Sleep durations are seconds; workout distance is meters; calorie fields are kilocalories.

On /oura/workouts, source is Oura's own workout source value. For example, confirmed means the workout was saved in Oura after confirmation in the Oura app. It is not a VitalTrends confidence score or a cross-device verification status. Other common values include autodetected, manual, and workout_heart_rate.

Withings measurement fields ending in _kg are stored in kilograms, and fat_ratio_pct is a percentage. Empty Withings fields mean the connected device did not provide that metric for the measurement, not that VitalTrends rejected it.

Apple Health source is the HealthKit device or app label that wrote the sample, not a confidence or verification status. Pass include=metadata on /apple-health?type=<type> to see sleep stages and workout details. For cumulative daily metrics such as steps, distance, and energy, VitalTrends avoids double-counting by choosing the largest per-source daily total by default.

Example request

curl -s "https://vitaltrends.net/api/v1/whoop/daily?start=2024-01-01&per_page=7" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

curl -s "https://vitaltrends.net/api/v1/oura/daily-readiness?start=2026-05-01&per_page=7" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq .

Example response

{
  "data": [
    {
      "date": "2024-01-07",
      "cycle_start_date": "2024-01-06",
      "cycle_end_date": "2024-01-07",
      "is_partial": false,
      "recovery_score": 82,
      "hrv_rmssd_milli": 68.4,
      "resting_heart_rate": 48,
      "sleep_performance_pct": 89,
      "sleep_duration_minutes": 450,
      "strain": 12.4,
      "whoop_recovery_updated_at": "2024-01-07T07:05:00+00:00",
      "recovery_synced_at": "2024-01-07T07:06:00+00:00",
      "recovery_data_changed_at": "2024-01-07T07:06:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 7,
    "total": 7,
    "from": 1,
    "to": 7
  }
}

Rate limits

The API allows 120 requests per minute per API key. If you exceed the limit, requests return 429 Too Many Requests with a Retry-After header.

Error responses

Need an endpoint that is not listed here? Get in touch and we will consider adding it.