REST API Endpoints

Our full OpenAPI spec is available at: https://github.com/tryterra/openapi/blob/master/v5.yaml

🕸️ API info

Get list of available integrations

get

Retrieve a list of all available provider integrations on the API.

Responses

200

Returns list of all available integrations on the API

application/json

providersstring[]OptionalExample: FITBIT

sdk_resourcestring[]OptionalExample: APPLE

statusstring · enumOptionalDefault: successPossible values:

get

/integrations

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.

Responses

200

Successful response containing a list of integrations.

application/json

statusstringOptional

Status of the API response

Example: success

get

/integrations/detailed

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

🔌 Authentication

Generate an authentication link

post

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

resourcestringRequired

Provider resource identifier (e.g., 'FITBIT', 'GARMIN', 'OURA'). See "Get detailed list of integrations" for available providers

Example: FITBIT

Header parameters

dev-idstringRequired

your developer ID

Example: testingTerra

Body

languagestringOptional

reference_idstringOptional

auth_success_redirect_urlstringOptional

auth_failure_redirect_urlstringOptional

Responses

200

Returned when authentication link could be successfully generated

application/json

statusstring · enumOptional

indicates that the request was successful

Example: successPossible values:

user_idstringOptional

User ID for the user being created

Example: 23dc2540-7139-44c6-8158-f81196e2cf2e

auth_urlstringOptional

authentication URL the user must be redirected to in order to link their account

Example:

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

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

/auth/authenticateUser

POST /v2/auth/authenticateUser?resource=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: text
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "language": "text",
  "reference_id": "text",
  "auth_success_redirect_url": "text",
  "auth_failure_redirect_url": "text"
}

{
  "status": "success",
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=23BBG9&scope=settings+nutrition+sleep+heartrate+electrocardiogram+weight+respiratory_rate+oxygen_saturation+profile+temperature+cardio_fitness+activity+location&state=bLqqjPie9ptwoWm6VBxHCu6JkkoWJp"
}

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)

Authorizations

x-api-keystringRequired

Your API key for authentication

Responses

200

application/json

statusstringOptionalExample: success

tokenstringOptionalExample: 250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d

expires_inintegerOptionalDefault: 0Example: 180

404

application/json

post

/auth/generateAuthToken

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

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

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

Authorizations

x-api-keystringRequired

Your API key for authentication

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

session_idstringOptional

Session ID for the widget authentication session

Example: 23dc2540-7139-44c6-8158-f81196e2cf2e

urlstringOptional

the widget URL the user must be redirected to in order to link their account

Example: https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd

statusstring · enumOptional

indicates that the request was successful (value is success)

Example: successPossible values:

expires_innumberOptional

a number in seconds depicting how long the url is valid for

Example: 900

400

Returned when one or more parameters is malformed - an appropriate error message will be returned

application/json

post

/auth/generateWidgetSession

POST /v2/auth/generateWidgetSession HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "providers": "GARMIN,FITBIT,OURA,WITHINGS,SUUNTO",
  "language": "en",
  "reference_id": "[email protected]",
  "auth_success_redirect_url": "https://myapp.com/success",
  "auth_failure_redirect_url": "https://myapp.com/failure"
}

{
  "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
  "status": "success",
  "expires_in": 900
}

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to deauthenticate and remove from Terra system

Responses

200

Returned when user is successfully deauthenticated and data is deleted

application/json

statusstring · enumOptional

indicates that the deauthentication was successful (value is success)

Possible values:

404

Returned when the user_id is not existent

application/json

delete

/auth/deauthenticateUser

DELETE /v2/auth/deauthenticateUser?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "status": "success"
}

💁‍♂️ User info

Get information for a single user ID or multiple users by reference ID

get

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringOptional

user ID to query for

reference_idstringOptional

reference ID to query for

Responses

200

Returned when the provided resources are found

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

get

/userInfo

GET /v2/userInfo HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

Get all Terra User IDs

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

Authorizations

x-api-keystringRequired

Your API key for authentication

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

Responses

200

Returned upon a successful request

application/json

400

Returned when one or more parameters are malformed

application/json

get

/subscriptions

GET /v2/subscriptions HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

Get information for multiple user IDs

post

Used to query for information for multiple Terra User IDs

Authorizations

x-api-keystringRequired

Your API key for authentication

Bodystring[]

string[]Optional

List of user IDs to get information for

Responses

200

Returned upon successful request

application/json

List of User objects

