Data Types - MTH Health Docs

ConnectionResponse

Returned when listing connections or as part of the providers list. Represents an active OAuth connection between a user and a wearable provider.

Field	Type	Description
`id`	`string (UUID)`	Connection ID
`userId`	`string (UUID)`	The user this connection belongs to
`provider`	`string`	Provider name: `Fitbit`, `Garmin`, `Whoop`, or `Dexcom`
`providerUserId`	`string`	The user's ID on the provider's platform
`status`	`string`	Connection status: `Active`, `Expired`, or `Disconnected`
`scopes`	`string \| null`	OAuth scopes granted
`tokenExpiresAt`	`string (ISO 8601)`	When the OAuth access token expires
`createdAt`	`string (ISO 8601)`	When the connection was established
`updatedAt`	`string (ISO 8601)`	When the connection was last updated

Example

{
  "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "Dexcom",
  "providerUserId": "dexcom-user-id",
  "status": "Active",
  "scopes": "offline_access",
  "tokenExpiresAt": "2026-03-24T10:00:00Z",
  "createdAt": "2026-03-17T10:00:00Z",
  "updatedAt": "2026-03-17T10:00:00Z"
}

ConnectSessionResponse

Returned when creating an OAuth connect session. Contains the authorization URL to redirect the end user to.

Field	Type	Description
`id`	`string (UUID)`	Session ID
`authorizationUrl`	`string`	URL to redirect the user to for OAuth authorization
`expiresAt`	`string (ISO 8601)`	When this session expires (typically 10 minutes)

Example

{
  "id": "f8a1b2c3-d4e5-6789-0abc-def123456789",
  "authorizationUrl": "https://sandbox-api.dexcom.com/v3/oauth2/login?...",
  "expiresAt": "2026-03-17T10:10:00Z"
}

DailyActivityResponse

Returned by the connection activity endpoint. Contains daily activity metrics from a specific provider connection.

This schema is currently relevant for providers that expose a traditional daily activity summary, such as Fitbit and Garmin. WHOOP uses the load-oriented response below, and unsupported providers return 404 for the legacy activity route.

Field	Type	Description
`steps`	`integer`	Total steps for the day
`caloriesOut`	`integer`	Total calories burned
`distance`	`number`	Distance traveled (km)
`fairlyActiveMinutes`	`integer`	Minutes of moderate activity
`veryActiveMinutes`	`integer`	Minutes of vigorous activity
`rawJson`	`string`	Raw JSON from the provider (for debugging or custom parsing)

Example

{
  "steps": 8432,
  "caloriesOut": 2180,
  "distance": 6.34,
  "fairlyActiveMinutes": 25,
  "veryActiveMinutes": 22,
  "rawJson": "{...}"
}

DailyActivityEntryResponse

Returned by the user-scoped activity range endpoint. Each entry is a canonical daily summary for a specific provider connection and date.

Field	Type	Description
`connectionId`	`string (UUID)`	Connection that produced the entry
`provider`	`string`	Provider name
`date`	`string`	Date in `YYYY-MM-DD` format
`steps`	`integer \| null`	Total steps when available
`caloriesOut`	`integer \| null`	Total calories burned when available
`distanceMeters`	`number \| null`	Distance in meters
`lightActiveMinutes`	`integer \| null`	Low-intensity active minutes
`moderateActiveMinutes`	`integer \| null`	Moderate active minutes
`vigorousActiveMinutes`	`integer \| null`	Vigorous active minutes
`sedentaryMinutes`	`integer \| null`	Sedentary minutes
`floorsClimbed`	`integer \| null`	Floors climbed

DailyActivityLoadResponse

Returned by the canonical activity-load endpoint. It represents provider-native or normalized daily load data, such as WHOOP cycle strain.

This shape is intended for load-oriented providers and may contain nullable fields when a provider does not supply a specific metric.

