Terra Docs
Dashboard
  • Docs
  • API Reference
  • Changelog
  • Health & Fitness API
    • REST API Endpoints
    • Supported integrations
    • Event Types
    • Data models
    • Samples
    • Core concepts
    • Destinations
    • Mobile SDK
      • iOS (Swift)
      • Android (Kotlin)
      • React Native
      • Flutter
  • Streaming API
    • REST API Endpoints
    • Supported Integrations
    • Core Concepts
    • Websocket Reference
    • Mobile SDK
      • iOS (Swift)
      • Android (Kotlin)
      • Flutter
      • React Native
  • Teams API - Beta
    • Supported Integrations
    • Core Concepts
    • API Endpoints
    • Event types
Powered by GitBook
On this page

Was this helpful?

  1. Health & Fitness API

REST API Endpoints

NextSupported integrations

Last updated 29 days ago

Was this helpful?

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

Get list of available integrations

get
Responses
200
Returns list of all available integrations on the API
application/json
get
GET /v2/integrations HTTP/1.1
Host: api.tryterra.co
Accept: */*
200

Returns list of all available integrations on the API

{
  "providers": [
    "FITBIT"
  ],
  "sdk_resource": [
    "APPLE"
  ],
  "status": "success"
}

Get detailed list of integrations

get

Retrieve a detailed list of supported integrations, optionally filtered by the developer's enabled integrations and the requirement for SDK usage.

Query parameters
sdkbooleanOptional

If true, allows SDK integrations to be included in the response.

Header parameters
dev-idstringOptional

Developer ID to filter the integrations list based on the developer's enabled integrations.

Responses
200
Successful response containing a list of integrations.
application/json
get
GET /v2/integrations/detailed HTTP/1.1
Host: api.tryterra.co
Accept: */*
200

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
      }
    }
  ]
}

Deauthenticates a user and deletes any cached data for them

delete

Deletes all records of the user on Terra's end, revoking Terra's access to their data

Query parameters
user_idstringRequired

user_id to deauthenticate for

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned when authentication link could be successfully generated
application/json
404
Returned when the user_id is not existent
application/json
delete
DELETE /v2/auth/deauthenticateUser HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "status": "success"
}
get

Used to query for information on one Terra user ID, or to query for all registered Terra User objects under one reference ID

Query parameters
user_idstringOptional

user ID to query for

reference_idstringOptional

reference ID to query for

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned when the provided resources are found
application/json
Responseone of
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/userInfo HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "status": "success",
  "is_authenticated": true
}
get

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).

Query parameters
pageintegerOptional

Zero-based page number. If omitted, results are not paginated.

Example: 0
per_pageintegerOptional

Number of results per page (default is 500).

Example: 500
Header parameters
dev-idstringRequired

Your developer ID

Example: testingTerra
x-api-keystringRequired

Your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon a successful request
application/json
Responseone of
or
400
Returned when one or more parameters are malformed
application/json
get
GET /v2/subscriptions HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "users": [
    {
      "reference_id": "[email protected]",
      "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
      "scopes": "activity:read,sleep:read",
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "FITBIT",
      "active": true
    }
  ]
}

Retrieve user profile info for a given user ID

get

Fetches relevant profile info such as first & last name, birth date etc. for a given user ID

Query parameters
user_idstringRequired

user ID to query data for

to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/athlete HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "athlete": {
    "gender": "male",
    "state": "California",
    "bio": "Passionate runner and cyclist",
    "age": "28",
    "country": "United States",
    "sex": "male",
    "date_of_birth": "1999-11-23",
    "city": "San Francisco",
    "account_creation_date": "2023-01-15",
    "email": "[email protected]",
    "last_name": "Smith",
    "first_name": "John"
  },
  "type": "athlete",
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  }
}

Retrieve activity data for a given user ID

get

