Core concepts
Last updated
Was this helpful?
Last updated
Was this helpful?
Your developer ID is your unique identifier for access to the API. This is how Terra identifies you, and ties & their data back to you.
You may find your dev ID in the credentials section of your Terra Dashboard account
Your API key is your secret access token for the API. This is how Terra knows you're legitimately the developer behind the dev ID you're using.
You may find your API Key in the credentials section of your Terra Dashboard account
Terra sends data to your server through a Destination. At its most basic, this is a Webhook, but can also take the form of an SQL database, an Azure Blog storage, or an Amazon SQS queue. You can customize which Destination is active at any given time through your .
Throughout this documentation, a connection made to one fitness wearable account (e.g. one Fitbit account, or one Garmin account) will be referred to as "one User".
An End User represents a person who may own one or more wearable devices, and can have multiple Users associated to them through Terra.
When creating a User, you will have the option of passing in a reference_id to conveniently link it back to an End User
at most 10MB
at most 10 objects within the data array
whichever limit of the two gets hit first will determine the chunk's size
Integrations that are Polled do not have an event-sending system, and require Terra to periodically check for data updates by polling their servers. This will be done as often as every 5 minutes.
This represents a workout session completed (not currently active or planned) by the user, with a defined start and end time. For example, this corresponds to when a user woud press "start workout" on their Garmin smartwatch, go for a run, then press "end workout".
This represents a sleep session completed by the user. The start time and end time can be representative of the time that the user got in bed instead of the time that they fell asleep at, if tracked by the wearable device.
This represents a summary of the total activity completed by a user for a given 24 hour period, defined by the start and end time of the payload.
This represents a day in the user's menstrual cycle, and includes information about that day within the context of their overall monthly cycle, such as current phase, and any metadata associated with that day (bleeding level, feelings of nausea, etc).
This represents the various Body metrics for a user for a given 24 hour period, defined by the start and end time of the payload.
This represents the various food logged by a user for a given 24 hour period, defined by the start and end time of the payload.
This will be data logged in Food Diary apps such as MyFitnessPal, Fitbit or MacrosFirst. Each meal represents a given food item logged within that day.
Terra API is versioned in two main ways.
These API versions are very infrequent and represent a large architectural change in the API endpoints, and underlying infrastructure. You will identify these with the base URL (i.e. api.tryterra.co/v2, api.tryterra.co/v1, and access.tryterra.co are 3 separate major versions)
These can be identified by the version included in every payload you receive from Terra, and will be versioned by date. For example, at the time of writing, the latest API version is 2022-03-16. The version prior to it was 2022-03-02.
Only breaking changes to the API are versioned. Any non breaking changes will be continuously developed, tested, and deployed.
A Source (also referred to as a Provider, or Integration) is a wearable fitness & health data supplier, such as Fitbit, Garmin or Apple Health. These can be turned on or off (enabling or interrupting the flow of data) through your .
Check out the list of supported integrations
This means that multiple Users can be created for one individual, also referred to as an .
Any time a e.g. Fitbit/Garmin/Google Fit account is connected through Terra, a is created
You can use a Reference ID in order to tie a back to an . The reference_id should be the identifier of the End User on your systems. This could be the End User's username, their email address, or any way in which you identify them.
An Event is a piece of data (usually a JSON object) sent to your . This can be one of the or a metadata event type
A request spanning more than 28 days (unless defined otherwise).
This type of request will always be processed asynchronously, and sent to your in chunks. The chunks sent to you will each be of either
Integrations that are Event-Driven allow for the fastest data retrieval speeds. As soon as new data is synced from the user's wearable's app (e.g. the Fitbit app) to the cloud, a notification (or event) gets sent to Terra with the newest data, following which Terra sends you a to your with the latest available data.
These payloads will be sent multiple times throughout a given day, as a user moves around, and will be a total of their activity up until that point in the day. When ingesting Daily events, always overwrite data for a given date with the latest one sent to your .
These payloads will be sent multiple times throughout a given day, as a user generates more body-related metrics (weigh-ins, blood glucose measurements etc), and will be a total up until that point in the day. When ingesting Body events, always overwrite data for a given date with the latest one sent to your .