Field	Type	Description
`date`	`string`	Date bucket in `YYYY-MM-DD` format
`windowKind`	`string`	Time window type, such as `PhysiologicalCycle`
`windowStartUtc`	`string \| null`	UTC start time of the provider window
`windowEndUtc`	`string \| null`	UTC end time of the provider window
`loadScore`	`number \| null`	Provider-native or normalized load score
`loadScoreScale`	`string \| null`	Identifier for the score scale
`energyKilocalories`	`number \| null`	Energy expenditure in kilocalories
`averageHeartRate`	`integer \| null`	Average heart rate for the window
`maxHeartRate`	`integer \| null`	Maximum heart rate for the window
`distanceMeters`	`number \| null`	Distance in meters when available
`steps`	`integer \| null`	Step count when the provider exposes it
`zoneDurationsJson`	`string \| null`	Serialized provider zone duration payload
`sourceConfidence`	`string`	Whether the record is provider-native or derived

Example

{
  "date": "2026-03-15",
  "windowKind": "PhysiologicalCycle",
  "windowStartUtc": "2026-03-14T21:48:00Z",
  "windowEndUtc": "2026-03-15T07:12:00Z",
  "loadScore": 15.4,
  "loadScoreScale": "whoop-strain-0-21",
  "energyKilocalories": 612.5,
  "averageHeartRate": 70,
  "maxHeartRate": 188,
  "distanceMeters": null,
  "steps": null,
  "zoneDurationsJson": "{...}",
  "sourceConfidence": "ProviderNative"
}

DailyActivityLoadEntryResponse

Returned by the user-scoped activity-load range endpoint. Each entry is a load-oriented record for a specific provider connection and date.

Field	Type	Description
`connectionId`	`string (UUID)`	Connection that produced the entry
`provider`	`string`	Provider name
`date`	`string`	Date bucket in `YYYY-MM-DD` format
`windowKind`	`string`	Time window type
`windowStartUtc`	`string \| null`	UTC start time of the provider window
`windowEndUtc`	`string \| null`	UTC end time of the provider window
`loadScore`	`number \| null`	Provider-native or normalized load score
`loadScoreScale`	`string \| null`	Identifier for the score scale
`energyKilocalories`	`number \| null`	Energy expenditure in kilocalories
`averageHeartRate`	`integer \| null`	Average heart rate for the window
`maxHeartRate`	`integer \| null`	Maximum heart rate for the window
`distanceMeters`	`number \| null`	Distance in meters
`steps`	`integer \| null`	Step count when available
`zoneDurationsJson`	`string \| null`	Serialized provider zone duration payload
`sourceConfidence`	`string`	Whether the record is provider-native or derived

DailyScoreResponse

Returned by the daily scores endpoint. Each entry represents a single day's computed health scores.

Field	Type	Description
`date`	`string`	Date in `YYYY-MM-DD` format
`sleepScore`	`integer`	Sleep quality score (0-100)
`activityScore`	`integer`	Activity score (0-100)
`recoveryScore`	`integer`	Recovery score (0-100)
`overallScore`	`integer`	Weighted overall health score (0-100)
`components`	`object`	Detailed breakdown of score components

Example

{
  "date": "2026-03-15",
  "sleepScore": 82,
  "activityScore": 71,
  "recoveryScore": 78,
  "overallScore": 77,
  "components": { ... }
}

GlucoseDataResponse

Returned by the user-scoped glucose range endpoint. The payload contains three arrays: continuous glucose readings, glucose-related events, and calibration records.

Top-level shape

Field	Type	Description
`readings`	`GlucoseReadingEntryResponse[]`	Continuous glucose readings
`events`	`GlucoseEventEntryResponse[]`	Provider glucose events such as exercise or insulin
`calibrations`	`GlucoseCalibrationEntryResponse[]`	Calibration records

GlucoseReadingEntryResponse

Field	Type	Description
`connectionId`	`string (UUID)`	Connection that produced the reading
`provider`	`string`	Provider name
`date`	`string`	Date bucket in `YYYY-MM-DD` format
`systemTime`	`string \| null`	Provider system timestamp
`displayTime`	`string \| null`	User-facing reading timestamp
`value`	`integer \| null`	Glucose value
`trend`	`string \| null`	Trend descriptor
`trendRate`	`number \| null`	Trend rate
`unit`	`string \| null`	Measurement unit
`rateUnit`	`string \| null`	Trend-rate unit
`status`	`string \| null`	Provider reading status
`transmitterId`	`string \| null`	Provider transmitter identifier
`recordId`	`string`	Stable provider reading identifier

