Quickstart

All Terra requests can be downloaded as a postman collection here

curl --location --request POST 'https://api.tryterra.co/v2/auth/generateWidgetSession' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY' \

You'll receive a JSON response that looks like the following

{
    "expires_in": 900, //Length of the auth session, in seconds
    "session_id": SOME_SESSION_ID, //unique ID for the session
    "status": "success",
    "url": "https://widget.tryterra.co/session/SOME_SESSION_ID" //URL to access the session
}

From which you can copy & paste the URL into your browser, select a provider, and authenticate.

Upon the final redirection, your URL will look like the following:

https://widget.tryterra.co/session/demo/success?user_id=SOME_USER_ID&resource=SOME_PROVIDER

Where the authenticated user ID will be available as a query parameter for convenience. You can copy this user ID and save it somewhere for convenience

🚧

User creation

The newly created TerraUser object will also be sent to your webhook

2. Request Data

Once you've connected an account and saved the User ID provided, you can now make data requests.

These can be made for:

• Activity - event recorded for a specific workout
• Athlete - user information
• Body - data relating to body measurements, such as weight, height, glucose etc...
• Daily - daily summary of a user's total activity such as steps, distance, etc...
• Menstruation - log of a user's menstruation data
• Nutrition - log of a user's nutrition data, including both individual meals and a daily summary
• Sleep - events recorded for sleep sessions

You can now try this out for yourself with your newly created TerraUser Make a request with the format:

curl --location -g --request GET 'https://api.tryterra.co/v2/activity?to_webhook=false&user_id=YOUR_USER_ID&start_date=2022-07-20&end_date=2022-07-22&to_webhook=false' \
--header 'dev-id: YOUR_DEV_ID' \
--header 'X-API-Key: YOUR_API_KEY'

Query parameters to include:

to_webhook': set to false for testing - this ensures you get the data in the HTTP response and not [asynchronously sent to your webhook](doc:getting-data-into-your-project) user_id: the user ID of the user created in step 1 start_date: ISO8601 date string for which you want to query end_date`: ISO8601 date string for which you want to query

You should now receive the requested data in the HTTP response.

3. Data updates

Ideally, you will want to automatically receive up-to-date data without having to query the API for it.
To do that, set up a webhook endpoint - essentially an endpoint on your server which accepts HTTP POST requests.

Once done, make sure you handle each event type appropriately.