user_idstring · min: 1Required

Terra identifier for the wearable connection

Example: 123e4567-e89b-12d3-a456-426614174000

providerstring · min: 1Required

Connection data source

Example: FITBIT

last_webhook_updatestringOptional

Last time at which a webhook update was sent for the connection

Example: 2022-12-12T10:00:00.000000+00:00

scopesstringOptional

(when available) Permissions granted by the user during authentication - to be used as debugging metadata

Example: activity:read,sleep:read

reference_idstringOptional

Connection identifier on the developer's end, used to tie connection back to a user on the developer's platform

Example: [email protected]

activebooleanOptional

whether the user is active or not (inactive users will not receive any data updates and are in considered

Example: true

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

/bulkUserInfo

POST /v2/bulkUserInfo HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 8

[
  "text"
]

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

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

Responses

200

Returned upon successful data request

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

get

/athlete

GET /v2/athlete?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "athlete": {
    "age": 28,
    "country": "United States",
    "bio": "Passionate runner and cyclist",
    "state": "California",
    "last_name": "Smith",
    "sex": "male",
    "city": "San Francisco",
    "email": "[email protected]",
    "date_of_birth": "1999-11-23",
    "first_name": "John",
    "gender": "male",
    "joined_provider": "2023-01-15",
    "devices": [
      {
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "data_provided": [
          "text"
        ],
        "hardware_version": "v2.1",
        "last_upload_date": "text",
        "manufacturer": "Garmin",
        "name": "Forerunner 945",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1",
            "activation_timestamp": "text",
            "data_provided": [
              "text"
            ],
            "last_upload_date": "text"
          }
        ],
        "sensor_state": "text",
        "serial_number": "GR123456789",
        "software_version": "5.2.1"
      }
    ]
  },
  "type": "athlete",
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "reference_id": "[email protected]",
    "active": true
  }
}

⏳ Historical Data retrieval

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/activity

GET /v2/activity?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/body

GET /v2/body?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/daily

GET /v2/daily?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "reference_id": "[email protected]",
    "active": true
  },
  "data": [
    {
      "active_durations_data": {
        "activity_levels_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 4
          }
        ],
        "activity_seconds": 1800,
        "inactivity_seconds": 600,
        "low_intensity_seconds": 900,
        "moderate_intensity_seconds": 600,
        "num_continuous_inactive_periods": 3,
        "rest_seconds": 120,
        "vigorous_intensity_seconds": 300,
        "standing_hours_count": 1,
        "standing_seconds": 1
      },
      "calories_data": {
        "BMR_calories": 1,
        "calorie_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "calories": 1,
            "timer_duration_seconds": 1
          }
        ],
        "net_activity_calories": 1,
        "net_intake_calories": 1,
        "total_burned_calories": 1
      },
      "data_enrichment": {
        "cardiovascular_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "cardiovascular_score": 1,
        "immune_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "immune_index": 1,
        "readiness_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "readiness_score": 1,
        "respiratory_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "respiratory_score": 1,
        "start_time": "text",
        "stress_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "total_stress_score": 1
      },
      "device_data": {
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "data_provided": [
          "text"
        ],
        "hardware_version": "v2.1",
        "last_upload_date": "text",
        "manufacturer": "Garmin",
        "name": "Forerunner 945",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1",
            "activation_timestamp": "text",
            "data_provided": [
              "text"
            ],
            "last_upload_date": "text"
          }
        ],
        "sensor_state": "text",
        "serial_number": "GR123456789",
        "software_version": "5.2.1"
      },
      "distance_data": {
        "detailed": {
          "distance_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "distance_meters": 2500,
              "timer_duration_seconds": 900
            }
          ],
          "elevation_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "elev_meters": 925,
              "timer_duration_seconds": 1200
            }
          ],
          "floors_climbed_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "floors_climbed": 5,
              "timer_duration_seconds": 600
            }
          ],
          "step_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "steps": 1,
              "timer_duration_seconds": 1
            }
          ]
        },
        "distance_meters": 8500.45,
        "elevation": {
          "avg_meters": 950,
          "gain_actual_meters": 550,
          "gain_planned_meters": 500,
          "loss_actual_meters": 450,
          "max_meters": 1200,
          "min_meters": 800
        },
        "floors_climbed": 15,
        "steps": 12000,
        "swimming": {
          "num_laps": 20,
          "num_strokes": 500,
          "pool_length_meters": 25
        }
      },
      "heart_rate_data": {
        "detailed": {
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142,
              "timer_duration_seconds": 600,
              "context": 1
            }
          ],
          "hrv_samples_rmssd": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_rmssd": 42.1
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        },
        "summary": {
          "avg_hr_bpm": 145,
          "avg_hrv_rmssd": 35.2,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": 2,
              "start_percentage": 60,
              "end_percentage": 70,
              "name": "Aerobic",
              "duration_seconds": 300
            }
          ],
          "max_hr_bpm": 180,
          "min_hr_bpm": 85,
          "resting_hr_bpm": 65,
          "user_max_hr_bpm": 190
        }
      },
      "MET_data": {
        "MET_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 1
          }
        ],
        "avg_level": 3.8,
        "num_high_intensity_minutes": 10,
        "num_inactive_minutes": 5,
        "num_low_intensity_minutes": 15,
        "num_moderate_intensity_minutes": 25
      },
      "metadata": {
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "timestamp_localization": 0,
        "upload_type": 1
      },
      "oxygen_data": {
        "avg_saturation_percentage": 98,
        "saturation_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "percentage": 98,
            "type": 0
          }
        ],
        "vo2_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "vo2max_ml_per_min_per_kg": 45.5
          }
        ],
        "vo2max_ml_per_min_per_kg": 45.5
      },
      "scores": {
        "activity": 92,
        "recovery": 78,
        "sleep": 85,
        "biological_age": 27
      },
      "strain_data": {
        "strain_level": 14.5
      },
      "stress_data": {
        "avg_stress_level": 45.5,
        "activity_stress_duration_seconds": 3600,
        "low_stress_duration_seconds": 28800,
        "max_stress_level": 85,
        "medium_stress_duration_seconds": 7200,
        "samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 1
          }
        ],
        "rest_stress_duration_seconds": 1800,
        "high_stress_duration_seconds": 900,
        "stress_duration_seconds": 5400,
        "stress_rating": 3,
        "body_battery_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 1
          }
        ]
      },
      "tag_data": {
        "tags": [
          {
            "timestamp": "1999-11-23T09:00:00.000000+02:00",
            "tag_name": "hot_shower",
            "notes": "Felt refreshed after"
          }
        ]
      }
    }
  ],
  "type": null
}

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/menstruation