GlucoseEventEntryResponse

Field	Type	Description
`connectionId`	`string (UUID)`	Connection that produced the event
`provider`	`string`	Provider name
`date`	`string`	Date bucket in `YYYY-MM-DD` format
`systemTime`	`string \| null`	Provider system timestamp
`displayTime`	`string \| null`	User-facing event timestamp
`eventType`	`string`	Event type
`eventSubType`	`string \| null`	Optional provider event subtype
`value`	`number \| null`	Event value when applicable
`unit`	`string \| null`	Event unit when applicable
`eventId`	`string`	Stable provider event identifier

GlucoseCalibrationEntryResponse

Field	Type	Description
`connectionId`	`string (UUID)`	Connection that produced the calibration
`provider`	`string`	Provider name
`date`	`string`	Date bucket in `YYYY-MM-DD` format
`systemTime`	`string \| null`	Provider system timestamp
`displayTime`	`string \| null`	User-facing calibration timestamp
`value`	`number \| null`	Calibration value
`unit`	`string \| null`	Measurement unit

JournalEntryDetailResponse

Returned by manual create, scan create, detail fetch, and update endpoints. The detail response extends the summary shape with itemized foods or drinks and optional image metadata. The same shape is used for Meal, Drink, Water, and Coffee entries.

JournalNutrientsResponse

Field	Type	Description
`caloriesKcal`	`number \| null`	Total calories
`proteinGrams`	`number \| null`	Total protein
`carbsGrams`	`number \| null`	Total carbohydrates
`fatGrams`	`number \| null`	Total fat
`fiberGrams`	`number \| null`	Total fiber
`sugarGrams`	`number \| null`	Total sugar
`sodiumMg`	`number \| null`	Total sodium
`caffeineMg`	`number \| null`	Total caffeine
`volumeMl`	`number \| null`	Total liquid volume

JournalEntryItemResponse

Field	Type	Description
`id`	`string (UUID)`	Item identifier
`name`	`string`	Recognized or user-entered item name
`category`	`string`	Optional item grouping
`quantity`	`number \| null`	Item quantity
`unit`	`string \| null`	Serving unit such as `g`, `cup`, or `ml`
`estimatedWeightGrams`	`number \| null`	Estimated item weight
`nutrients`	`JournalNutrientsResponse`	Per-item nutrients
`confidence`	`number \| null`	AI confidence score from 0 to 1 when available

JournalEntryImageResponse

Field	Type	Description
`id`	`string (UUID)`	Image identifier
`storageProvider`	`string`	Backing storage provider
`fileName`	`string`	Original file name
`contentType`	`string`	MIME type
`sizeBytes`	`integer`	File size in bytes
`width`	`integer \| null`	Known width when available
`height`	`integer \| null`	Known height when available

JournalEntrySummaryResponse

Returned by GET /api/v1/users/{userId}/journal-entries?date=.... Each summary represents one meal, generic drink, water, or coffee entry for the requested journal date.

Field	Type	Description
`id`	`string (UUID)`	Journal entry identifier
`entryKind`	`string`	`Meal`, `Drink`, `Water`, or `Coffee`
`entrySource`	`string`	`Manual` or `AiImage`
`analysisStatus`	`string`	Current AI analysis lifecycle state
`title`	`string \| null`	Short entry label
`notes`	`string \| null`	User or AI notes
`consumedAtUtc`	`string`	UTC consumption timestamp
`journalDate`	`string`	Date bucket in `YYYY-MM-DD` format
`timezone`	`string`	Timezone used to derive `journalDate`
`isUserEdited`	`boolean`	Whether the user corrected the entry
`nutrients`	`JournalNutrientsResponse`	Normalized entry totals
`itemCount`	`integer`	Number of food/drink items in the entry
`hasImage`	`boolean`	Whether an uploaded source image exists

UserProviderConnectionsResponse

Returned by the providers list endpoint. Each entry pairs a ProviderInfo object with the user's connection to that provider (or null if not connected).

supportedDataTypes reflects the live adapter capabilities used by the backend rather than a static metadata list.

ProviderInfo

