Terra API

https://docs.tryterra.co/
Admin
Terra API is a unified API that simplifies connecting applications to a vast ecosystem of health and...
Tokens:599,964
Snippets:4,925
Trust Score:8.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Deploy the example app with setup script

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-basecamp

Clones the repository, installs dependencies, and runs the setup script. The setup provisions a Neon database, a Worker, and an R2 bucket, runs migrations, deploys, and prints the App URL. It asks for your Terra dev-id, API key, and webhook signing secret from the dashboard. Re-running it is idempotent.

```bash
terra examples clone unified-api-web-app my-app
cd my-app
npm install
npm run setup
```

--------------------------------

### Start in demo mode

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-panel

Clones the example app, installs dependencies, and runs the dev server. Opens at http://localhost:5173 with mutating actions disabled behind a banner; uses the same read path as live mode served from a local cache.

```bash
terra examples clone lab-reports-web-app my-app
cd my-app
npm install
npm run dev
```

--------------------------------

### Clone and run the Vantage example app

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-dispatch

Clones the vantage-web-app example, installs dependencies, and starts the development server. The API runs on port 8787 and the SPA on 5173; open http://localhost:5173 for a read-only walkthrough on captured sandbox data.

```bash
terra examples clone vantage-web-app my-app
cd my-app && npm install && npm run dev
```

--------------------------------

### Start in demo mode

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-dispatch

Clones the example, installs dependencies, and runs the dev server in demo mode. Requires Terra CLI and Node.js v20+. The API runs on port 8787 and the SPA on 5173; open http://localhost:5173 for a read-only walkthrough on real captured sandbox data.

```bash
terra examples clone vantage-web-app my-app
cd my-app
npm install
npm run dev
```

--------------------------------

### Clone and install dependencies for streaming-mobile-app

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-grip

Clones the example app and installs dependencies. This is the first step of the 'Build and launch' workflow.

```bash
terra examples clone streaming-mobile-app my-app
cd my-app/app
npm install
```

--------------------------------

### Clone and run the streaming consumer web app

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-pulse

Clones the example app, installs dependencies, and starts the dev server. Requires Terra CLI, Node.js 18+, and a Terra Dev ID and API key.

```bash
terra examples clone streaming-consumer-web-app my-app
cd my-app && npm install && npm run dev
```

--------------------------------

### Prompt for setting up Terra CLI for any agent

Source: https://docs.tryterra.co/developer-tools/terra-cli/coding-agents

Paste this prompt into any coding agent that doesn't have the Terra API plugin. It instructs the agent to install the CLI and run `terra agent setup` to install Terra's agent skills.

```text
Set up the Terra API CLI for this project. Install it with
"brew install tryterra/tap/terra" on macOS, or "npm install -g @tryterra/cli"
otherwise. Then run "terra agent setup" to install Terra's agent skills, read
the terra-cli skill it writes, and follow its getting-started section to tell
me what my account is configured to do.
```

--------------------------------

### Enable data sources via Terra CLI prompt

Source: https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-sources

A prompt example for the Terra CLI to enable specific data sources in a staging environment. It includes installation commands (brew install tryterra/tap/terra or npm install -g @tryterra/cli), login, and usage of terra docs ask and terra <command> --help.

```text
Enable Garmin, Fitbit, and Oura in my staging environment.

Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "<question>" for anything you need from the Terra docs, and terra <command> --help for usage.
```

--------------------------------

### Set up and run the downloaded app

Source: https://docs.tryterra.co/developer-tools/example-apps

Open the downloaded directory and install its dependencies. Follow the app's README to configure credentials and run it.

```bash
cd my-app
npm install
```

--------------------------------

### GET /api/v2/integrations/detailed - JSON Response

Source: https://docs.tryterra.co/reference/health-and-fitness-api

Example response for the detailed integrations endpoint, showing provider details such as name, icon, setup type, and enabled status.

```json
{
  "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
      }
    }
  ]
}
```

--------------------------------

### terra admin-api raw request examples

Source: https://docs.tryterra.co/developer-tools/terra-cli/raw-requests

Use terra admin-api to send requests to any admin API endpoint. The path is relative to the configured base URL and must start with '/'. Examples include GET, POST, PATCH, and DELETE requests.