GET /v2/menstruation?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "reference_id": "[email protected]",
    "active": true
  },
  "data": [
    {
      "metadata": {
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "timestamp_localization": 0
      },
      "menstruation_data": {
        "period_length_days": 5,
        "current_phase": "menstrual",
        "length_of_current_phase_days": 5,
        "days_until_next_phase": 23,
        "period_start_date": "2022-11-28",
        "predicted_cycle_length_days": 28,
        "day_in_cycle": 24,
        "last_updated_time": "2022-12-12T14:03:05.000000-05:00",
        "cycle_length_days": "28",
        "is_predicted_cycle": "true",
        "menstruation_flow": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "flow": 4
          }
        ]
      }
    }
  ],
  "type": null
}

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/nutrition

GET /v2/nutrition?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

with_samplesbooleanOptional

Boolean flag specifying whether to include detailed samples in the returned payload (default: false)

Responses

200

Returned upon successful data request

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

get

/sleep

GET /v2/sleep?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "reference_id": "[email protected]",
    "active": true
  },
  "data": [
    {
      "data_enrichment": {
        "sleep_contributors": [
          {
            "contributor_name": "text",
            "contributor_score": 1
          }
        ],
        "sleep_score": 1
      },
      "device_data": {
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "data_provided": [
          "text"
        ],
        "hardware_version": "v2.1",
        "last_upload_date": "text",
        "manufacturer": "Garmin",
        "name": "Forerunner 945",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1",
            "activation_timestamp": "text",
            "data_provided": [
              "text"
            ],
            "last_upload_date": "text"
          }
        ],
        "sensor_state": "text",
        "serial_number": "GR123456789",
        "software_version": "5.2.1"
      },
      "heart_rate_data": {
        "detailed": {
          "hr_samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "bpm": 142,
              "timer_duration_seconds": 600,
              "context": 1
            }
          ],
          "hrv_samples_rmssd": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_rmssd": 42.1
            }
          ],
          "hrv_samples_sdnn": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "hrv_sdnn": 48.3
            }
          ]
        },
        "summary": {
          "avg_hr_bpm": 145,
          "avg_hrv_rmssd": 35.2,
          "avg_hrv_sdnn": 45.5,
          "hr_zone_data": [
            {
              "zone": 2,
              "start_percentage": 60,
              "end_percentage": 70,
              "name": "Aerobic",
              "duration_seconds": 300
            }
          ],
          "max_hr_bpm": 180,
          "min_hr_bpm": 85,
          "resting_hr_bpm": 65,
          "user_max_hr_bpm": 190
        }
      },
      "metadata": {
        "end_time": "2022-11-24T08:00:00.000000+01:00",
        "is_nap": false,
        "start_time": "1999-11-23T22:00:00.000000+02:00",
        "summary_id": "text",
        "timestamp_localization": 0,
        "upload_type": 1
      },
      "readiness_data": {
        "readiness": 85,
        "recovery_level": 5
      },
      "respiration_data": {
        "breaths_data": {
          "avg_breaths_per_min": 14,
          "max_breaths_per_min": 18,
          "min_breaths_per_min": 10,
          "on_demand_reading": false,
          "samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "breaths_per_min": 16
            }
          ],
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "end_time": "2022-11-24T08:00:00.000000+01:00"
        },
        "oxygen_saturation_data": {
          "avg_saturation_percentage": 97,
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "percentage": 98,
              "type": 0
            }
          ],
          "start_time": "1999-11-23T22:00:00.000000+02:00"
        },
        "snoring_data": {
          "start_time": "1999-11-23T22:00:00.000000+02:00",
          "end_time": "2022-11-24T08:00:00.000000+01:00",
          "num_snoring_events": 12,
          "samples": [
            {
              "timestamp": "2022-11-23T09:00:00.000000+02:00",
              "duration_seconds": 120
            }
          ],
          "total_snoring_duration_seconds": 3600
        }
      },
      "scores": {
        "sleep": 1
      },
      "sleep_durations_data": {
        "asleep": {
          "duration_asleep_state_seconds": 25200,
          "duration_deep_sleep_state_seconds": 5400,
          "duration_light_sleep_state_seconds": 14400,
          "duration_REM_sleep_state_seconds": 5400,
          "num_REM_events": 4
        },
        "awake": {
          "duration_awake_state_seconds": 1200,
          "duration_long_interruption_seconds": 600,
          "duration_short_interruption_seconds": 180,
          "num_out_of_bed_events": 1,
          "num_wakeup_events": 3,
          "sleep_latency_seconds": 900,
          "wake_up_latency_seconds": 300
        },
        "hypnogram_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "level": 2
          }
        ],
        "other": {
          "duration_in_bed_seconds": 28800,
          "duration_unmeasurable_sleep_seconds": 300
        },
        "sleep_efficiency": 87.5
      },
      "temperature_data": {
        "delta": 0.5
      }
    }
  ],
  "type": null
}