Field	Type	Description
`name`	`string`	Display name of the provider
`slug`	`string`	URL-safe identifier (e.g., `fitbit`, `dexcom`)
`authType`	`string`	OAuth type: `OAuth2` or `OAuth1`
`logoUrl`	`string \| null`	URL to the provider's logo image
`supportedDataTypes`	`string[]`	Array of supported data types

Full response shape

Example

[
  {
    "provider": {
      "name": "Whoop",
      "slug": "whoop",
      "authType": "OAuth2",
      "logoUrl": null,
      "supportedDataTypes": [
        "Sleep",
        "ActivitySession",
        "Recovery",
        "ActivityLoadDaily",
        "ProfileSnapshot",
        "BodyMeasurementSnapshot"
      ]
    },
    "connection": null
  },
  {
    "provider": {
      "name": "Dexcom",
      "slug": "dexcom",
      "authType": "OAuth2",
      "logoUrl": null,
      "supportedDataTypes": [
        "GlucoseReading",
        "GlucoseEvent",
        "GlucoseCalibration"
      ]
    },
    "connection": {
      "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider": "Dexcom",
      "providerUserId": "dexcom-user-id",
      "status": "Active",
      "scopes": "offline_access",
      "tokenExpiresAt": "2026-03-24T10:00:00Z",
      "createdAt": "2026-03-17T10:00:00Z",
      "updatedAt": "2026-03-17T10:00:00Z"
    }
  }
]

UserResponse

Returned by user read and update endpoints (GET, PATCH). User tokens are only issued on user creation and token rotation.

Field	Type	Description
`id`	`string (UUID)`	MTH Health internal user ID
`appId`	`string (UUID)`	The application this user belongs to
`externalUserId`	`string`	Your application's identifier for this user
`status`	`string`	User status: `Active` or `Deleted`
`locale`	`string \| null`	User locale (e.g., `en-US`)
`timezone`	`string \| null`	IANA timezone (e.g., `Europe/Brussels`)
`metadata`	`object \| null`	Arbitrary key-value metadata
`createdAt`	`string (ISO 8601)`	Timestamp when the user was created
`updatedAt`	`string (ISO 8601)`	Timestamp of last update

Example

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "appId": "e5f6g7h8-i9j0-1234-klmn-op5678901234",
  "externalUserId": "user-123",
  "status": "Active",
  "locale": "en-US",
  "timezone": "Europe/Brussels",
  "metadata": { "plan": "premium" },
  "createdAt": "2026-03-17T10:00:00Z",
  "updatedAt": "2026-03-17T10:00:00Z"
}

UserWithTokenResponse

Returned only when a fresh user token is issued, such as during POST /api/v1/users for either a newly created user or an idempotent re-create of an existing user.

Field	Type	Description
`id`	`string (UUID)`	MTH Health internal user ID
`appId`	`string (UUID)`	The application this user belongs to
`externalUserId`	`string`	Your application's identifier for this user
`status`	`string`	User status: `Active` or `Deleted`
`locale`	`string \| null`	User locale (e.g., `en-US`)
`timezone`	`string \| null`	IANA timezone (e.g., `Europe/Brussels`)
`metadata`	`object \| null`	Arbitrary key-value metadata
`token`	`string`	Freshly issued user token for user-scoped API operations
`createdAt`	`string (ISO 8601)`	Timestamp when the user was created
`updatedAt`	`string (ISO 8601)`	Timestamp of last update

WeeklyScoreResponse

Returned by the weekly scores endpoint. Each entry represents a week's aggregated health scores.

Field	Type	Description
`weekStartDate`	`string`	Monday of the week in `YYYY-MM-DD` format
`sleepScore`	`integer`	Average sleep score for the week (0-100)
`activityScore`	`integer`	Average activity score for the week (0-100)
`recoveryScore`	`integer`	Average recovery score for the week (0-100)
`overallScore`	`integer`	Average overall score for the week (0-100)
`daysWithData`	`integer`	Number of days in the week that had health data

Example

{
  "weekStartDate": "2026-03-10",
  "sleepScore": 80,
  "activityScore": 68,
  "recoveryScore": 75,
  "overallScore": 74,
  "daysWithData": 5
}