Fetches completed workout sessions, with a defined start and end time and activity type (e.g. running, cycling, etc.)

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/activity HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "activity_level": "MEDIUM_INTENSITY",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 600,
        "vigorous_intensity_seconds": 300,
        "activity_seconds": 1800,
        "low_intensity_seconds": 900,
        "rest_seconds": 120,
        "moderate_intensity_seconds": 600
      },
      "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"
          }
        ]
      },
      "cheat_detection": 0,
      "polyline_map_data": {
        "summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
      },
      "strain_data": {
        "strain_level": 8.5
      },
      "position_data": {
        "position_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "coords_lat_lng_deg": [
              -18.4911,
              130.9123
            ]
          }
        ],
        "end_pos_lat_lng_deg": [
          -84.4911,
          -150.9123
        ],
        "center_pos_lat_lng_deg": [
          -18.4911,
          130.9123
        ],
        "start_pos_lat_lng_deg": [
          80.2394,
          102.931
        ]
      },
      "movement_data": {
        "max_pace_minutes_per_kilometer": 6.5,
        "adjusted_max_speed_meters_per_second": 4.2,
        "avg_velocity_meters_per_second": 3,
        "max_velocity_meters_per_second": 4.5,
        "avg_speed_meters_per_second": 3.2,
        "avg_torque_newton_meters": 40,
        "cadence_samples": [
          {
            "timer_duration_seconds": 300,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "cadence_rpm": 85
          }
        ],
        "max_speed_meters_per_second": 4.5,
        "avg_pace_minutes_per_kilometer": 6.2,
        "avg_cadence_rpm": 85,
        "max_torque_newton_meters": 55.5,
        "torque_samples": [
          {
            "torque_newton_meters": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300
          }
        ],
        "normalized_speed_meters_per_second": 3.8,
        "max_cadence_rpm": 110,
        "speed_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "speed_meters_per_second": 3.5
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "energy_data": {
        "energy_planned_kilojoules": 1200,
        "energy_kilojoules": 1150
      },
      "MET_data": {
        "num_inactive_minutes": 5,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ],
        "num_low_intensity_minutes": 15,
        "num_moderate_intensity_minutes": 25,
        "avg_level": 3.8,
        "num_high_intensity_minutes": 10
      },
      "power_data": {
        "avg_watts": 185,
        "max_watts": 350,
        "power_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800,
            "watts": 250
          }
        ]
      },
      "distance_data": {
        "summary": {
          "distance_meters": 5000,
          "elevation": {
            "gain_planned_meters": 500,
            "loss_actual_meters": 450,
            "max_meters": 1200,
            "min_meters": 800,
            "gain_actual_meters": 550,
            "avg_meters": 950
          },
          "steps": 6500,
          "floors_climbed": 10,
          "swimming": {
            "num_laps": 20,
            "num_strokes": 500,
            "pool_length_meters": 25
          }
        },
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        }
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 65,
          "avg_hr_bpm": 145,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": "ZONE_2",
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic"
            }
          ],
          "min_hr_bpm": 85,
          "avg_hrv_rmssd": 35.2,
          "user_max_hr_bpm": 190
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "TSS_data": {
        "TSS_samples": [
          {
            "intensity_factor_planned": 0.85,
            "intensity_factor_actual": 0.82,
            "normalized_power_watts": 225,
            "planned": 85,
            "actual": 82,
            "method": "HeartRate"
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 450,
        "total_burned_calories": 2250,
        "net_intake_calories": 200,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "state": "California",
        "timestamp_localization": 0,
        "country": "United States",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "summary_id": "123e4567-e89b-12d3-a456-426614174000",
        "city": "San Francisco",
        "type": "RUNNING",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "name": "Morning Run",
        "upload_type": "UNKNOWN"
      },
      "work_data": {
        "work_kilojoules": 450.5
      }
    }
  ],
  "type": "text"
}

Retrieve body metrics for a given user ID

get

Fetches body metrics such as weight, height, body fat percentage etc. for a given user ID

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/body HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "measurements_data": {
        "measurements": [
          {
            "weight_kg": 75.5,
            "bodyfat_percentage": 18.5,
            "BMI": 22.4,
            "water_percentage": 60.5,
            "measurement_time": "2022-11-23T09:00:00.000000+02:00",
            "lean_mass_g": 61500,
            "estimated_fitness_age": "25",
            "skin_fold_mm": 12.5,
            "height_cm": 178,
            "bone_mass_g": 3200,
            "insulin_units": 10.5,
            "muscle_mass_g": 35000,
            "BMR": 1800,
            "urine_color": "pale yellow",
            "RMR": 2000,
            "insulin_type": "rapid-acting"
          }
        ]
      },
      "ketone_data": {
        "ketone_samples": [
          {
            "ketone_mg_per_dL": 1.5,
            "sample_type": "UNKNOWN",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "hydration_data": {
        "hydration_amount_samples": 65.5,
        "day_total_water_consumption_ml": 2500
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "heart_data": {
        "heart_rate_data": {
          "summary": {
            "resting_hr_bpm": 60,
            "avg_hr_bpm": 75,
            "max_hr_bpm": 180,
            "avg_hrv_sdnn": 45.5,
            "hr_zone_data": [
              {
                "zone": "ZONE_2",
                "start_percentage": 60,
                "end_percentage": 70,
                "duration_seconds": 300,
                "name": "Aerobic"
              }
            ],
            "min_hr_bpm": 45,
            "avg_hrv_rmssd": 42.8,
            "user_max_hr_bpm": 190
          },
          "detailed": {
            "hrv_samples_rmssd": [
              {
                "hrv_rmssd": 42.1,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ],
            "hr_samples": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "bpm": 142
              }
            ],
            "hrv_samples_sdnn": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_sdnn": 48.3
              }
            ]
          }
        },
        "pulse_wave_velocity_samples": [
          {
            "pulse_wave_velocity_meters_per_second": 7.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "afib_classification_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "afib_classification": "NORMAL"
          }
        ],
        "ecg_signal": [
          {
            "start_timestamp": "2022-11-23T09:00:00.000000+02:00",
            "avg_hr_bpm": 72.5,
            "afib_classfication": 1,
            "raw_signal": [
              {
                "potential_uV": 1250.5,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ]
          }
        ],
        "rr_interval_samples": [
          {
            "rr_interval_ms": 850,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hr_bpm": 72
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "glucose_data": {
        "detailed_blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "day_avg_blood_glucose_mg_per_dL": 92.5
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "blood_pressure_data": {
        "blood_pressure_samples": [
          {
            "diastolic_bp": 80.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "systolic_bp": 120.5
          }
        ]
      },
      "temperature_data": {
        "body_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "skin_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "ambient_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      }
    }
  ],
  "type": "text"
}

Retrieve daily activity summaries for a given user ID

get

Fetches daily summaries of activity metrics such as steps, distance, calories burned etc. for a given user ID

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/daily HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "activity_level": "MEDIUM_INTENSITY",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 28800,
        "vigorous_intensity_seconds": 1800,
        "activity_seconds": 14400,
        "low_intensity_seconds": 7200,
        "rest_seconds": 28800,
        "moderate_intensity_seconds": 5400
      },
      "scores": {
        "sleep": 85,
        "recovery": 78,
        "activity": 92
      },
      "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": [
          {
            "steps": 3250,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 900
          }
        ],
        "rest_stress_duration_seconds": 1800,
        "high_stress_duration_seconds": 900,
        "stress_duration_seconds": 5400
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "tag_data": {
        "tags": [
          {
            "notes": "Felt refreshed after",
            "tag_name": "hot_shower",
            "timestamp": "1999-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 60,
          "avg_hr_bpm": 75,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": "ZONE_2",
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic"
            }
          ],
          "min_hr_bpm": 45,
          "avg_hrv_rmssd": 42.8,
          "user_max_hr_bpm": 190
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "MET_data": {
        "num_inactive_minutes": 480,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ],
        "num_low_intensity_minutes": 720,
        "num_moderate_intensity_minutes": 180,
        "avg_level": 1.8,
        "num_high_intensity_minutes": 60
      },
      "distance_data": {
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        },
        "distance_meters": 8500,
        "elevation": {
          "gain_planned_meters": 150,
          "loss_actual_meters": 120,
          "max_meters": 450,
          "min_meters": 300,
          "gain_actual_meters": 130,
          "avg_meters": 375
        },
        "steps": 12000,
        "floors_climbed": 15,
        "swimming": {
          "num_laps": 20,
          "num_strokes": 500,
          "pool_length_meters": 25
        }
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 45.5,
        "avg_saturation_percentage": 98,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 500,
        "total_burned_calories": 2300,
        "net_intake_calories": 2000,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "upload_type": "UNKNOWN",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      }
    }
  ],
  "type": "text"
}

