REST API Endpoints

NextSupported integrations

Last updated 14 days ago

Was this helpful?

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

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

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

string · dateOptional

end_dateone ofOptional

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

integerOptional

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

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

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": "Activity successfully logged"
}

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": "Nutrition successfully logged"
}

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": "Body data successfully logged"
}

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": "Nutrition successfully logged"
}

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

Generates an authentication token for the Terra mobile SDKs

post

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)

Header parameters

dev-idstringRequired

your developer ID

Example: testingTerra

x-api-keystringRequired

your API key

Example: OtHJok60oQmT8zhnUWc4SWBJI7ztPTs88C0gOsJJ

Responses

200

application/json

404

application/json

post

POST /v2/auth/generateAuthToken HTTP/1.1
Host: api.tryterra.co
dev-id: text
x-api-key: text
Accept: */*

{
    "status": "success",
    "token": "250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d",
    "expires_in": 180
}

REST API Endpoints

REST API Endpoints

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

🕸️ API info

🔌 Authentication

💁‍♂️ User info

⏳ Historical Data retrieval

✏️ Writing data

Get list of available integrations

Get detailed list of integrations

Deauthenticates a user and deletes any cached data for them

Retrieve user profile info for a given user ID

Retrieve activity data for a given user ID

Retrieve body metrics for a given user ID

Retrieve daily activity summaries for a given user ID

Retrieve menstruation data for a given user ID

Retrieve nutrition log data for a given user ID

Retrieve sleep sessions for a given user ID

Retrieve workout plans for a given user ID

Generate an authentication link

Generate an authentication link, using the Terra Authentication Widget

Generates an authentication token for the Terra mobile SDKs