REST API Endpoints
🕸️ API info
Retrieve a list of all available provider integrations on the API.
GET /v2/integrations HTTP/1.1
Host: api.tryterra.co
Accept: */*
Returns list of all available integrations on the API
{
"providers": [
"FITBIT"
],
"sdk_resource": [
"APPLE"
],
"status": "success"
}
Retrieve a detailed list of supported integrations, optionally filtered by the developer's enabled integrations and the requirement for SDK usage.
If true
, allows SDK integrations to be included in the response.
GET /v2/integrations/detailed HTTP/1.1
Host: api.tryterra.co
Accept: */*
Successful response containing a list of integrations.
{
"status": "success",
"providers": [
{
"provider": "MAPMYFITNESS",
"name": "MapMyFitness",
"icon": "https://api.tryterra.co/v2/static/assets/img/app_icons/mapmyfitness.webp",
"setup": "API_KEYS_MANAGED",
"enabled": true,
"types": {
"activity": true,
"body": false,
"nutrition": false,
"daily": false,
"sleep": false,
"menstruation": false
}
}
]
}
🔌 Authentication
Creates a login link that allows end users to connect their fitness tracking account
Provider resource identifier (e.g., 'FITBIT', 'GARMIN', 'OURA'). See "Get detailed list of integrations" for available providers
FITBIT
your developer ID
testingTerra
POST /v2/auth/authenticateUser HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: text
Content-Type: application/json
Accept: */*
Content-Length: 111
{
"language": "text",
"reference_id": "text",
"auth_success_redirect_url": "text",
"auth_failure_redirect_url": "text"
}
{
"status": "success",
"user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
"auth_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=23BBG9&scope=settings+nutrition+sleep+heartrate+electrocardiogram+weight+respiratory_rate+oxygen_saturation+profile+temperature+cardio_fitness+activity+location&state=bLqqjPie9ptwoWm6VBxHCu6JkkoWJp"
}
Creates a token to be used with initConnection() functions in the Terra mobile SDKs in order to create a user record for Apple Health or Samsung Health (or equivalent)
POST /v2/auth/generateAuthToken HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"status": "success",
"token": "250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d",
"expires_in": 180
}
Generates a link to redirect an end user to for them to select an integration and log in with their fitness data provider
Comma separated list of providers to display on the device selection page. This overrides your selected sources on your dashboard
GARMIN,FITBIT,OURA,WITHINGS,SUUNTO
Display language of the widget
en
Identifier of the end user on your system, such as a user ID or email associated with them
[email protected]
URL the user is redirected to upon successful authentication
https://myapp.com/success
URL the user is redirected to upon unsuccessful authentication
https://myapp.com/failure
POST /v2/auth/generateWidgetSession HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 213
{
"providers": "GARMIN,FITBIT,OURA,WITHINGS,SUUNTO",
"language": "en",
"reference_id": "[email protected]",
"auth_success_redirect_url": "https://myapp.com/success",
"auth_failure_redirect_url": "https://myapp.com/failure"
}
{
"session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
"url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
"status": "success",
"expires_in": 900
}
Deletes all records of the user on Terra's end, revoking Terra's access to their data
Terra user ID (UUID format) to deauthenticate and remove from Terra system
DELETE /v2/auth/deauthenticateUser HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"status": "success"
}
💁♂️ User info
Used to query for information on one Terra user ID, or to query for all registered Terra User objects under one reference ID
user ID to query for
reference ID to query for
GET /v2/userInfo HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"status": "success",
"is_authenticated": true
}
Used to query for information for all Terra User IDs. Supports optional pagination via page
and per_page
. If page
is not provided, it returns all users in one go (backwards compatibility).
Zero-based page number. If omitted, results are not paginated.
0
Number of results per page (default is 500).
500
GET /v2/subscriptions HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"users": [
{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
}
]
}
Used to query for information for multiple Terra User IDs
List of user IDs to get information for
POST /v2/bulkUserInfo HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 8
[
"text"
]
[
{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
}
]
Fetches relevant profile info such as first & last name, birth date etc. for a given user ID
Terra user ID (UUID format) to retrieve data for
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
GET /v2/athlete HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"athlete": {
"age": 28,
"country": "United States",
"bio": "Passionate runner and cyclist",
"state": "California",
"last_name": "Smith",
"sex": "male",
"city": "San Francisco",
"email": "[email protected]",
"date_of_birth": "1999-11-23",
"first_name": "John",
"gender": "male",
"joined_provider": "2023-01-15",
"devices": [
{
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
}
]
},
"type": "athlete",
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
}
}
⏳ Historical Data retrieval
Fetches completed workout sessions, with a defined start and end time and activity type (e.g. running, cycling, etc.)
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/activity HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"active_durations_data": {
"activity_levels_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 4
}
],
"activity_seconds": 1800,
"inactivity_seconds": 600,
"low_intensity_seconds": 900,
"moderate_intensity_seconds": 600,
"num_continuous_inactive_periods": 3,
"rest_seconds": 120,
"vigorous_intensity_seconds": 300,
"standing_hours_count": 1,
"standing_seconds": 1
},
"calories_data": {
"BMR_calories": 1,
"calorie_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"calories": 1,
"timer_duration_seconds": 1
}
],
"net_activity_calories": 1,
"net_intake_calories": 1,
"total_burned_calories": 1
},
"cheat_detection": 0,
"data_enrichment": {
"stress_score": 1
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"distance_data": {
"detailed": {
"distance_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"distance_meters": 2500,
"timer_duration_seconds": 900
}
],
"elevation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"elev_meters": 925,
"timer_duration_seconds": 1200
}
],
"floors_climbed_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"floors_climbed": 5,
"timer_duration_seconds": 600
}
],
"step_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"steps": 1,
"timer_duration_seconds": 1
}
]
},
"summary": {
"distance_meters": 1,
"elevation": {
"avg_meters": 950,
"gain_actual_meters": 550,
"gain_planned_meters": 500,
"loss_actual_meters": 450,
"max_meters": 1200,
"min_meters": 800
},
"floors_climbed": 1,
"steps": 1,
"swimming": {
"num_laps": 20,
"num_strokes": 500,
"pool_length_meters": 25
}
}
},
"energy_data": {
"energy_kilojoules": 1200,
"energy_planned_kilojoules": 1150
},
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"lap_data": {
"laps": [
{
"calories": 50,
"avg_hr_bpm": 145,
"start_time": "1999-11-23T09:00:00.000000+02:00",
"avg_speed_meters_per_second": 3.5,
"distance_meters": 400,
"total_strokes": 20,
"end_time": "2022-10-28T10:00:00.000000+01:00",
"stroke_type": "freestyle"
}
]
},
"MET_data": {
"MET_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 1
}
],
"avg_level": 3.8,
"num_high_intensity_minutes": 10,
"num_inactive_minutes": 5,
"num_low_intensity_minutes": 15,
"num_moderate_intensity_minutes": 25
},
"metadata": {
"city": "San Francisco",
"country": "United States",
"end_time": "2022-10-28T10:00:00.000000+01:00",
"name": "Morning Run",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"state": "California",
"summary_id": "123e4567-e89b-12d3-a456-426614174000",
"timestamp_localization": 0,
"type": 8,
"upload_type": 1
},
"movement_data": {
"adjusted_max_speed_meters_per_second": 4.2,
"avg_cadence_rpm": 85,
"avg_pace_minutes_per_kilometer": 6.2,
"avg_speed_meters_per_second": 3.2,
"avg_torque_newton_meters": 40,
"avg_velocity_meters_per_second": 3,
"cadence_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"cadence_rpm": 1,
"timer_duration_seconds": 1
}
],
"max_cadence_rpm": 110,
"max_pace_minutes_per_kilometer": 6.5,
"max_speed_meters_per_second": 4.5,
"max_torque_newton_meters": 55.5,
"max_velocity_meters_per_second": 4.5,
"normalized_speed_meters_per_second": 3.8,
"speed_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"speed_meters_per_second": 1,
"timer_duration_seconds": 1
}
],
"torque_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"timer_duration_seconds": 300,
"torque_newton_meters": 45.5
}
]
},
"oxygen_data": {
"avg_saturation_percentage": 98,
"saturation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"vo2_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"vo2max_ml_per_min_per_kg": 45.5
}
],
"vo2max_ml_per_min_per_kg": 45.5
},
"polyline_map_data": {
"summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
},
"position_data": {
"center_pos_lat_lng_deg": [
-18.4911,
130.9123
],
"end_pos_lat_lng_deg": [
-84.4911,
-150.9123
],
"position_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"coords_lat_lng_deg": [
-18.4911,
130.9123
],
"timer_duration_seconds": 300
}
],
"start_pos_lat_lng_deg": [
80.2394,
102.931
]
},
"power_data": {
"avg_watts": 185,
"max_watts": 350,
"power_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"watts": 250,
"timer_duration_seconds": 1800
}
]
},
"strain_data": {
"strain_level": 14.5
},
"TSS_data": {
"TSS_samples": [
{
"planned": 1,
"actual": 1,
"method": "text",
"intensity_factor_planned": 1,
"intensity_factor_actual": 1,
"normalized_power_watts": 1
}
]
},
"work_data": {
"work_kilojoules": 450.5
}
}
],
"type": null
}
Fetches body metrics such as weight, height, body fat percentage etc. for a given user ID
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/body HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"blood_pressure_data": {
"blood_pressure_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"diastolic_bp": 80.5,
"systolic_bp": 120.5
}
]
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"heart_data": {
"afib_classification_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"afib_classification": 1
}
],
"ecg_signal": [
{
"start_timestamp": "text",
"avg_hr_bpm": 72.5,
"afib_classification": 1,
"raw_signal": [
{
"potential_uV": 1250.5,
"timestamp": "2022-11-23T09:00:00.000000+02:00"
}
]
}
],
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"pulse_wave_velocity_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"pulse_wave_velocity_meters_per_second": 7.2
}
],
"rr_interval_samples": [
{
"rr_interval_ms": 850,
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hr_bpm": 72
}
]
},
"hydration_data": {
"day_total_water_consumption_ml": 2500,
"hydration_amount_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hydration_kg": 40
}
]
},
"ketone_data": {
"ketone_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"ketone_mg_per_dL": 1.5,
"sample_type": 1
}
]
},
"measurements_data": {
"measurements": [
{
"measurement_time": "2022-11-23T09:00:00.000000+02:00",
"BMI": 22.4,
"BMR": 1800,
"RMR": 2000,
"estimated_fitness_age": "25",
"skin_fold_mm": 12.5,
"bodyfat_percentage": 18.5,
"weight_kg": 75.5,
"height_cm": 178,
"bone_mass_g": 3200,
"muscle_mass_g": 35000,
"lean_mass_g": 61500,
"water_percentage": 60.5,
"insulin_units": 10.5,
"insulin_type": "rapid-acting",
"urine_color": "pale yellow",
"user_notes": "text"
}
]
},
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0
},
"oxygen_data": {
"avg_saturation_percentage": 98,
"saturation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"vo2_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"vo2max_ml_per_min_per_kg": 45.5
}
],
"vo2max_ml_per_min_per_kg": 45.5
},
"temperature_data": {
"ambient_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
],
"body_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
],
"skin_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
]
},
"glucose_data": {
"blood_glucose_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"blood_glucose_mg_per_dL": 95,
"glucose_level_flag": 1,
"trend_arrow": 4
}
],
"detailed_blood_glucose_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"blood_glucose_mg_per_dL": 95,
"glucose_level_flag": 1,
"trend_arrow": 4
}
],
"day_avg_blood_glucose_mg_per_dL": 92.5,
"gmi": 1,
"time_in_range": 1,
"sensor_usage": 1,
"daily_patterns": [
{
"time_from_midnight": 9,
"percentile_5": 1,
"percentile_25": 1,
"percentile_50": 1,
"percentile_75": 1,
"percentile_95": 1
}
]
}
}
],
"type": null
}
Fetches daily summaries of activity metrics such as steps, distance, calories burned etc. for a given user ID
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/daily HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"active_durations_data": {
"activity_levels_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 4
}
],
"activity_seconds": 1800,
"inactivity_seconds": 600,
"low_intensity_seconds": 900,
"moderate_intensity_seconds": 600,
"num_continuous_inactive_periods": 3,
"rest_seconds": 120,
"vigorous_intensity_seconds": 300,
"standing_hours_count": 1,
"standing_seconds": 1
},
"calories_data": {
"BMR_calories": 1,
"calorie_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"calories": 1,
"timer_duration_seconds": 1
}
],
"net_activity_calories": 1,
"net_intake_calories": 1,
"total_burned_calories": 1
},
"data_enrichment": {
"cardiovascular_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"cardiovascular_score": 1,
"immune_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"immune_index": 1,
"readiness_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"readiness_score": 1,
"respiratory_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"respiratory_score": 1,
"start_time": "text",
"stress_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"total_stress_score": 1
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"distance_data": {
"detailed": {
"distance_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"distance_meters": 2500,
"timer_duration_seconds": 900
}
],
"elevation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"elev_meters": 925,
"timer_duration_seconds": 1200
}
],
"floors_climbed_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"floors_climbed": 5,
"timer_duration_seconds": 600
}
],
"step_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"steps": 1,
"timer_duration_seconds": 1
}
]
},
"distance_meters": 8500,
"elevation": {
"avg_meters": 950,
"gain_actual_meters": 550,
"gain_planned_meters": 500,
"loss_actual_meters": 450,
"max_meters": 1200,
"min_meters": 800
},
"floors_climbed": 15,
"steps": 12000,
"swimming": {
"num_laps": 20,
"num_strokes": 500,
"pool_length_meters": 25
}
},
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"MET_data": {
"MET_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 1
}
],
"avg_level": 3.8,
"num_high_intensity_minutes": 10,
"num_inactive_minutes": 5,
"num_low_intensity_minutes": 15,
"num_moderate_intensity_minutes": 25
},
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0,
"upload_type": 1
},
"oxygen_data": {
"avg_saturation_percentage": 98,
"saturation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"vo2_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"vo2max_ml_per_min_per_kg": 45.5
}
],
"vo2max_ml_per_min_per_kg": 45.5
},
"scores": {
"activity": 92,
"recovery": 78,
"sleep": 85
},
"strain_data": {
"strain_level": 14.5
},
"stress_data": {
"avg_stress_level": 45.5,
"activity_stress_duration_seconds": 3600,
"low_stress_duration_seconds": 28800,
"max_stress_level": 85,
"medium_stress_duration_seconds": 7200,
"samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 1
}
],
"rest_stress_duration_seconds": 1800,
"high_stress_duration_seconds": 900,
"stress_duration_seconds": 5400,
"stress_rating": 3,
"body_battery_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 1
}
]
},
"tag_data": {
"tags": [
{
"timestamp": "1999-11-23T09:00:00.000000+02:00",
"tag_name": "hot_shower",
"notes": "Felt refreshed after"
}
]
}
}
],
"type": null
}
Fetches menstruation data such as cycle length, period length, ovulation date etc. for a given user ID
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/menstruation HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0
},
"menstruation_data": {
"period_length_days": 5,
"current_phase": "menstrual",
"length_of_current_phase_days": 5,
"days_until_next_phase": 23,
"period_start_date": "2022-11-28",
"predicted_cycle_length_days": 28,
"day_in_cycle": 24,
"last_updated_time": "2022-12-12T14:03:05.000000-05:00",
"cycle_length_days": "28",
"is_predicted_cycle": "true",
"menstruation_flow": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"flow": 4
}
]
}
}
],
"type": null
}
Fetches nutrition log data such as meal type, calories, macronutrients etc. for a given user ID
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/nutrition HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"drink_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"drink_volume": 250,
"drink_unit": "ml",
"drink_name": "Water"
}
],
"meals": [
{
"micros": {
"biotin_mg": 0.03,
"caffeine_mg": 95,
"calcium_mg": 1000,
"chloride_mg": 2300,
"chromium_mg": 0.035,
"copper_mg": 0.9,
"folate_mg": 0.4,
"folic_acid_mg": 0.4,
"iodine_mg": 0.15,
"iron_mg": 8.5,
"magnesium_mg": 320,
"manganese_mg": 2.3,
"molybdenum_mg": 0.045,
"niacin_mg": 16,
"pantothenic_acid_mg": 5,
"phosphorus_mg": 1000,
"potassium_mg": 3500,
"riboflavin_mg": 1.3,
"selenium_mg": 0.055,
"thiamin_mg": 1.2,
"vitamin_A_mg": 0.9,
"vitamin_B12_mg": 0.0024,
"vitamin_B6_mg": 1.7,
"vitamin_C_mg": 90,
"vitamin_D_mg": 0.02,
"vitamin_D2_mg": 0.01,
"vitamin_D3_mg": 0.015,
"vitamin_E_mg": 15,
"vitamin_K_mg": 0.12,
"zinc_mg": 11,
"cystine_g": 0.3,
"histidine_g": 0.6,
"isoleucine_g": 0.8,
"leucine_g": 1.2,
"lysine_g": 0.9,
"methionine_g": 0.6,
"phenylalanine_g": 0.9,
"threonine_g": 0.5,
"tryptophan_g": 0.3,
"tyrosine_g": 0.7,
"valine_g": 0.8,
"monounsaturated_fat_g": 15,
"polyunsaturated_fat_g": 13,
"omega3_g": 1.6,
"omega6_g": 17,
"starch_g": 25
},
"type": 1,
"id": "food_123",
"timestamp": "2022-12-12T08:53:00.000000+02:00",
"quantity": {
"unit": 4,
"amount": 1
},
"name": "Oatmeal",
"macros": {
"alcohol_g": 14,
"calories": 2000,
"carbohydrates_g": 300,
"cholesterol_mg": 300,
"fat_g": 65,
"fiber_g": 25,
"net_carbohydrates_g": 275,
"protein_g": 50,
"saturated_fat_g": 20,
"sodium_mg": 2300,
"sugar_g": 25,
"trans_fat_g": 2
}
}
],
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0
},
"summary": {
"macros": {
"alcohol_g": 14,
"calories": 2000,
"carbohydrates_g": 300,
"cholesterol_mg": 300,
"fat_g": 65,
"fiber_g": 25,
"net_carbohydrates_g": 275,
"protein_g": 50,
"saturated_fat_g": 20,
"sodium_mg": 2300,
"sugar_g": 25,
"trans_fat_g": 2
},
"micros": {
"biotin_mg": 0.03,
"caffeine_mg": 95,
"calcium_mg": 1000,
"chloride_mg": 2300,
"chromium_mg": 0.035,
"copper_mg": 0.9,
"folate_mg": 0.4,
"folic_acid_mg": 0.4,
"iodine_mg": 0.15,
"iron_mg": 8.5,
"magnesium_mg": 320,
"manganese_mg": 2.3,
"molybdenum_mg": 0.045,
"niacin_mg": 16,
"pantothenic_acid_mg": 5,
"phosphorus_mg": 1000,
"potassium_mg": 3500,
"riboflavin_mg": 1.3,
"selenium_mg": 0.055,
"thiamin_mg": 1.2,
"vitamin_A_mg": 0.9,
"vitamin_B12_mg": 0.0024,
"vitamin_B6_mg": 1.7,
"vitamin_C_mg": 90,
"vitamin_D_mg": 0.02,
"vitamin_D2_mg": 0.01,
"vitamin_D3_mg": 0.015,
"vitamin_E_mg": 15,
"vitamin_K_mg": 0.12,
"zinc_mg": 11,
"cystine_g": 0.3,
"histidine_g": 0.6,
"isoleucine_g": 0.8,
"leucine_g": 1.2,
"lysine_g": 0.9,
"methionine_g": 0.6,
"phenylalanine_g": 0.9,
"threonine_g": 0.5,
"tryptophan_g": 0.3,
"tyrosine_g": 0.7,
"valine_g": 0.8,
"monounsaturated_fat_g": 15,
"polyunsaturated_fat_g": 13,
"omega3_g": 1.6,
"omega6_g": 17,
"starch_g": 25
},
"water_ml": 2000,
"drink_ml": 500
}
}
],
"type": null
}
Fetches sleep data such as sleep duration, sleep stages, sleep quality etc. for a given user ID, for sleep sessions with a defined start and end time
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
Boolean flag specifying whether to include detailed samples in the returned payload (default: false)
GET /v2/sleep HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"data_enrichment": {
"sleep_contributors": [
{
"contributor_name": "text",
"contributor_score": 1
}
],
"sleep_score": 1
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"metadata": {
"end_time": "2022-11-24T08:00:00.000000+01:00",
"is_nap": false,
"start_time": "1999-11-23T22:00:00.000000+02:00",
"summary_id": "text",
"timestamp_localization": 0,
"upload_type": 1
},
"readiness_data": {
"readiness": 85,
"recovery_level": 5
},
"respiration_data": {
"breaths_data": {
"avg_breaths_per_min": 14,
"max_breaths_per_min": 18,
"min_breaths_per_min": 10,
"on_demand_reading": false,
"samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"breaths_per_min": 16
}
],
"start_time": "1999-11-23T22:00:00.000000+02:00",
"end_time": "2022-11-24T08:00:00.000000+01:00"
},
"oxygen_saturation_data": {
"avg_saturation_percentage": 97,
"end_time": "2022-11-24T08:00:00.000000+01:00",
"samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"start_time": "1999-11-23T22:00:00.000000+02:00"
},
"snoring_data": {
"start_time": "1999-11-23T22:00:00.000000+02:00",
"end_time": "2022-11-24T08:00:00.000000+01:00",
"num_snoring_events": 12,
"samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"duration_seconds": 120
}
],
"total_snoring_duration_seconds": 3600
}
},
"scores": {
"sleep_score": 1
},
"sleep_durations_data": {
"asleep": {
"duration_asleep_state_seconds": 25200,
"duration_deep_sleep_state_seconds": 5400,
"duration_light_sleep_state_seconds": 14400,
"duration_REM_sleep_state_seconds": 5400,
"num_REM_events": 4
},
"awake": {
"duration_awake_state_seconds": 1200,
"duration_long_interruption_seconds": 600,
"duration_short_interruption_seconds": 180,
"num_out_of_bed_events": 1,
"num_wakeup_events": 3,
"sleep_latency_seconds": 900,
"wake_up_latency_seconds": 300
},
"hypnogram_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 2
}
],
"other": {
"duration_in_bed_seconds": 28800,
"duration_unmeasurable_sleep_seconds": 300
},
"sleep_efficiency": 87.5
},
"temperature_data": {
"delta": 0.5
}
}
],
"type": null
}
Used to get workout plans the user has registered on their account. This can be strength workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)
Terra user ID (UUID format) to retrieve data for
Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)
Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: false)
GET /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"data": [
{
"steps": [
{
"targets": [
{
"target_type": "HEART_RATE"
}
],
"type": "STEP",
"intensity": "REST",
"order": 1,
"description": "text",
"durations": [
{
"duration_type": "TIME"
}
],
"name": "text"
}
],
"metadata": {
"estimated_energy_kj": null,
"estimated_speed_meters_per_second": null,
"estimated_elevation_gain_meters": null,
"estimated_tss": null,
"estimated_calories": null,
"created_date": "2022-11-23T09:00:00.000000+02:00",
"planned_date": "2022-11-24T09:00:00.000000+02:00",
"type": "IN_VEHICLE",
"id": null,
"estimated_duration_seconds": null,
"estimated_pace_minutes_per_kilometer": null,
"provider": "text",
"estimated_tscore": null,
"description": null,
"name": null,
"estimated_distance_meters": null,
"estimated_if": null,
"pool_length_meters": null
}
}
],
"type": null
}
✏️ Writing data
Used to post activity data to a provider. This endpoint only works for users connected via Wahoo. Returns error for other providers.
POST /v2/activity HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 5155
{
"data": [
{
"active_durations_data": {
"activity_levels_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 4
}
],
"activity_seconds": 1800,
"inactivity_seconds": 600,
"low_intensity_seconds": 900,
"moderate_intensity_seconds": 600,
"num_continuous_inactive_periods": 3,
"rest_seconds": 120,
"vigorous_intensity_seconds": 300,
"standing_hours_count": 1,
"standing_seconds": 1
},
"calories_data": {
"BMR_calories": 1,
"calorie_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"calories": 1,
"timer_duration_seconds": 1
}
],
"net_activity_calories": 1,
"net_intake_calories": 1,
"total_burned_calories": 1
},
"cheat_detection": 0,
"data_enrichment": {
"stress_score": 1
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"distance_data": {
"detailed": {
"distance_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"distance_meters": 2500,
"timer_duration_seconds": 900
}
],
"elevation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"elev_meters": 925,
"timer_duration_seconds": 1200
}
],
"floors_climbed_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"floors_climbed": 5,
"timer_duration_seconds": 600
}
],
"step_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"steps": 1,
"timer_duration_seconds": 1
}
]
},
"summary": {
"distance_meters": 1,
"elevation": {
"avg_meters": 950,
"gain_actual_meters": 550,
"gain_planned_meters": 500,
"loss_actual_meters": 450,
"max_meters": 1200,
"min_meters": 800
},
"floors_climbed": 1,
"steps": 1,
"swimming": {
"num_laps": 20,
"num_strokes": 500,
"pool_length_meters": 25
}
}
},
"energy_data": {
"energy_kilojoules": 1200,
"energy_planned_kilojoules": 1150
},
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"lap_data": {
"laps": [
{
"calories": 50,
"avg_hr_bpm": 145,
"start_time": "1999-11-23T09:00:00.000000+02:00",
"avg_speed_meters_per_second": 3.5,
"distance_meters": 400,
"total_strokes": 20,
"end_time": "2022-10-28T10:00:00.000000+01:00",
"stroke_type": "freestyle"
}
]
},
"MET_data": {
"MET_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"level": 1
}
],
"avg_level": 3.8,
"num_high_intensity_minutes": 10,
"num_inactive_minutes": 5,
"num_low_intensity_minutes": 15,
"num_moderate_intensity_minutes": 25
},
"metadata": {
"city": "San Francisco",
"country": "United States",
"end_time": "2022-10-28T10:00:00.000000+01:00",
"name": "Morning Run",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"state": "California",
"summary_id": "123e4567-e89b-12d3-a456-426614174000",
"timestamp_localization": 0,
"type": 8,
"upload_type": 1
},
"movement_data": {
"adjusted_max_speed_meters_per_second": 4.2,
"avg_cadence_rpm": 85,
"avg_pace_minutes_per_kilometer": 6.2,
"avg_speed_meters_per_second": 3.2,
"avg_torque_newton_meters": 40,
"avg_velocity_meters_per_second": 3,
"cadence_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"cadence_rpm": 1,
"timer_duration_seconds": 1
}
],
"max_cadence_rpm": 110,
"max_pace_minutes_per_kilometer": 6.5,
"max_speed_meters_per_second": 4.5,
"max_torque_newton_meters": 55.5,
"max_velocity_meters_per_second": 4.5,
"normalized_speed_meters_per_second": 3.8,
"speed_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"speed_meters_per_second": 1,
"timer_duration_seconds": 1
}
],
"torque_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"timer_duration_seconds": 300,
"torque_newton_meters": 45.5
}
]
},
"oxygen_data": {
"avg_saturation_percentage": 98,
"saturation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"vo2_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"vo2max_ml_per_min_per_kg": 45.5
}
],
"vo2max_ml_per_min_per_kg": 45.5
},
"polyline_map_data": {
"summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
},
"position_data": {
"center_pos_lat_lng_deg": [
-18.4911,
130.9123
],
"end_pos_lat_lng_deg": [
-84.4911,
-150.9123
],
"position_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"coords_lat_lng_deg": [
-18.4911,
130.9123
],
"timer_duration_seconds": 300
}
],
"start_pos_lat_lng_deg": [
80.2394,
102.931
]
},
"power_data": {
"avg_watts": 185,
"max_watts": 350,
"power_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"watts": 250,
"timer_duration_seconds": 1800
}
]
},
"strain_data": {
"strain_level": 14.5
},
"TSS_data": {
"TSS_samples": [
{
"planned": 1,
"actual": 1,
"method": "text",
"intensity_factor_planned": 1,
"intensity_factor_actual": 1,
"normalized_power_watts": 1
}
]
},
"work_data": {
"work_kilojoules": 450.5
}
}
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"log_ids": [
"text"
],
"message": "Activity successfully logged"
}
Used to post nutrition logs to a provider. This endpoint only works for users connected via Fitbit. Returns error for other providers.
POST /v2/nutrition HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2618
{
"data": [
{
"drink_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"drink_volume": 250,
"drink_unit": "ml",
"drink_name": "Water"
}
],
"meals": [
{
"micros": {
"biotin_mg": 0.03,
"caffeine_mg": 95,
"calcium_mg": 1000,
"chloride_mg": 2300,
"chromium_mg": 0.035,
"copper_mg": 0.9,
"folate_mg": 0.4,
"folic_acid_mg": 0.4,
"iodine_mg": 0.15,
"iron_mg": 8.5,
"magnesium_mg": 320,
"manganese_mg": 2.3,
"molybdenum_mg": 0.045,
"niacin_mg": 16,
"pantothenic_acid_mg": 5,
"phosphorus_mg": 1000,
"potassium_mg": 3500,
"riboflavin_mg": 1.3,
"selenium_mg": 0.055,
"thiamin_mg": 1.2,
"vitamin_A_mg": 0.9,
"vitamin_B12_mg": 0.0024,
"vitamin_B6_mg": 1.7,
"vitamin_C_mg": 90,
"vitamin_D_mg": 0.02,
"vitamin_D2_mg": 0.01,
"vitamin_D3_mg": 0.015,
"vitamin_E_mg": 15,
"vitamin_K_mg": 0.12,
"zinc_mg": 11,
"cystine_g": 0.3,
"histidine_g": 0.6,
"isoleucine_g": 0.8,
"leucine_g": 1.2,
"lysine_g": 0.9,
"methionine_g": 0.6,
"phenylalanine_g": 0.9,
"threonine_g": 0.5,
"tryptophan_g": 0.3,
"tyrosine_g": 0.7,
"valine_g": 0.8,
"monounsaturated_fat_g": 15,
"polyunsaturated_fat_g": 13,
"omega3_g": 1.6,
"omega6_g": 17,
"starch_g": 25
},
"type": 1,
"id": "food_123",
"timestamp": "2022-12-12T08:53:00.000000+02:00",
"quantity": {
"unit": 4,
"amount": 1
},
"name": "Oatmeal",
"macros": {
"alcohol_g": 14,
"calories": 2000,
"carbohydrates_g": 300,
"cholesterol_mg": 300,
"fat_g": 65,
"fiber_g": 25,
"net_carbohydrates_g": 275,
"protein_g": 50,
"saturated_fat_g": 20,
"sodium_mg": 2300,
"sugar_g": 25,
"trans_fat_g": 2
}
}
],
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0
},
"summary": {
"macros": {
"alcohol_g": 14,
"calories": 2000,
"carbohydrates_g": 300,
"cholesterol_mg": 300,
"fat_g": 65,
"fiber_g": 25,
"net_carbohydrates_g": 275,
"protein_g": 50,
"saturated_fat_g": 20,
"sodium_mg": 2300,
"sugar_g": 25,
"trans_fat_g": 2
},
"micros": {
"biotin_mg": 0.03,
"caffeine_mg": 95,
"calcium_mg": 1000,
"chloride_mg": 2300,
"chromium_mg": 0.035,
"copper_mg": 0.9,
"folate_mg": 0.4,
"folic_acid_mg": 0.4,
"iodine_mg": 0.15,
"iron_mg": 8.5,
"magnesium_mg": 320,
"manganese_mg": 2.3,
"molybdenum_mg": 0.045,
"niacin_mg": 16,
"pantothenic_acid_mg": 5,
"phosphorus_mg": 1000,
"potassium_mg": 3500,
"riboflavin_mg": 1.3,
"selenium_mg": 0.055,
"thiamin_mg": 1.2,
"vitamin_A_mg": 0.9,
"vitamin_B12_mg": 0.0024,
"vitamin_B6_mg": 1.7,
"vitamin_C_mg": 90,
"vitamin_D_mg": 0.02,
"vitamin_D2_mg": 0.01,
"vitamin_D3_mg": 0.015,
"vitamin_E_mg": 15,
"vitamin_K_mg": 0.12,
"zinc_mg": 11,
"cystine_g": 0.3,
"histidine_g": 0.6,
"isoleucine_g": 0.8,
"leucine_g": 1.2,
"lysine_g": 0.9,
"methionine_g": 0.6,
"phenylalanine_g": 0.9,
"threonine_g": 0.5,
"tryptophan_g": 0.3,
"tyrosine_g": 0.7,
"valine_g": 0.8,
"monounsaturated_fat_g": 15,
"polyunsaturated_fat_g": 13,
"omega3_g": 1.6,
"omega6_g": 17,
"starch_g": 25
},
"water_ml": 2000,
"drink_ml": 500
}
}
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"log_ids": [
"text"
],
"message": "Nutrition successfully logged"
}
Used to post body data to a provider. This endpoint only works for users connected via Google Fit. Returns error for other providers.
POST /v2/body HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 3729
{
"data": [
{
"blood_pressure_data": {
"blood_pressure_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"diastolic_bp": 80.5,
"systolic_bp": 120.5
}
]
},
"device_data": {
"activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
"data_provided": [
"text"
],
"hardware_version": "v2.1",
"last_upload_date": "text",
"manufacturer": "Garmin",
"name": "Forerunner 945",
"other_devices": [
{
"manufacturer": "Garmin",
"hardware_version": "v2.1",
"serial_number": "GR123456789",
"name": "Forerunner 945",
"software_version": "5.2.1",
"activation_timestamp": "text",
"data_provided": [
"text"
],
"last_upload_date": "text"
}
],
"sensor_state": "text",
"serial_number": "GR123456789",
"software_version": "5.2.1"
},
"heart_data": {
"afib_classification_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"afib_classification": 1
}
],
"ecg_signal": [
{
"start_timestamp": "text",
"avg_hr_bpm": 72.5,
"afib_classification": 1,
"raw_signal": [
{
"potential_uV": 1250.5,
"timestamp": "2022-11-23T09:00:00.000000+02:00"
}
]
}
],
"heart_rate_data": {
"detailed": {
"hr_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"bpm": 142,
"timer_duration_seconds": 600,
"context": 1
}
],
"hrv_samples_rmssd": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_rmssd": 42.1
}
],
"hrv_samples_sdnn": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hrv_sdnn": 48.3
}
]
},
"summary": {
"avg_hr_bpm": 145,
"avg_hrv_rmssd": 35.2,
"avg_hrv_sdnn": 45.5,
"hr_zone_data": [
{
"zone": 2,
"start_percentage": 60,
"end_percentage": 70,
"name": "Aerobic",
"duration_seconds": 300
}
],
"max_hr_bpm": 180,
"min_hr_bpm": 85,
"resting_hr_bpm": 65,
"user_max_hr_bpm": 190
}
},
"pulse_wave_velocity_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"pulse_wave_velocity_meters_per_second": 7.2
}
],
"rr_interval_samples": [
{
"rr_interval_ms": 850,
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hr_bpm": 72
}
]
},
"hydration_data": {
"day_total_water_consumption_ml": 2500,
"hydration_amount_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"hydration_kg": 40
}
]
},
"ketone_data": {
"ketone_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"ketone_mg_per_dL": 1.5,
"sample_type": 1
}
]
},
"measurements_data": {
"measurements": [
{
"measurement_time": "2022-11-23T09:00:00.000000+02:00",
"BMI": 22.4,
"BMR": 1800,
"RMR": 2000,
"estimated_fitness_age": "25",
"skin_fold_mm": 12.5,
"bodyfat_percentage": 18.5,
"weight_kg": 75.5,
"height_cm": 178,
"bone_mass_g": 3200,
"muscle_mass_g": 35000,
"lean_mass_g": 61500,
"water_percentage": 60.5,
"insulin_units": 10.5,
"insulin_type": "rapid-acting",
"urine_color": "pale yellow",
"user_notes": "text"
}
]
},
"metadata": {
"end_time": "2022-10-28T10:00:00.000000+01:00",
"start_time": "1999-11-23T09:00:00.000000+02:00",
"timestamp_localization": 0
},
"oxygen_data": {
"avg_saturation_percentage": 98,
"saturation_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"percentage": 98,
"type": 0
}
],
"vo2_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"vo2max_ml_per_min_per_kg": 45.5
}
],
"vo2max_ml_per_min_per_kg": 45.5
},
"temperature_data": {
"ambient_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
],
"body_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
],
"skin_temperature_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"temperature_celsius": 37.2
}
]
},
"glucose_data": {
"blood_glucose_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"blood_glucose_mg_per_dL": 95,
"glucose_level_flag": 1,
"trend_arrow": 4
}
],
"detailed_blood_glucose_samples": [
{
"timestamp": "2022-11-23T09:00:00.000000+02:00",
"blood_glucose_mg_per_dL": 95,
"glucose_level_flag": 1,
"trend_arrow": 4
}
],
"day_avg_blood_glucose_mg_per_dL": 92.5,
"gmi": 1,
"time_in_range": 1,
"sensor_usage": 1,
"daily_patterns": [
{
"time_from_midnight": 9,
"percentile_5": 1,
"percentile_25": 1,
"percentile_50": 1,
"percentile_75": 1,
"percentile_95": 1
}
]
}
}
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"log_ids": [
"text"
],
"message": "Body data successfully logged"
}
Used to post workout plans users can follow on their wearable. This can be strength workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)
POST /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 709
{
"data": [
{
"steps": [
{
"targets": [
{
"target_type": "HEART_RATE"
}
],
"type": "STEP",
"intensity": "REST",
"order": 1,
"description": "text",
"durations": [
{
"duration_type": "TIME"
}
],
"name": "text"
}
],
"metadata": {
"estimated_energy_kj": null,
"estimated_speed_meters_per_second": null,
"estimated_elevation_gain_meters": null,
"estimated_tss": null,
"estimated_calories": null,
"created_date": "2022-11-23T09:00:00.000000+02:00",
"planned_date": "2022-11-24T09:00:00.000000+02:00",
"type": "IN_VEHICLE",
"id": null,
"estimated_duration_seconds": null,
"estimated_pace_minutes_per_kilometer": null,
"provider": "text",
"estimated_tscore": null,
"description": null,
"name": null,
"estimated_distance_meters": null,
"estimated_if": null,
"pool_length_meters": null
}
}
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"log_ids": [
"text"
],
"message": "Planned workout successfully created"
}
Used to delete nutrition logs the user has registered on their account
Terra user ID (UUID format) to retrieve data for
List of identifiers for nutrition entries to be deleted
DELETE /v2/nutrition HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"data": [
"text"
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"processed_data": [
{
"id": "text",
"response_code": 1
}
]
}
Used to delete Body metrics the user has registered on their account
Terra user ID (UUID format) to retrieve data for
List of identifiers for body metrics entries to be deleted
DELETE /v2/body HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20
{
"log_ids": [
"text"
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"processed_data": [
{
"id": "text",
"response_code": 1
}
]
}
Used to delete workout plans the user has registered on their account. This can be strength workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)
Terra user ID (UUID format) to retrieve data for
List of identifiers for planned workout entries to be deleted
DELETE /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"data": [
"text"
]
}
{
"user": {
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"provider": "FITBIT",
"last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
"scopes": "activity:read,sleep:read",
"reference_id": "[email protected]",
"active": true
},
"processed_data": [
{
"id": "text",
"response_code": 1
}
]
}
Last updated
Was this helpful?