Retrieve menstruation data for a given user ID

get

Fetches menstruation data such as cycle length, period length, ovulation date etc. for a given user ID

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/menstruation HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "menstruation_data": {
        "length_of_current_phase_days": 5,
        "period_length_days": 5,
        "cycle_length_days": "28",
        "days_until_next_phase": 23,
        "is_predicted_cycle": "true",
        "last_updated_time": "2022-12-12T14:03:05.000000-05:00",
        "current_phase": 1,
        "period_start_date": "2022-11-28",
        "predicted_cycle_length_days": 28,
        "menstruation_flow": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "flow": "UNKNOWN"
          }
        ],
        "day_in_cycle": 24
      }
    }
  ],
  "type": "text"
}

Retrieve nutrition log data for a given user ID

get

Fetches nutrition log data such as meal type, calories, macronutrients etc. for a given user ID

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/nutrition HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "summary": {
        "micros": {
          "iron_mg": 8.5,
          "magnesium_mg": 320,
          "vitamin_A_mg": 0.9,
          "vitamin_B12_mg": 0.0024,
          "biotin_mg": 0.03,
          "cystine_g": 0.3,
          "phenylalanine_g": 0.9,
          "chloride_mg": 2300,
          "vitamin_D3_mg": 0.015,
          "isoleucine_g": 0.8,
          "calcium_mg": 1000,
          "iodine_mg": 0.15,
          "histidine_g": 0.6,
          "chromium_mg": 0.035,
          "vitamin_K_mg": 0.12,
          "manganese_mg": 2.3,
          "folic_acid_mg": 0.4,
          "leucine_g": 1.2,
          "caffeine_mg": 95,
          "potassium_mg": 3500,
          "molybdenum_mg": 0.045,
          "lysine_g": 0.9,
          "tyrosine_g": 0.7,
          "valine_g": 0.8,
          "omega6_g": 17,
          "omega3_g": 1.6,
          "vitamin_C_mg": 90,
          "zinc_mg": 11,
          "vitamin_D2_mg": 0.01,
          "vitamin_E_mg": 15,
          "pantothenic_acid_mg": 5,
          "riboflavin_mg": 1.3,
          "phosphorus_mg": 1000,
          "vitamin_D_mg": 0.02,
          "tryptophan_g": 0.3,
          "niacin_mg": 16,
          "copper_mg": 0.9,
          "threonine_g": 0.5,
          "monounsaturated_fat_g": 15,
          "folate_mg": 0.4,
          "selenium_mg": 0.055,
          "vitamin_B6_mg": 1.7,
          "thiamin_mg": 1.2,
          "polyunsaturated_fat_g": 13,
          "methionine_g": 0.6,
          "starch_g": 25
        },
        "macros": {
          "fiber_g": 25,
          "calories": 2000,
          "fat_g": 65,
          "sodium_mg": 2300,
          "alcohol_g": 14,
          "trans_fat_g": 2,
          "carbohydrates_g": 300,
          "protein_g": 50,
          "saturated_fat_g": 20,
          "sugar_g": 25,
          "cholesterol_mg": 300,
          "net_carbohydrates_g": 275
        },
        "water_ml": 2000
      },
      "drink_samples": [
        {
          "drink_unit": "ml",
          "timestamp": "2022-11-23T09:00:00.000000+02:00",
          "drink_name": "Water",
          "drink_volume": "250"
        }
      ],
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "meals": [
        {
          "micros": {
            "iron_mg": 8.5,
            "magnesium_mg": 320,
            "vitamin_A_mg": 0.9,
            "vitamin_B12_mg": 0.0024,
            "biotin_mg": 0.03,
            "cystine_g": 0.3,
            "phenylalanine_g": 0.9,
            "chloride_mg": 2300,
            "vitamin_D3_mg": 0.015,
            "isoleucine_g": 0.8,
            "calcium_mg": 1000,
            "iodine_mg": 0.15,
            "histidine_g": 0.6,
            "chromium_mg": 0.035,
            "vitamin_K_mg": 0.12,
            "manganese_mg": 2.3,
            "folic_acid_mg": 0.4,
            "leucine_g": 1.2,
            "caffeine_mg": 95,
            "potassium_mg": 3500,
            "molybdenum_mg": 0.045,
            "lysine_g": 0.9,
            "tyrosine_g": 0.7,
            "valine_g": 0.8,
            "omega6_g": 17,
            "omega3_g": 1.6,
            "vitamin_C_mg": 90,
            "zinc_mg": 11,
            "vitamin_D2_mg": 0.01,
            "vitamin_E_mg": 15,
            "pantothenic_acid_mg": 5,
            "riboflavin_mg": 1.3,
            "phosphorus_mg": 1000,
            "vitamin_D_mg": 0.02,
            "tryptophan_g": 0.3,
            "niacin_mg": 16,
            "copper_mg": 0.9,
            "threonine_g": 0.5,
            "monounsaturated_fat_g": 15,
            "folate_mg": 0.4,
            "selenium_mg": 0.055,
            "vitamin_B6_mg": 1.7,
            "thiamin_mg": 1.2,
            "polyunsaturated_fat_g": 13,
            "methionine_g": 0.6,
            "starch_g": 25
          },
          "type": "BREAKFAST",
          "id": "food_123",
          "timestamp": "2022-12-12T08:53:00.000000+02:00",
          "quantity": {
            "unit": "grams",
            "amount": 100
          },
          "name": "Oatmeal",
          "macros": {
            "fiber_g": 25,
            "calories": 2000,
            "fat_g": 65,
            "sodium_mg": 2300,
            "alcohol_g": 14,
            "trans_fat_g": 2,
            "carbohydrates_g": 300,
            "protein_g": 50,
            "saturated_fat_g": 20,
            "sugar_g": 25,
            "cholesterol_mg": 300,
            "net_carbohydrates_g": 275
          }
        }
      ]
    }
  ],
  "type": "text"
}

