# Core concepts ## Developer ID (Dev ID) Your developer ID is your unique identifier for access to the API. This is how Terra identifies you, and ties [Users](#user) & their data back to you. {% hint style="info" %} Think of your dev ID like your username It does not constitute sensitive information. Making it publicly available is not a security conern {% endhint %} You may find your dev ID in the credentials section of your Terra Dashboard account ## API Key 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. {% hint style="info" %} Think of your API Key like your **password** It constitutes sensitive information. Making it publicly available is a big security risk {% endhint %} You may find your API Key in the credentials section of your Terra Dashboard account ## Destinations 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 [Terra Dashboard](https://dashboard.tryterra.co/dashboard/connections). ## Source/Provider/Integration 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 [Terra Dashboard](https://dashboard.tryterra.co/dashboard/connections). Check out the list of supported integrations [here](https://docs.tryterra.co/reference/health-and-fitness-api/supported-integrations) ## User 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". This means that multiple Users can be created for one individual, also referred to as an [End User](#end-user). Any time a e.g. Fitbit/Garmin/Google Fit account is connected through Terra, a [User](#user) is created ## End 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. ## Reference ID You can use a Reference ID in order to tie a [User](#user) back to an [End User](#end-user). 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. When creating a User, you will have the option of passing in a `reference_id` to conveniently link it back to an End User ## Event An **Event** is a piece of data (usually a JSON object) sent to your [Destination](#destinations). This can be one of the [Data Types](#data-types) or a metadata event type ## Large Request A [data](#data-types) request spanning more than 28 days (unless defined otherwise). This type of request will **always** be processed asynchronously, and sent to your [destinations](#destinations) in chunks. The chunks sent to you will each be of either * 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 ## Polled/Event-Driven integrations 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[ Provider's](#source-provider-integration) cloud, a notification (or **event**) gets sent to Terra with the newest data, following which Terra sends you a [payload](#payload) to your [Destination](#destinations) with the latest available data. 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**. ## Data Types ### Activity 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". ### Sleep 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. ### Daily 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.** 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 [Destination](#destinations). ### Menstruation 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). ### Body 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**. 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 [Destination](#destinations). ### Nutrition 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. ## API Versions Terra API is versioned in two main ways. ### Major API versions 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) ### Minor API 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.