REST API Endpoints

Our full OpenAPI spec is available at: https://github.com/tryterra/openapi/blob/master/dist/core/v2-bundled.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 /api/v2/integrations HTTP/1.1
Host: access.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 /api/v2/integrations/detailed HTTP/1.1
Host: access.tryterra.co
Accept: */*

200

Successful response containing a list of integrations.

{
  "status": "success",
  "providers": [
    {
      "provider": "MAPMYFITNESS",
      "name": "MapMyFitness",
      "icon": "https://access.tryterra.co/api/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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/auth/authenticateUser

POST /api/v2/auth/authenticateUser?resource=text HTTP/1.1
Host: access.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

dev-idstringRequired

Your developer ID for authentication and tracking

Responses

200

application/json

statusstringOptionalExample: success

tokenstringOptionalExample: 250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d

expires_inintegerOptionalDefault: 0Example: 180

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/auth/generateAuthToken

POST /api/v2/auth/generateAuthToken HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: 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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

post/auth/generateWidgetSession

POST /api/v2/auth/generateWidgetSession HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: 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

dev-idstringRequired

Your developer ID for authentication and tracking

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

A referenced resource does not exist on Terra's end.

application/problem+json

delete/auth/deauthenticateUser

DELETE /api/v2/auth/deauthenticateUser?user_id=text HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: 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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/userInfo

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "last_webhook_update": "2022-12-12T10:00:00.000000+00:00",
    "scopes": "activity:read,sleep:read",
    "reference_id": "[email protected]",
    "active": true,
    "last_polled_at": "2024-01-20T11:00:00Z",
    "most_recent_data_at": "2024-01-19T23:00:00Z"
  },
  "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

get/subscriptions

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

{
  "users": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "FITBIT",
      "created_at": "2022-12-12T10:00:00.000000+00:00",
      "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

created_atstringOptional

Time at which the connection was created

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

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/bulkUserInfo

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

[
  "text"
]

[
  {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/athlete

GET /api/v2/athlete?user_id=text HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: 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",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/activity

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/body

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/daily

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/menstruation

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/nutrition

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/sleep

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

get/plannedWorkout

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

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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 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

dev-idstringRequired

Your developer ID for authentication and tracking

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

log_idsstring[]Optional

List of identifiers for the objects created, returned in the same order they were posted. I.e. Posting [ObjectA, ObjectB] will return [IdentifierA, IdentifierB]

messagestringOptionalDefault: Planned workout successfully created

400

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/plannedWorkout

POST /api/v2/plannedWorkout?user_id=text HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: 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",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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 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

dev-idstringRequired

Your developer ID for authentication and tracking

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

One or more parameters is malformed. The detail field describes the specific problem.

application/problem+json

401

Authentication credentials are missing or invalid.

application/problem+json

404

A referenced resource does not exist on Terra's end.

application/problem+json

delete/plannedWorkout

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

{
  "data": [
    "text"
  ]
}

{
  "user": {
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "provider": "FITBIT",
    "created_at": "2022-12-12T10:00:00.000000+00:00",
    "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
    }
  ]
}

🛰️ v3 endpoints

NextOpenAPI Spec

Last updated 1 month ago

Was this helpful?