Retrieve sleep sessions for a given user ID

get

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

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

with_samplesbooleanOptional

boolean flag specifying whether to include detailed samples in the returned payload

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
or
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/sleep HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "respiration_data": {
        "snoring_data": {
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "total_snoring_duration_seconds": 3600,
          "samples": [
            {
              "duration_seconds": 120,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "num_snoring_events": 12
        },
        "breaths_data": {
          "avg_breaths_per_min": 14,
          "max_breaths_per_min": 18,
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "min_breaths_per_min": 10,
          "samples": [
            {
              "breaths_per_min": 16,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "on_demand_reading": false,
          "end_time": "2022-11-24T08:00:00.000000+01:00"
        },
        "oxygen_saturation_data": {
          "samples": [
            {
              "percentage": 98,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "type": 0
            }
          ],
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "avg_saturation_percentage": 97,
          "end_time": "2022-11-24T08:00:00.000000+01:00"
        }
      },
      "sleep_durations_data": {
        "sleep_efficiency": 87.5,
        "awake": {
          "duration_short_interruption_seconds": 180,
          "duration_awake_state_seconds": 1200,
          "wake_up_latency_seconds": 300,
          "num_wakeup_events": 3,
          "duration_long_interruption_seconds": 600,
          "sleep_latency_seconds": 900,
          "num_out_of_bed_events": 1
        },
        "asleep": {
          "num_REM_events": 4,
          "duration_asleep_state_seconds": 25200,
          "duration_REM_sleep_state_seconds": 5400,
          "duration_light_sleep_state_seconds": 14400,
          "duration_deep_sleep_state_seconds": 5400
        },
        "hypnogram_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": "UNKNOWN"
          }
        ],
        "other": {
          "duration_unmeasurable_sleep_seconds": 300,
          "duration_in_bed_seconds": 28800
        }
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 55,
          "avg_hr_bpm": 60,
          "max_hr_bpm": 75,
          "avg_hrv_sdnn": 45,
          "min_hr_bpm": 48,
          "avg_hrv_rmssd": 35,
          "user_max_hr_bpm": 185
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "metadata": {
        "is_nap": false,
        "start_time": "1999-11-23T22:00:00.000000+02:00",
        "upload_type": 1,
        "end_time": "2022-11-24T08:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "readiness_data": {
        "readiness": 85,
        "recovery_level": 4
      },
      "temperature_data": {
        "delta": 0.5
      }
    }
  ],
  "type": "text"
}

Retrieve workout plans for a given user ID

get

Used to get workout plans the user has registered on their account. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

Query parameters
user_idstringRequired

user ID to query data for

