Data model

Latido normalizes every provider into six record families. A developer never converts per provider: the field names and units below are the same whether the data came from Garmin, Oura, Apple Health or the demo provider. The tables at the end of this page are generated from the API's own schemas.

#Conventions

• Units are fixed and SI-like: meters, seconds, kilograms, kilocalories, beats per minute, watts, m/s, milliseconds for HRV (RMSSD), mg/dL for glucose, °C, percentages on 0-100. The unit is in the field name (distanceMeters, durationSeconds, weightKg…).
• Absent means unknown, never zero. A field the provider did not give is left out: "no data" and "zero" are different answers.
• Time. Instants are ISO 8601 (startTime, measuredAt…), stored in UTC; utcOffsetMinutes keeps the member's wall clock. Days (date) are the member's local calendar day, YYYY-MM-DD — for sleep, the day they woke up.
• Ids. id is Latido's (rec_…); providerRecordId is the provider's own. With the data type, providerRecordId is unique per connection: a provider correcting a record updates it in place (and raises *.updated where that event exists).
• Raw payload. Every record synced from a provider keeps the provider's payload verbatim (mobile uploads have none). Add include=raw ({ include: "raw" } in the SDK) to a list or GET /v1/records/{id} and each record gains raw. Webhooks and MCP never carry it.
• Sources. For aggregators (Apple Health, Health Connect) source.appName names the app that wrote the record and source.deviceName / deviceManufacturer the device.

#Reading records

GET /v1/members/{memberId}/{workouts | sleep-sessions | daily-summaries | body-measurements | heart-rate | glucose}
    ?from=2026-10-01&to=2026-10-27T00:00:00Z&provider=garmin&include=raw&limit=50&cursor=…
GET /v1/records/{recordId}?include=raw

• Newest first. from (inclusive) and to (exclusive) are ISO dates or instants, compared with the record's start.
• Pages of limit (1-200, default 50); meta.nextCursor is absent on the last page.
• SDK: latido.members.workouts.list(memberId, query) for one page, latido.members.workouts.iterate(memberId, query) for all of them; sleepSessions, dailySummaries, bodyMeasurements, heartRate, glucose likewise. Each family's type is exported (WorkoutRecord, SleepSessionRecord, …), and the SDK checks that every record of a page is of the family asked for.

{
  "data": [
    {
      "id": "rec_V1StGXR8_Z5jdHi6B",
      "type": "workout",
      "memberId": "mem_…",
      "connectionId": "conn_…",
      "provider": "garmin",
      "providerRecordId": "17234567890",
      "sport": "running",
      "providerSport": "RUNNING",
      "startTime": "2026-10-25T06:00:00.000Z",
      "endTime": "2026-10-25T07:00:00.000Z",
      "utcOffsetMinutes": 120,
      "durationSeconds": 3600,
      "distanceMeters": 10000,
      "averageHeartRateBpm": 148,
      "hasFile": false,
      "createdAt": "2026-10-25T07:05:12.000Z",
      "updatedAt": "2026-10-25T07:05:12.000Z"
    }
  ],
  "meta": { "nextCursor": "eyJ0Ijoi…" }
}

#Members and connections

• Member (mem_…): your end user, known by your externalUserId (unique per project and mode) with optional metadata (≤ 2 KB JSON). GET /v1/members/{id} adds connections and recordCounts (records stored per data type, every type present).
• Connection (conn_…): one member × one provider — status (pending, active, expired, revoked, error), scopes, providerUserId / providerUserLabel, lastSyncedAt, backfill (status: pending | running | completed | failed, from, completedAt) and lastError (code, message, at). Tokens never leave the backend.

#Planned workouts

POST /v1/members/{memberId}/planned-workouts with { provider, workout } sends a structured workout to a device: name (≤ 100), sport (SportType), scheduledDate? (YYYY-MM-DD, the member's day), description?, and 1-100 steps. A step has a kind (warmup, active, recovery, cooldown, rest, repeat), an optional durationSeconds (≤ 86,400) or distanceMeters, optional target ranges { min, max } — targetHeartRateBpm, targetPowerWatts, targetPaceSecondsPerKm — and a note. A repeat step runs its steps (≤ 50) repeat times (1-100). The answer is queued; GET /v1/planned-workouts/{id} and the planned_workout.pushed / .failed webhooks report the outcome.

#Field reference

#Common fields

Every record, whatever its family, carries these.

#Workout (workout)

GET /v1/members/{memberId}/workouts · SDK latido.members.workouts

heartRateZones[] items:

laps[] items:

#Daily summary (daily_summary)

GET /v1/members/{memberId}/daily-summaries · SDK latido.members.dailySummaries

#Sleep session (sleep_session)

GET /v1/members/{memberId}/sleep-sessions · SDK latido.members.sleepSessions

stages[] items:

#Body measurement (body_measurement)

GET /v1/members/{memberId}/body-measurements · SDK latido.members.bodyMeasurements

#Heart-rate samples (heart_rate_sample)

GET /v1/members/{memberId}/heart-rate · SDK latido.members.heartRate

samples[] items:

#Glucose sample (glucose_sample)

GET /v1/members/{memberId}/glucose · SDK latido.members.glucose

#Providers and what they carry

From the provider catalog (packages/common/lib/health/provider-catalog.ts). AI is allowsAiProcessing: when no, MCP tools never return the provider's records.

#Sports (SportType)

Every provider's activity types map onto these; anything unmapped is other, with the original kept in providerSport.

running, trail_running, treadmill_running, track_running, walking, hiking, cycling, mountain_biking, gravel_cycling, indoor_cycling, virtual_cycling, e_biking, pool_swimming, open_water_swimming, triathlon, rowing, indoor_rowing, kayaking, stand_up_paddling, surfing, cross_country_skiing, alpine_skiing, snowboarding, strength_training, hiit, crossfit, yoga, pilates, elliptical, stair_climbing, climbing, bouldering, tennis, padel, soccer, basketball, golf, martial_arts, boxing, dance, meditation, breathwork, mobility, other