```bash
terra admin-api /me
terra admin-api /environments -q limit=5
terra admin-api /environments -X POST -d dev_id=dev-new -d name=Staging
terra admin-api /company -X PATCH --body '{"display_name":"Acme"}'
terra admin-api /tokens/tok_123 -X DELETE
```

--------------------------------

### Set up an environment

Source: https://docs.tryterra.co/developer-tools/terra-cli/terra-cli

Enables GARMIN as a data source, creates a webhook destination, and retrieves the API key. Requires keys:read for credential reads and data API key lookup.

```bash
terra unified-api sources enable GARMIN
# Garmin appears in the auth widget and starts syncing to your destinations

terra unified-api destinations create --type webhook --url https://example.com/hook
# prints the new destination's id

terra environments retrieve-api-key
# prints the dev-id, API key, and webhook signing secret
```

--------------------------------

### Prompt to get started with Terra API

Source: https://docs.tryterra.co/developer-tools/terra-cli/coding-agents

After the skills are installed, a later session needs only this prompt. The agent checks authentication, finds environments, reports which providers are on and where webhooks go, and names the gap that matters.

```text
Get started with Terra API.
```

--------------------------------

### Clone the Unified API example app

Source: https://docs.tryterra.co/developer-tools/example-apps

Download the Unified API example into a new 'my-app' directory. Replace 'unified-api-web-app' with another example name to download a different app. The destination must not exist yet and must be inside an existing parent directory. Downloading requires a network connection but no Terra login or Git.

```bash
terra examples clone unified-api-web-app my-app
```

--------------------------------

### Flutter: Start streaming to Terra's server with startRealtimeToServer

Source: https://docs.tryterra.co/streaming-api/your-app-greater-than-terra/flutter

Use `startRealtimeToServer` to stream data to Terra's websocket server instead of a local callback. Requires a streaming token generated by your backend. The example shows getting the user ID, fetching the token, and starting streaming for heart rate and steps.

```dart
import 'package:terra_flutter_rt/terra_flutter_rt.dart';
import 'package:terra_flutter_rt/types.dart';

Future<void> startServerStreaming() async {
  // 1. Get the Terra user ID
  final userId = await TerraFlutterRt.getUserId();
  if (userId == null) return;

  // 2. Get a streaming token from your backend
  final token = await fetchStreamingTokenFromBackend(userId);

  // 3. Start streaming to Terra's server
  await TerraFlutterRt.startRealtimeToServer(
    Connection.ble,
    [DataType.heartRate, DataType.steps],
    token,
  );
}
```

--------------------------------

### Clone and run the lab-reports-web-app example

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-panel

Clones the example app and starts the development server. Requires Terra CLI and Node.js v20+. Demo mode needs no credentials; live data requires a Terra Dev ID and API key with Lab Reports enabled.

```bash
terra examples clone lab-reports-web-app my-app
cd my-app && npm install && npm run dev
```

--------------------------------

### GET /plannedWorkouts response example

Source: https://docs.tryterra.co/planned-workouts-api/overview

Example JSON response from GET /plannedWorkouts?user_id=X showing a provider-created workout (is_external: true) with planned_date, provider_workout_id, and workout details including step_blocks and intensity targets.