start_dateone ofRequired

start date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
end_dateone ofOptional

end date of data to query for - either ISO8601 date or unix timestamp

integerOptional
or
string · dateOptional
to_webhookbooleanOptional

boolean flag specifying whether to send the data retrieved to the webhook, or in the response

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Responses
200
Returned upon successful data request
application/json
Responseone of
or
or
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
get
GET /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "data": [
    {
      "steps": {},
      "metadata": {
        "estimated_energy_kj": 1,
        "estimated_speed_meters_per_second": 1,
        "estimated_elevation_gain_meters": 1,
        "estimated_tss": 1,
        "estimated_calories": 1,
        "created_date": "2022-11-23T09:00:00.000000+02:00",
        "planned_date": "2022-11-24T09:00:00.000000+02:00",
        "type": "IN_VEHICLE",
        "id": "text",
        "estimated_duration_seconds": 1,
        "estimated_pace_minutes_per_kilometer": 1,
        "provider": "text",
        "estimated_tscore": 1,
        "description": "text",
        "name": "text",
        "estimated_distance_meters": 1,
        "estimated_if": 1,
        "pool_length_meters": 1
      }
    }
  ],
  "type": "text"
}
  • 🕸️ API info
  • GETGet list of available integrations
  • GETGet detailed list of integrations
  • 🔌 Authentication
  • POSTGenerate an authentication link
  • POSTGenerate an authentication link, using the Terra Authentication Widget
  • DELETEDeauthenticates a user and deletes any cached data for them
  • 💁‍♂️ User info
  • GET/userInfo
  • GET/subscriptions
  • POST/bulkUserInfo
  • GETRetrieve user profile info for a given user ID
  • ⏳ Historical Data retrieval
  • GETRetrieve activity data for a given user ID
  • GETRetrieve body metrics for a given user ID
  • GETRetrieve daily activity summaries for a given user ID
  • GETRetrieve menstruation data for a given user ID
  • GETRetrieve nutrition log data for a given user ID
  • GETRetrieve sleep sessions for a given user ID
  • GETRetrieve workout plans for a given user ID
  • ✏️ Writing data
  • POST/activity
  • POST/nutrition
  • POST/body
  • POST/plannedWorkout
  • DELETE/nutrition
  • DELETE/body
  • DELETE/plannedWorkout

Generate an authentication link

post

Creates a login link that allows end users to connect their fitness tracking account

Query parameters
resourcestringRequired

resource to authenticate user with

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
languagestringOptional
reference_idstringOptional
auth_success_redirect_urlstringOptional
auth_failure_redirect_urlstringOptional
Responses
200
Returned when authentication link could be successfully generated
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. resource)
application/json
post
POST /v2/auth/authenticateUser HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: 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"
}

Generate an authentication link, using the Terra Authentication Widget

post

Generates a link to redirect an end user to for them to select an integration and log in with their fitness data provider

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
providersstringOptional

Comma separated list of providers to display on the device selection page. This overrides your selected sources on your dashboard

Example: GARMIN,FITBIT,OURA,WITHINGS,SUUNTO
languagestringOptional

Display language of the widget

Example: en
reference_idstringOptional

Identifier of the end user on your system, such as a user ID or email associated with them

Example: [email protected]
auth_success_redirect_urlstringOptional

URL the user is redirected to upon successful authentication

Example: https://myapp.com/success
auth_failure_redirect_urlstringOptional

URL the user is redirected to upon unsuccessful authentication

Example: https://myapp.com/failure
Responses
200
Returned when authentication link could be successfully generated
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
post
POST /v2/auth/generateWidgetSession HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
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
}
post

Used to query for information for multiple Terra User IDs

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
string[]Optional

List of user IDs to get information for

Responses
200
Returned upon successful request
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
post
POST /v2/bulkUserInfo HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 8

[
  "text"
]
[
  {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  }
]
post

Used to post activity data to a provider. Available for Wahoo

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
Responses
201
Returned when activity was successfully created on the provider
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
post
POST /v2/activity HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 4976