Retrieve workout plans for a given user ID

get

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

start_dateone ofRequired

Start date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

end_dateone ofOptional

End date for data query - either ISO8601 date (YYYY-MM-DD) or unix timestamp in seconds (10-digit)

integerOptional

string · dateOptional

to_webhookbooleanOptional

Boolean flag specifying whether to send the data retrieved to the webhook instead of in the response (default: true if not provided)

Responses

200

Returned upon successful data request

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

get

/plannedWorkout

GET /v2/plannedWorkout?user_id=text&start_date=1 HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Accept: */*

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

✏️ Writing data

Post activity data to a provider

post

Used to post activity data to a provider. This endpoint only works for users connected via Wahoo. Returns error for other providers.

Authorizations

x-api-keystringRequired

Your API key for authentication

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

/activity

POST /v2/activity HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 5155

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

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

Post nutrition logs to a provider

post

Used to post nutrition logs to a provider. This endpoint only works for users connected via Fitbit. Returns error for other providers.

Authorizations

x-api-keystringRequired

Your API key for authentication

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

/nutrition

POST /v2/nutrition HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2618

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

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

Post body data to a provider

post

Used to post body data to a provider. This endpoint only works for users connected via Google Fit. Returns error for other providers.

Authorizations

x-api-keystringRequired

Your API key for authentication

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

/body

POST /v2/body HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 3729

{
  "data": [
    {
      "blood_pressure_data": {
        "blood_pressure_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "diastolic_bp": 80.5,
            "systolic_bp": 120.5
          }
        ]
      },
      "device_data": {
        "activation_timestamp": "2022-12-25T00:00:00.000000+05:00",
        "data_provided": [
          "text"
        ],
        "hardware_version": "v2.1",
        "last_upload_date": "text",
        "manufacturer": "Garmin",
        "name": "Forerunner 945",
        "other_devices": [
          {
            "manufacturer": "Garmin",
            "hardware_version": "v2.1",
            "serial_number": "GR123456789",
            "name": "Forerunner 945",
            "software_version": "5.2.1",
            "activation_timestamp": "text",
            "data_provided": [
              "text"
            ],
            "last_upload_date": "text"
          }
        ],
        "sensor_state": "text",
        "serial_number": "GR123456789",
        "software_version": "5.2.1"
      },
      "heart_data": {
        "afib_classification_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "afib_classification": 1
          }
        ],
        "ecg_signal": [
          {
            "start_timestamp": "text",
            "avg_hr_bpm": 72.5,
            "afib_classification": 1,
            "raw_signal": [
              {
                "potential_uV": 1250.5,
                "timestamp": "2022-11-23T09:00:00.000000+02:00"
              }
            ]
          }
        ],
        "heart_rate_data": {
          "detailed": {
            "hr_samples": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "bpm": 142,
                "timer_duration_seconds": 600,
                "context": 1
              }
            ],
            "hrv_samples_rmssd": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_rmssd": 42.1
              }
            ],
            "hrv_samples_sdnn": [
              {
                "timestamp": "2022-11-23T09:00:00.000000+02:00",
                "hrv_sdnn": 48.3
              }
            ]
          },
          "summary": {
            "avg_hr_bpm": 145,
            "avg_hrv_rmssd": 35.2,
            "avg_hrv_sdnn": 45.5,
            "hr_zone_data": [
              {
                "zone": 2,
                "start_percentage": 60,
                "end_percentage": 70,
                "name": "Aerobic",
                "duration_seconds": 300
              }
            ],
            "max_hr_bpm": 180,
            "min_hr_bpm": 85,
            "resting_hr_bpm": 65,
            "user_max_hr_bpm": 190
          }
        },
        "pulse_wave_velocity_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "pulse_wave_velocity_meters_per_second": 7.2
          }
        ],
        "rr_interval_samples": [
          {
            "rr_interval_ms": 850,
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hr_bpm": 72
          }
        ]
      },
      "hydration_data": {
        "day_total_water_consumption_ml": 2500,
        "hydration_amount_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "hydration_kg": 40
          }
        ]
      },
      "ketone_data": {
        "ketone_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "ketone_mg_per_dL": 1.5,
            "sample_type": 1
          }
        ]
      },
      "measurements_data": {
        "measurements": [
          {
            "measurement_time": "2022-11-23T09:00:00.000000+02:00",
            "BMI": 22.4,
            "BMR": 1800,
            "RMR": 2000,
            "estimated_fitness_age": "25",
            "skin_fold_mm": 12.5,
            "bodyfat_percentage": 18.5,
            "weight_kg": 75.5,
            "height_cm": 178,
            "bone_mass_g": 3200,
            "muscle_mass_g": 35000,
            "lean_mass_g": 61500,
            "water_percentage": 60.5,
            "insulin_units": 10.5,
            "insulin_type": "rapid-acting",
            "urine_color": "pale yellow",
            "user_notes": "text"
          }
        ]
      },
      "metadata": {
        "end_time": "2022-10-28T10:00:00.000000+01:00",
        "start_time": "1999-11-23T09:00:00.000000+02:00",
        "timestamp_localization": 0
      },
      "oxygen_data": {
        "avg_saturation_percentage": 98,
        "saturation_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "percentage": 98,
            "type": 0
          }
        ],
        "vo2_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "vo2max_ml_per_min_per_kg": 45.5
          }
        ],
        "vo2max_ml_per_min_per_kg": 45.5
      },
      "temperature_data": {
        "ambient_temperature_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "temperature_celsius": 37.2
          }
        ],
        "body_temperature_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "temperature_celsius": 37.2
          }
        ],
        "skin_temperature_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "temperature_celsius": 37.2
          }
        ]
      },
      "glucose_data": {
        "blood_glucose_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "blood_glucose_mg_per_dL": 95,
            "glucose_level_flag": 1,
            "trend_arrow": 4
          }
        ],
        "detailed_blood_glucose_samples": [
          {
            "timestamp": "2022-11-23T09:00:00.000000+02:00",
            "blood_glucose_mg_per_dL": 95,
            "glucose_level_flag": 1,
            "trend_arrow": 4
          }
        ],
        "day_avg_blood_glucose_mg_per_dL": 92.5,
        "gmi": 1,
        "time_in_range": 1,
        "sensor_usage": 1,
        "daily_patterns": [
          {
            "time_from_midnight": 9,
            "percentile_5": 1,
            "percentile_25": 1,
            "percentile_50": 1,
            "percentile_75": 1,
            "percentile_95": 1
          }
        ]
      }
    }
  ]
}

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

Post workout plans to a provider

post

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

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

/plannedWorkout

POST /v2/plannedWorkout?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 709

{
  "data": [
    {
      "steps": [
        {
          "targets": [
            {
              "target_type": "HEART_RATE"
            }
          ],
          "type": "STEP",
          "intensity": "REST",
          "order": 1,
          "description": "text",
          "durations": [
            {
              "duration_type": "TIME"
            }
          ],
          "name": "text"
        }
      ],
      "metadata": {
        "estimated_energy_kj": null,
        "estimated_speed_meters_per_second": null,
        "estimated_elevation_gain_meters": null,
        "estimated_tss": null,
        "estimated_calories": null,
        "created_date": "2022-11-23T09:00:00.000000+02:00",
        "planned_date": "2022-11-24T09:00:00.000000+02:00",
        "type": "IN_VEHICLE",
        "id": null,
        "estimated_duration_seconds": null,
        "estimated_pace_minutes_per_kilometer": null,
        "provider": "text",
        "estimated_tscore": null,
        "description": null,
        "name": null,
        "estimated_distance_meters": null,
        "estimated_if": null,
        "pool_length_meters": null
      }
    }
  ]
}

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

Delete nutrition logs for a given user ID

delete

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

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

/nutrition

DELETE /v2/nutrition?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "data": [
    "text"
  ]
}

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

Delete body metrics for a given user ID

delete

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

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

/body

DELETE /v2/body?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "log_ids": [
    "text"
  ]
}

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

Delete workout plans for a given user ID

delete

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

Authorizations

x-api-keystringRequired

Your API key for authentication

Query parameters

user_idstringRequired

Terra user ID (UUID format) to retrieve data for

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

/plannedWorkout

DELETE /v2/plannedWorkout?user_id=text HTTP/1.1
Host: api.tryterra.co
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "data": [
    "text"
  ]
}

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

NextOpenAPI Spec

Last updated 2 months ago

Was this helpful?

hashtag🕸️ API info

hashtagGet list of available integrations

hashtagGet detailed list of integrations

hashtag🔌 Authentication

hashtagGenerate an authentication link

hashtagGenerates an authentication token for the Terra mobile SDKs

hashtagGenerate an authentication link, using the Terra Authentication Widget

hashtagDeauthenticates a user and deletes any cached data for them

hashtag💁‍♂️ User info

hashtagGet information for a single user ID or multiple users by reference ID

hashtagGet all Terra User IDs

hashtagGet information for multiple user IDs

hashtagRetrieve user profile info for a given user ID

hashtag⏳ Historical Data retrieval

hashtagRetrieve activity data for a given user ID

hashtagRetrieve body metrics for a given user ID

hashtagRetrieve daily activity summaries for a given user ID

hashtagRetrieve menstruation data for a given user ID

hashtagRetrieve nutrition log data for a given user ID

hashtagRetrieve sleep sessions for a given user ID

hashtagRetrieve workout plans for a given user ID

hashtag✏️ Writing data

hashtagPost activity data to a provider

hashtagPost nutrition logs to a provider

hashtagPost body data to a provider

hashtagPost workout plans to a provider

hashtagDelete nutrition logs for a given user ID

hashtagDelete body metrics for a given user ID

hashtagDelete workout plans for a given user ID

🕸️ API info

Get list of available integrations

Get detailed list of integrations

🔌 Authentication

Generate an authentication link

Generates an authentication token for the Terra mobile SDKs

Generate an authentication link, using the Terra Authentication Widget

Deauthenticates a user and deletes any cached data for them

💁‍♂️ User info

Get information for a single user ID or multiple users by reference ID

Get all Terra User IDs

Get information for multiple user IDs

Retrieve user profile info for a given user ID

⏳ Historical Data retrieval

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

✏️ Writing data

Post activity data to a provider

Post nutrition logs to a provider

Post body data to a provider

Post workout plans to a provider

Delete nutrition logs for a given user ID

Delete body metrics for a given user ID

Delete workout plans for a given user ID