For the complete documentation index, see llms.txt. This page is also available as Markdown.

Core concepts

Learn the terms and building blocks shared across Terra products.

Your Terra account has one or more environments, such as testing and production. Each environment has its own credentials, users and destinations, and every Terra product you use works inside it.

Product
Takes in
Sends results to

Unified API

Data from wearables and health apps

Your destinations

Lab Reports

Lab report files and DXA scans you upload

Your destinations

Vantage API

Test orders you place

The Vantage webhook URL

Credentials

Every Terra product uses the same two credentials. Find both under API keys in the header bar of the Terra Dashboard. Learn more about account setup and API keys.

Credential
Safe to expose
Description

Developer ID (dev-id)

Yes

Identifies one environment in your account. It works like a username.

API key (x-api-key)

No

Authenticates your requests and proves they come from the owner of the developer ID. Treat it like a password.

Send both as headers on every request. The Vantage API also accepts them as HTTP Basic auth.

Environments

Each environment has its own developer ID. Users, destinations and settings belong to one environment and are not shared with the others, so you can build and test without touching production data. Learn more about Terra environments.

End users and reference IDs

An end user is the real person whose data you are working with: the person wearing the device, uploading the lab report, or taking the test.

Terra does not know who the end user is in your system. When you connect a wearable, upload a report or place an order, pass your own ID for that person, such as a username, email address or database ID. Terra stores it as a reference ID and returns it with the result, so you can match the data back to the right person.

Product
Reference ID field

Unified API

reference_id

Lab Reports

reference_id

Vantage API

client_order_reference_id

Destinations

A destination is where Terra sends what a product produces: a webhook on your server, a SQL database, cloud storage such as Amazon S3, a queue such as Amazon SQS or Kafka, or a database such as MongoDB, Firestore or Supabase. Add destinations on the Connections page of the dashboard.

A destination receives every event type unless you limit it with destination_event_types. Learn more about destinations.

Events

An event is a JSON payload Terra sends to tell you something happened, such as new data arriving or a status changing. Each product has its own events, described in its section below.

API versions

Terra versions its APIs by date. A breaking change ships under a new date. Additive changes, such as a new field, reach every version.

Choose a version for a request with the X-Terra-Version header. Without it, the request uses the version your account is pinned to, which is the latest version at the time of your first request.

One date works across every product. Each product serves its newest version on or before the date you send. For example, if you send 2026-10-25, the Vantage API serves its 2026-10-15 version and Lab Reports serves its 2026-10-21 version. Learn more about versioning.

Unified API

The Unified API reads health and fitness data from wearables and apps and sends it to your destinations in one format.

Sources

A source is where health and fitness data comes from, such as Fitbit, Garmin or Apple Health. Other pages also call a source a provider or an integration. Enable sources on the Connections page, and see every source in the supported integrations list.

Sources send new data to Terra in one of two ways:

Type
Description

Event-driven

The provider notifies Terra as soon as the wearable's app syncs new data to the provider's cloud. This is the fastest way to get new data.

Polled

The provider has no notifications, so Terra checks its servers for new data every 15 minutes by default, and never more often.

Users

A user is one connection between Terra and one wearable account, such as one Fitbit account or one Garmin account. Each user has its own user_id, and Terra returns your reference_id on the user in every event.

One end user can have several users. If someone connects both their Fitbit and their Garmin, Terra creates two users with different user_ids that share one reference_id.

If an end user connects the same provider account again with the same reference_id, Terra replaces the old user with a new one, with a new user_id. Connecting a different account on the same provider adds a second user and leaves the first in place.

Data types

The Unified API has eight data types, each with a fixed structure. Learn more about every field in the data models reference.

Data type
Description

activity

One completed workout with a start and end time, such as a run recorded between pressing start and stop on a Garmin watch.

athlete

The end user's profile on the provider, such as name, age, sex, location and devices.

body

The end user's body metrics for one day, such as weigh-ins and blood glucose readings.

daily

The end user's total activity for one day.

hormone

One hormone test, with levels such as LH, FSH and hCG.

menstruation

One day of the menstrual cycle: the current phase and anything logged that day.

nutrition

The food an end user logged in one day, from apps such as MyFitnessPal.

sleep

One completed sleep session. If the device tracks it, the start time can be when the end user got into bed rather than when they fell asleep.

daily and body payloads arrive several times a day. Each one holds the running total for that day so far, so overwrite the stored payload for that date with the latest one.

Event delivery

Terra sends each event to each of your destinations as a separate delivery. A delivery is one or more attempts: the first send, plus any retries and resends. Learn more about event delivery.

Large requests

A request for more than one calendar month of data is a large request. Terra processes it in the background and sends the data to your destinations in chunks of 10 MB or less, so a large request must use to_webhook=true, which is the default.

Lab Reports

Lab Reports turns lab report PDFs, images and DXA scans into structured biomarker data.

Each upload creates a session, which tracks the report through extraction, standardization and delivery. Terra classifies the file as a clinical lab report or a DXA scan, matches each result to a known biomarker, and maps its unit to a standard UCUM code. It does not convert values between units.

When processing ends, Terra sends a lab_report.completed or lab_report.failed event to your destinations. Learn more about sessions and delivery.

Vantage API

The Vantage API orders blood and DNA tests and returns the results.

You order from a catalog of products, grouped by product type such as blood or DNA. Each product has variants, and a variant is what you order. Samples are collected at home, by kit or a visiting phlebotomist, or at a lab.

An order is one purchase for a recipient, and holds one or more order items. Each order item is tracked on its own: kit activation, results and acknowledgment all belong to the order item. The person who takes the test, the test taker, can be someone other than the recipient.

Vantage sends an event when an order's fulfilment status or an order item's results status changes. It sends events to one webhook URL per environment, not to your destinations. Learn more about orders, results and status lifecycles.

Streaming API

The Streaming API sends live readings, such as heart rate, from a wearable to your backend over WebSockets while the end user wears it.

Term
Description

Device

A wearable that streams over Bluetooth Low Energy (BLE), ANT+, or its own Bluetooth protocol (Apple Watch, Wear OS and Samsung watches).

Phone

The end user's iOS or Android phone. It connects to the device and runs your app with the Terra RT SDK.

Producer

A connection that sends data to Terra. The RT SDK on the phone is the producer.

Broker

Terra. It receives data from producers and passes it to every consumer connected to that stream.

Consumer

A connection that receives the stream, usually your backend.

Each WebSocket connection authenticates with its own short-lived token, minted by your backend. Learn more about streaming authentication.

See also

Last updated

Was this helpful?