{
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "activity_level": "MEDIUM_INTENSITY",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "num_continuous_inactive_periods": 3,
        "inactivity_seconds": 600,
        "vigorous_intensity_seconds": 300,
        "activity_seconds": 1800,
        "low_intensity_seconds": 900,
        "rest_seconds": 120,
        "moderate_intensity_seconds": 600
      },
      "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"
          }
        ]
      },
      "cheat_detection": 0,
      "polyline_map_data": {
        "summary_polyline": "}_p~iF~ps|U_ulLnnqC_mqNvxq`@"
      },
      "strain_data": {
        "strain_level": 8.5
      },
      "position_data": {
        "position_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "coords_lat_lng_deg": [
              -18.4911,
              130.9123
            ]
          }
        ],
        "end_pos_lat_lng_deg": [
          -84.4911,
          -150.9123
        ],
        "center_pos_lat_lng_deg": [
          -18.4911,
          130.9123
        ],
        "start_pos_lat_lng_deg": [
          80.2394,
          102.931
        ]
      },
      "movement_data": {
        "max_pace_minutes_per_kilometer": 6.5,
        "adjusted_max_speed_meters_per_second": 4.2,
        "avg_velocity_meters_per_second": 3,
        "max_velocity_meters_per_second": 4.5,
        "avg_speed_meters_per_second": 3.2,
        "avg_torque_newton_meters": 40,
        "cadence_samples": [
          {
            "timer_duration_seconds": 300,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "cadence_rpm": 85
          }
        ],
        "max_speed_meters_per_second": 4.5,
        "avg_pace_minutes_per_kilometer": 6.2,
        "avg_cadence_rpm": 85,
        "max_torque_newton_meters": 55.5,
        "torque_samples": [
          {
            "torque_newton_meters": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300
          }
        ],
        "normalized_speed_meters_per_second": 3.8,
        "max_cadence_rpm": 110,
        "speed_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 300,
            "speed_meters_per_second": 3.5
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "energy_data": {
        "energy_planned_kilojoules": 1200,
        "energy_kilojoules": 1150
      },
      "MET_data": {
        "num_inactive_minutes": 5,
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4.2
          }
        ],
        "num_low_intensity_minutes": 15,
        "num_moderate_intensity_minutes": 25,
        "avg_level": 3.8,
        "num_high_intensity_minutes": 10
      },
      "power_data": {
        "avg_watts": 185,
        "max_watts": 350,
        "power_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800,
            "watts": 250
          }
        ]
      },
      "distance_data": {
        "summary": {
          "distance_meters": 5000,
          "elevation": {
            "gain_planned_meters": 500,
            "loss_actual_meters": 450,
            "max_meters": 1200,
            "min_meters": 800,
            "gain_actual_meters": 550,
            "avg_meters": 950
          },
          "steps": 6500,
          "floors_climbed": 10,
          "swimming": {
            "num_laps": 20,
            "num_strokes": 500,
            "pool_length_meters": 25
          }
        },
        "detailed": {
          "elevation_samples": [
            {
              "elev_meters": 925,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 1200
            }
          ],
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "floors_climbed_samples": [
            {
              "floors_climbed": 5,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "steps": 3250,
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "timer_duration_seconds": 900
            }
          ]
        }
      },
      "heart_rate_data": {
        "summary": {
          "resting_hr_bpm": 65,
          "avg_hr_bpm": 145,
          "max_hr_bpm": 180,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": "ZONE_2",
              "start_percentage": 60,
              "end_percentage": 70,
              "duration_seconds": 300,
              "name": "Aerobic"
            }
          ],
          "min_hr_bpm": 85,
          "avg_hrv_rmssd": 35.2,
          "user_max_hr_bpm": 190
        },
        "detailed": {
          "hrv_samples_rmssd": [
            {
              "hrv_rmssd": 42.1,
              "timestamp": "2022-11-23T09:00:00.000000+02:00"
            }
          ],
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        }
      },
      "TSS_data": {
        "TSS_samples": [
          {
            "intensity_factor_planned": 0.85,
            "intensity_factor_actual": 0.82,
            "normalized_power_watts": 225,
            "planned": 85,
            "actual": 82,
            "method": "HeartRate"
          }
        ]
      },
      "calories_data": {
        "BMR_calories": 1800,
        "net_activity_calories": 450,
        "total_burned_calories": 2250,
        "net_intake_calories": 200,
        "calorie_samples": [
          {
            "calories": 450,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "timer_duration_seconds": 1800
          }
        ]
      },
      "metadata": {
        "state": "California",
        "timestamp_localization": 0,
        "country": "United States",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "summary_id": "123e4567-e89b-12d3-a456-426614174000",
        "city": "San Francisco",
        "type": "RUNNING",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "name": "Morning Run",
        "upload_type": "UNKNOWN"
      },
      "work_data": {
        "work_kilojoules": 450.5
      }
    }
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "log_ids": [
    "text"
  ],
  "message": "text"
}
post

Used to post nutrition logs to a provider. Available for Fitbit

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
Responses
201
Returned when activity was successfully created on the provider
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
post
POST /v2/nutrition HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 2623