```json
{
  "planned_workout_id": null,
  "workout_id": null,
  "planned_date": "2026-07-15",
  "provider_workout_id": "3841172642",
  "is_external": true,
  "created_at": null,
  "last_updated_at": null,
  "athlete_metrics": null,
  "warnings": [],
  "workout": {
    "name": "threshold",
    "sport": "cycling",
    "estimated_duration_seconds": 3816,
    "estimated_tss": 65.4,
    "estimated_intensity_factor": 0.75,
    "step_blocks": [
      {
        "completion_condition": null,
        "steps": [
          {
            "intensity_type": "warmup",
            "completion_condition": { "type": "time", "value": 900 },
            "intensity_targets": [
              { "target_type": "heart_rate_max_percentage", "value_low": 40, "value_high": 50 }
            ],
            "notes": "Warm up"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Download and configure the streaming consumer web app

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-pulse

Clones the app, installs dependencies, and copies the environment template. Paste your Dev ID and API key into .env; they stay server-side, read only by the token server.

```bash
terra examples clone streaming-consumer-web-app my-app
cd my-app
npm install
cp .env.example .env
```

--------------------------------

### Install Terra Flutter package

Source: https://docs.tryterra.co/unified-api/mobile-only-sources/flutter

Install the Terra Flutter package using flutter pub get.

```bash
flutter pub get terra_flutter_bridge
```

--------------------------------

### List available Terra example apps

Source: https://docs.tryterra.co/developer-tools/example-apps

List the available example apps using the Terra CLI.

```bash
terra examples list
```

--------------------------------

### List and clone Terra example apps

Source: https://docs.tryterra.co/developer-tools/terra-cli/command-reference

Fetches the public catalog and clones an app into a new directory. Requires no Terra login or pre-selected environment. The destination's parent must exist and the destination itself must not already exist; defaults to the example name when the directory is omitted. Preserves published files and package names without needing Node.js or Git installed.

```bash
terra examples list
terra examples clone unified-api-web-app my-app
```

--------------------------------

### startExercise(forType:completion:)

Source: https://docs.tryterra.co/reference/streaming-api/reference/ios-swift

Starts an HKWorkoutSession, enabling enhanced sensor access.

```APIDOC
## startExercise(forType:completion:)

### Description
Starts an HKWorkoutSession, enabling enhanced sensor access.

### Method
Function

### Signature
```swift
func startExercise(forType workoutType: WorkoutTypes,
                   completion: @escaping (Bool, TerraWatchOSErrors?) -> Void)
```

### Parameters
- **workoutType** (WorkoutTypes) - Required - The type of workout to start.
- **completion** (closure) - Required - A closure that receives a Bool indicating success and an optional error.

```

--------------------------------

### Install @tryterra/graphs-react-native

Source: https://docs.tryterra.co/graphs/embedding

Install the React Native package for native graph rendering. No chart engine setup is required; react-native-svg is a peer dependency installed automatically. On Expo, run 'npx expo install react-native-svg' to match the SDK version.

```bash
npm install @tryterra/graphs-react-native
```

--------------------------------

### Producer setup and streaming start in ProducerController.ts

Source: https://docs.tryterra.co/developer-tools/example-apps/terra-grip

Shows the producer setup and streaming start sequence from ProducerController.ts. The reusable rt. token is fetched and passed to startStreaming to open the WebSocket connection. Production integrations typically mint a short-lived token per connection from their own backend.

```typescript
// setup(): initTerra → rt. token → initConnection → map reference_id
await sdk.initialize(devId, referenceId);
const token = await api.fetchSdkToken();
await sdk.registerDevice(token);
const userId = await sdk.getUserId();

// startStreaming(): pass the token to open the producer connection
const streamingToken = await api.fetchStreamingToken(userId);
await sdk.startStreaming(connectionType, STREAM_DATA_TYPES, streamingToken);
```

--------------------------------

### Cloud storage file path examples

Source: https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/cloud-storage-s3-gcp

Concrete examples of how data files are organized within the storage bucket folders.

```text
2022-03-16/auth/abc123-2026-03-12T14:30:00Z.json
2022-03-16/activity/abc123-2026-03-12T06:00:00Z.json
2022-03-16/sleep/abc123-2026-03-11T22:00:00Z.json
```

--------------------------------

### List environments and set default using Terra CLI

Source: https://docs.tryterra.co/health-and-fitness-api/integration-setup/understanding-terra-environments

Use this prompt with the Terra CLI to list your environments and set staging as the default. Requires installing the CLI via brew or npm, then logging in with terra login. Use terra docs ask --question for documentation queries and terra <command> --help for usage.

```text
List my Terra environments with how many users each has, and set staging as my default.

Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "<question>" for anything you need from the Terra docs, and terra <command> --help for usage.
```

--------------------------------

### Get analytics overview with curl

Source: https://docs.tryterra.co/vantage-api/monitoring

Use the GET /api/v1/overview endpoint to retrieve a summary of account activity for a time window (default: last 7 days). The since parameter sets the start time.

```bash
curl 'https://vantage.tryterra.co/api/v1/overview?since=2026-07-01T00:00:00Z' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'
```
Tokens:
Raw