{
  "data": [
    {
      "summary": {
        "micros": {
          "iron_mg": 8.5,
          "magnesium_mg": 320,
          "vitamin_A_mg": 0.9,
          "vitamin_B12_mg": 0.0024,
          "biotin_mg": 0.03,
          "cystine_g": 0.3,
          "phenylalanine_g": 0.9,
          "chloride_mg": 2300,
          "vitamin_D3_mg": 0.015,
          "isoleucine_g": 0.8,
          "calcium_mg": 1000,
          "iodine_mg": 0.15,
          "histidine_g": 0.6,
          "chromium_mg": 0.035,
          "vitamin_K_mg": 0.12,
          "manganese_mg": 2.3,
          "folic_acid_mg": 0.4,
          "leucine_g": 1.2,
          "caffeine_mg": 95,
          "potassium_mg": 3500,
          "molybdenum_mg": 0.045,
          "lysine_g": 0.9,
          "tyrosine_g": 0.7,
          "valine_g": 0.8,
          "omega6_g": 17,
          "omega3_g": 1.6,
          "vitamin_C_mg": 90,
          "zinc_mg": 11,
          "vitamin_D2_mg": 0.01,
          "vitamin_E_mg": 15,
          "pantothenic_acid_mg": 5,
          "riboflavin_mg": 1.3,
          "phosphorus_mg": 1000,
          "vitamin_D_mg": 0.02,
          "tryptophan_g": 0.3,
          "niacin_mg": 16,
          "copper_mg": 0.9,
          "threonine_g": 0.5,
          "monounsaturated_fat_g": 15,
          "folate_mg": 0.4,
          "selenium_mg": 0.055,
          "vitamin_B6_mg": 1.7,
          "thiamin_mg": 1.2,
          "polyunsaturated_fat_g": 13,
          "methionine_g": 0.6,
          "starch_g": 25
        },
        "macros": {
          "fiber_g": 25,
          "calories": 2000,
          "fat_g": 65,
          "sodium_mg": 2300,
          "alcohol_g": 14,
          "trans_fat_g": 2,
          "carbohydrates_g": 300,
          "protein_g": 50,
          "saturated_fat_g": 20,
          "sugar_g": 25,
          "cholesterol_mg": 300,
          "net_carbohydrates_g": 275
        },
        "water_ml": 2000
      },
      "drink_samples": [
        {
          "drink_unit": "ml",
          "timestamp": "2022-11-23T09:00:00.000000+02:00",
          "drink_name": "Water",
          "drink_volume": "250"
        }
      ],
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "meals": [
        {
          "micros": {
            "iron_mg": 8.5,
            "magnesium_mg": 320,
            "vitamin_A_mg": 0.9,
            "vitamin_B12_mg": 0.0024,
            "biotin_mg": 0.03,
            "cystine_g": 0.3,
            "phenylalanine_g": 0.9,
            "chloride_mg": 2300,
            "vitamin_D3_mg": 0.015,
            "isoleucine_g": 0.8,
            "calcium_mg": 1000,
            "iodine_mg": 0.15,
            "histidine_g": 0.6,
            "chromium_mg": 0.035,
            "vitamin_K_mg": 0.12,
            "manganese_mg": 2.3,
            "folic_acid_mg": 0.4,
            "leucine_g": 1.2,
            "caffeine_mg": 95,
            "potassium_mg": 3500,
            "molybdenum_mg": 0.045,
            "lysine_g": 0.9,
            "tyrosine_g": 0.7,
            "valine_g": 0.8,
            "omega6_g": 17,
            "omega3_g": 1.6,
            "vitamin_C_mg": 90,
            "zinc_mg": 11,
            "vitamin_D2_mg": 0.01,
            "vitamin_E_mg": 15,
            "pantothenic_acid_mg": 5,
            "riboflavin_mg": 1.3,
            "phosphorus_mg": 1000,
            "vitamin_D_mg": 0.02,
            "tryptophan_g": 0.3,
            "niacin_mg": 16,
            "copper_mg": 0.9,
            "threonine_g": 0.5,
            "monounsaturated_fat_g": 15,
            "folate_mg": 0.4,
            "selenium_mg": 0.055,
            "vitamin_B6_mg": 1.7,
            "thiamin_mg": 1.2,
            "polyunsaturated_fat_g": 13,
            "methionine_g": 0.6,
            "starch_g": 25
          },
          "type": "BREAKFAST",
          "id": "food_123",
          "timestamp": "2022-12-12T08:53:00.000000+02:00",
          "quantity": {
            "unit": "grams",
            "amount": 100
          },
          "name": "Oatmeal",
          "macros": {
            "fiber_g": 25,
            "calories": 2000,
            "fat_g": 65,
            "sodium_mg": 2300,
            "alcohol_g": 14,
            "trans_fat_g": 2,
            "carbohydrates_g": 300,
            "protein_g": 50,
            "saturated_fat_g": 20,
            "sugar_g": 25,
            "cholesterol_mg": 300,
            "net_carbohydrates_g": 275
          }
        }
      ]
    }
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "log_ids": [
    "text"
  ],
  "message": "text"
}
post

Used to post body data to a provider. Available for Google Fit

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
Responses
201
Returned when activity was successfully created on the provider
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
post
POST /v2/body HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 3346

{
  "data": [
    {
      "measurements_data": {
        "measurements": [
          {
            "weight_kg": 75.5,
            "bodyfat_percentage": 18.5,
            "BMI": 22.4,
            "water_percentage": 60.5,
            "measurement_time": "2022-11-23T09:00:00.000000+02:00",
            "lean_mass_g": 61500,
            "estimated_fitness_age": "25",
            "skin_fold_mm": 12.5,
            "height_cm": 178,
            "bone_mass_g": 3200,
            "insulin_units": 10.5,
            "muscle_mass_g": 35000,
            "BMR": 1800,
            "urine_color": "pale yellow",
            "RMR": 2000,
            "insulin_type": "rapid-acting"
          }
        ]
      },
      "ketone_data": {
        "ketone_samples": [
          {
            "ketone_mg_per_dL": 1.5,
            "sample_type": "UNKNOWN",
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      },
      "hydration_data": {
        "hydration_amount_samples": 65.5,
        "day_total_water_consumption_ml": 2500
      },
      "device_data": {
        "manufacturer": "Garmin",
        "hardware_version": "v2.1",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1"
          }
        ],
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "serial_number": "GR123456789",
        "name": "Forerunner 945",
        "software_version": "5.2.1"
      },
      "heart_data": {
        "heart_rate_data": {
          "summary": {
            "resting_hr_bpm": 60,
            "avg_hr_bpm": 75,
            "max_hr_bpm": 180,
            "avg_hrv_sdnn": 45.5,
            "hr_zone_data": [
              {
                "zone": "ZONE_2",
                "start_percentage": 60,
                "end_percentage": 70,
                "duration_seconds": 300,
                "name": "Aerobic"
              }
            ],
            "min_hr_bpm": 45,
            "avg_hrv_rmssd": 42.8,
            "user_max_hr_bpm": 190
          },
          "detailed": {
            "hrv_samples_rmssd": [
              {
                "hrv_rmssd": 42.1,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ],
            "hr_samples": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "bpm": 142
              }
            ],
            "hrv_samples_sdnn": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_sdnn": 48.3
              }
            ]
          }
        },
        "pulse_wave_velocity_samples": [
          {
            "pulse_wave_velocity_meters_per_second": 7.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "afib_classification_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "afib_classification": "NORMAL"
          }
        ],
        "ecg_signal": [
          {
            "start_timestamp": "2022-11-23T09:00:00.000000+02:00",
            "avg_hr_bpm": 72.5,
            "afib_classfication": 1,
            "raw_signal": [
              {
                "potential_uV": 1250.5,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ]
          }
        ],
        "rr_interval_samples": [
          {
            "rr_interval_ms": 850,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hr_bpm": 72
          }
        ]
      },
      "oxygen_data": {
        "vo2max_ml_per_min_per_kg": 42.5,
        "avg_saturation_percentage": 97,
        "vo2_samples": [
          {
            "vo2max_ml_per_min_per_kg": 45.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "saturation_samples": [
          {
            "percentage": 98,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "type": 0
          }
        ]
      },
      "glucose_data": {
        "detailed_blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "blood_glucose_samples": [
          {
            "glucose_level_flag": "NORMAL",
            "trend_arrow": "FLAT",
            "blood_glucose_mg_per_dL": 95,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "day_avg_blood_glucose_mg_per_dL": 92.5
      },
      "metadata": {
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "timestamp_localization": 0
      },
      "blood_pressure_data": {
        "blood_pressure_samples": [
          {
            "diastolic_bp": 80.5,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "systolic_bp": 120.5
          }
        ]
      },
      "temperature_data": {
        "body_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "skin_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ],
        "ambient_temperature_samples": [
          {
            "temperature_celsius": 37.2,
            "timestamp": "2022-11-23T09:00:00.000000+02:00"
          }
        ]
      }
    }
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "log_ids": [
    "text"
  ],
  "message": "text"
}
post

Used to post workout plans users can follow on their wearable. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
Responses
201
Returned when activity was successfully created on the provider
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
post
POST /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 523

{
  "data": [
    {
      "steps": {},
      "metadata": {
        "estimated_energy_kj": 1,
        "estimated_speed_meters_per_second": 1,
        "estimated_elevation_gain_meters": 1,
        "estimated_tss": 1,
        "estimated_calories": 1,
        "created_date": "2022-11-23T09:00:00.000000+02:00",
        "planned_date": "2022-11-24T09:00:00.000000+02:00",
        "type": "IN_VEHICLE",
        "id": "text",
        "estimated_duration_seconds": 1,
        "estimated_pace_minutes_per_kilometer": 1,
        "provider": "text",
        "estimated_tscore": 1,
        "description": "text",
        "name": "text",
        "estimated_distance_meters": 1,
        "estimated_if": 1,
        "pool_length_meters": 1
      }
    }
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "log_ids": [
    "text"
  ],
  "message": "text"
}
delete

Used to delete nutrition logs the user has registered on their account

Query parameters
user_idstringRequired

user ID to query data for

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
datastring[]Optional

List of identifiers for nutrition entries to be deleted

Responses
200
Returned when all records were deleted successfully
application/json
207
Returned when multiple status codes were obtained from attempting to delete the requested records
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
delete
DELETE /v2/nutrition HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "data": [
    "text"
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}
delete

Used to delete Body metrics the user has registered on their account

Query parameters
user_idstringRequired

user ID to query data for

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
log_idsstring[]Optional

List of identifiers for body metrics entries to be deleted

Responses
200
Returned when all records were deleted successfully
application/json
207
Returned when multiple status codes were obtained from attempting to delete the requested records
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when credentials (dev ID and API key) are invalid
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
delete
DELETE /v2/body HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "log_ids": [
    "text"
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}
delete

Used to delete workout plans the user has registered on their account. This can be stregnth workouts (sets, reps, weight lifted) or cardio workouts (warmup, intervals of different intensities, cooldown etc)

Query parameters
user_idstringRequired

user ID to query data for

Header parameters
dev-idstringRequired

your developer ID

Example: testingTerra
x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ
Body
datastring[]Optional

List of identifiers for planned workout entries to be deleted

Responses
200
Returned when all records were deleted successfully
application/json
207
Returned when multiple status codes were obtained from attempting to delete the requested records
application/json
400
Returned when one or more parameters is malformed - an appropriate error message will be returned
application/json
401
Returned when authorization with a data provider has failed
application/json
404
Returned when a parameter does not exist on Terra's end (e.g. user_id)
application/json
delete
DELETE /v2/plannedWorkout HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "data": [
    "text"
  ]
}
{
  "user": {
    "reference_id": "[email protected]",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "active": true
  },
  "processed_data": [
    {
      "id": "text",
      "response_code": 1
    }
  ]
}