From 5eb7ca3a6cabce02c4d92dcd9679f32ed582fc73 Mon Sep 17 00:00:00 2001 From: Maximilian Matthews Date: Thu, 16 Jul 2026 11:52:04 +0100 Subject: [PATCH 1/3] refactor: rename the terra-api skill to terra-unified-api The skill covers the unified Health & Fitness API, and the old name collided with the terra-api npm SDK package. Updates the directory, frontmatter name, and every cross-reference in the catalog, plugin manifest, and sibling skills. Mentions of the terra-api SDK package in rule examples are left as-is. --- .claude-plugin/marketplace.json | 2 +- AGENTS.md | 2 +- CLAUDE.md | 2 +- README.md | 6 +++--- package.json | 2 +- skills.sh.json | 2 +- skills/terra-mobile-sdk/README.md | 2 +- skills/terra-mobile-sdk/SKILL.md | 2 +- skills/{terra-api => terra-unified-api}/README.md | 8 ++++---- skills/{terra-api => terra-unified-api}/SKILL.md | 2 +- skills/{terra-api => terra-unified-api}/metadata.json | 0 .../{terra-api => terra-unified-api}/rules/_sections.md | 0 .../{terra-api => terra-unified-api}/rules/_template.md | 0 .../rules/auth-handle-all-events.md | 0 .../rules/auth-integrations-endpoint-headers.md | 0 .../rules/auth-parse-scopes.md | 0 .../rules/auth-reauth-id-swap.md | 0 .../rules/auth-reconcile-connections.md | 0 .../rules/auth-reference-id.md | 0 .../rules/data-coalesce-enrichment-scores.md | 0 .../rules/data-columns-over-blobs.md | 0 .../rules/data-date-part-only.md | 0 .../rules/data-natural-keys.md | 0 .../rules/data-superset-overwrite.md | 0 .../rules/data-timestamp-localization.md | 0 .../rules/devices-enrichment-provider-agnostic.md | 0 .../rules/devices-expect-cross-device-duplicates.md | 0 .../rules/testing-cover-event-edge-cases.md | 0 .../rules/testing-mock-boundaries.md | 0 .../rules/webhooks-ack-within-timeout.md | 0 .../rules/webhooks-archive-raw-payloads.md | 0 .../rules/webhooks-dedupe-terra-reference.md | 0 .../rules/webhooks-handle-informational-events.md | 0 .../rules/webhooks-verify-raw-body.md | 0 34 files changed, 15 insertions(+), 15 deletions(-) rename skills/{terra-api => terra-unified-api}/README.md (92%) rename skills/{terra-api => terra-unified-api}/SKILL.md (99%) rename skills/{terra-api => terra-unified-api}/metadata.json (100%) rename skills/{terra-api => terra-unified-api}/rules/_sections.md (100%) rename skills/{terra-api => terra-unified-api}/rules/_template.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-handle-all-events.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-integrations-endpoint-headers.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-parse-scopes.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-reauth-id-swap.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-reconcile-connections.md (100%) rename skills/{terra-api => terra-unified-api}/rules/auth-reference-id.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-coalesce-enrichment-scores.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-columns-over-blobs.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-date-part-only.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-natural-keys.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-superset-overwrite.md (100%) rename skills/{terra-api => terra-unified-api}/rules/data-timestamp-localization.md (100%) rename skills/{terra-api => terra-unified-api}/rules/devices-enrichment-provider-agnostic.md (100%) rename skills/{terra-api => terra-unified-api}/rules/devices-expect-cross-device-duplicates.md (100%) rename skills/{terra-api => terra-unified-api}/rules/testing-cover-event-edge-cases.md (100%) rename skills/{terra-api => terra-unified-api}/rules/testing-mock-boundaries.md (100%) rename skills/{terra-api => terra-unified-api}/rules/webhooks-ack-within-timeout.md (100%) rename skills/{terra-api => terra-unified-api}/rules/webhooks-archive-raw-payloads.md (100%) rename skills/{terra-api => terra-unified-api}/rules/webhooks-dedupe-terra-reference.md (100%) rename skills/{terra-api => terra-unified-api}/rules/webhooks-handle-informational-events.md (100%) rename skills/{terra-api => terra-unified-api}/rules/webhooks-verify-raw-body.md (100%) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index bb110a6..d157edf 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,7 +15,7 @@ "source": "./", "strict": false, "skills": [ - "./skills/terra-api", + "./skills/terra-unified-api", "./skills/terra-mobile-sdk", "./skills/terra-streaming", "./skills/terra-planned-workouts", diff --git a/AGENTS.md b/AGENTS.md index e2a4b54..5703182 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,7 @@ Rules: - Good: `Read references/webhooks.md when implementing the webhook endpoint or debugging signature failures.` - Bad: `See references/ for more details.` - Keep references one level deep from SKILL.md – no chains of files referencing files. -- Rules-based skills (like `terra-api`) use `rules/` instead of `references/`: SKILL.md is an index with a category priority table and a one-liner per rule; each rule lives in `rules/-.md` with frontmatter (title, impact, tags) and incorrect/correct code examples. `rules/_sections.md` defines the categories; copy `rules/_template.md` for new rules. +- Rules-based skills (like `terra-unified-api`) use `rules/` instead of `references/`: SKILL.md is an index with a category priority table and a one-liner per rule; each rule lives in `rules/-.md` with frontmatter (title, impact, tags) and incorrect/correct code examples. `rules/_sections.md` defines the categories; copy `rules/_template.md` for new rules. - Scripts in `scripts/` should be self-contained, print status to stderr and machine-readable output to stdout, and fail with helpful error messages. - Source content from the live docs: append `.md` to any `docs.tryterra.co` URL for markdown, or start from the index at `docs.tryterra.co/llms.txt`. Cite the source URL at the top of each reference file so it can be refreshed later. diff --git a/CLAUDE.md b/CLAUDE.md index 369ae57..e6710e0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ Rules: - Good: `Read references/webhooks.md when implementing the webhook endpoint or debugging signature failures.` - Bad: `See references/ for more details.` - Keep references one level deep from SKILL.md – no chains of files referencing files. -- Rules-based skills (like `terra-api`) use `rules/` instead of `references/`: SKILL.md is an index with a category priority table and a one-liner per rule; each rule lives in `rules/-.md` with frontmatter (title, impact, tags) and incorrect/correct code examples. `rules/_sections.md` defines the categories; copy `rules/_template.md` for new rules. +- Rules-based skills (like `terra-unified-api`) use `rules/` instead of `references/`: SKILL.md is an index with a category priority table and a one-liner per rule; each rule lives in `rules/-.md` with frontmatter (title, impact, tags) and incorrect/correct code examples. `rules/_sections.md` defines the categories; copy `rules/_template.md` for new rules. - Scripts in `scripts/` should be self-contained, print status to stderr and machine-readable output to stdout, and fail with helpful error messages. - Source content from the live docs: append `.md` to any `docs.tryterra.co` URL for markdown, or start from the index at `docs.tryterra.co/llms.txt`. Cite the source URL at the top of each reference file so it can be refreshed later. diff --git a/README.md b/README.md index 01e1983..dce716f 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ npx skills add tryterra/agent-skills Or a single skill: ```bash -npx skills add tryterra/agent-skills --skill terra-api +npx skills add tryterra/agent-skills --skill terra-unified-api ``` **Claude Code plugin** (alternative): @@ -28,14 +28,14 @@ npx skills add tryterra/agent-skills --skill terra-api **Manual** (Claude Code): ```bash -cp -r skills/terra-api ~/.claude/skills/ +cp -r skills/terra-unified-api ~/.claude/skills/ ``` ## Skills | Skill | Description | Status | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------- | -| [`terra-api`](skills/terra-api) | Best-practice rules: webhooks & signature verification, data idempotency, connection lifecycle, multi-device data, testing | ✅ Ready | +| [`terra-unified-api`](skills/terra-unified-api) | Best-practice rules: webhooks & signature verification, data idempotency, connection lifecycle, multi-device data, testing | ✅ Ready | | [`terra-mobile-sdk`](skills/terra-mobile-sdk) | Mobile SDK: Apple Health, Samsung Health, Health Connect (iOS, Android, React Native, Flutter) | ✅ Ready | | [`terra-streaming`](skills/terra-streaming) | Realtime streaming: websockets, Real-Time SDK, live sensor data (iOS, Android, React Native, Flutter, Wear OS) | ✅ Ready | | [`terra-planned-workouts`](skills/terra-planned-workouts) | Planned Workouts API: push structured workouts with intervals and targets to wearables | 🧪 Pre-release | diff --git a/package.json b/package.json index b9f2c8e..1dcb17a 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "url": "https://github.com/tryterra/agent-skills/issues" }, "keywords": [ - "terra-api", + "terra-unified-api", "agent-skills", "ai-agents", "claude-code", diff --git a/skills.sh.json b/skills.sh.json index af8e6fa..0ed161f 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -5,7 +5,7 @@ "title": "Terra API", "description": "Skills for integrating Terra API – the unified health & fitness data API.", "skills": [ - "terra-api", + "terra-unified-api", "terra-mobile-sdk", "terra-streaming", "terra-planned-workouts", diff --git a/skills/terra-mobile-sdk/README.md b/skills/terra-mobile-sdk/README.md index b4e1a55..57acdd7 100644 --- a/skills/terra-mobile-sdk/README.md +++ b/skills/terra-mobile-sdk/README.md @@ -2,7 +2,7 @@ Integration guidance for the [Terra API](https://tryterra.co) mobile SDK – the on-device path for health sources that have **no web API**: Apple Health (HealthKit), Samsung Health, and Health Connect. -Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api), covered by the `terra-api` skill. This skill is for the three sources you can only reach on-device. +Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api), covered by the `terra-unified-api` skill. This skill is for the three sources you can only reach on-device. `SKILL.md` carries the six-step workflow and every cross-platform gotcha inline; the `references/` files carry per-platform setup detail and code. diff --git a/skills/terra-mobile-sdk/SKILL.md b/skills/terra-mobile-sdk/SKILL.md index 2f5beec..862302e 100644 --- a/skills/terra-mobile-sdk/SKILL.md +++ b/skills/terra-mobile-sdk/SKILL.md @@ -22,7 +22,7 @@ The mobile SDK exists for one reason: to reach health sources that have **no web Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api), not the SDK. Google Fit can be read through the SDK via Health Connect, but the web API is the preferred, more reliable route for it. If a provider you need has a web API, use the web API. -Data captured by the SDK flows to the same Data Destination (webhook) as web API data, and connections are managed with the same auth model. If you are building the receiving webhook or storing the health data, that is the `terra-api` skill's territory; this skill covers the on-device connection. +Data captured by the SDK flows to the same Data Destination (webhook) as web API data, and connections are managed with the same auth model. If you are building the receiving webhook or storing the health data, that is the `terra-unified-api` skill's territory; this skill covers the on-device connection. ## The six-step workflow diff --git a/skills/terra-api/README.md b/skills/terra-unified-api/README.md similarity index 92% rename from skills/terra-api/README.md rename to skills/terra-unified-api/README.md index d1cc8f6..17bc828 100644 --- a/skills/terra-api/README.md +++ b/skills/terra-unified-api/README.md @@ -1,4 +1,4 @@ -# terra-api +# terra-unified-api Best practices for integrating [Terra API](https://tryterra.co) – the unified health & fitness data API for 500+ wearables and health data sources. @@ -7,13 +7,13 @@ Rules across 5 categories, distilled from a production multi-device integration. ## Installation ```bash -npx skills add tryterra/agent-skills --skill terra-api +npx skills add tryterra/agent-skills --skill terra-unified-api ``` Or manually for Claude Code: ```bash -cp -r skills/terra-api ~/.claude/skills/ +cp -r skills/terra-unified-api ~/.claude/skills/ ``` ## Categories @@ -38,7 +38,7 @@ cp -r skills/terra-api ~/.claude/skills/ ## Structure ``` -terra-api/ +terra-unified-api/ ├── SKILL.md # index: categories, priorities, quick reference └── rules/ ├── _sections.md diff --git a/skills/terra-api/SKILL.md b/skills/terra-unified-api/SKILL.md similarity index 99% rename from skills/terra-api/SKILL.md rename to skills/terra-unified-api/SKILL.md index de95a76..1c94c95 100644 --- a/skills/terra-api/SKILL.md +++ b/skills/terra-unified-api/SKILL.md @@ -1,5 +1,5 @@ --- -name: terra-api +name: terra-unified-api description: Best practices for integrating Terra API – the unified health & fitness data API for 500+ wearables (Garmin, Fitbit, Oura, Whoop, Apple Health, Strava, Dexcom). Use when building with Terra API or tryterra.co, handling terra-signature (X-Terra-Signature) webhooks, storing wearable health data (activity, sleep, daily, body, nutrition, menstruation, hormone), managing device connections, or merging data across multiple devices. license: MIT compatibility: Requires network access to docs.tryterra.co for full API schemas diff --git a/skills/terra-api/metadata.json b/skills/terra-unified-api/metadata.json similarity index 100% rename from skills/terra-api/metadata.json rename to skills/terra-unified-api/metadata.json diff --git a/skills/terra-api/rules/_sections.md b/skills/terra-unified-api/rules/_sections.md similarity index 100% rename from skills/terra-api/rules/_sections.md rename to skills/terra-unified-api/rules/_sections.md diff --git a/skills/terra-api/rules/_template.md b/skills/terra-unified-api/rules/_template.md similarity index 100% rename from skills/terra-api/rules/_template.md rename to skills/terra-unified-api/rules/_template.md diff --git a/skills/terra-api/rules/auth-handle-all-events.md b/skills/terra-unified-api/rules/auth-handle-all-events.md similarity index 100% rename from skills/terra-api/rules/auth-handle-all-events.md rename to skills/terra-unified-api/rules/auth-handle-all-events.md diff --git a/skills/terra-api/rules/auth-integrations-endpoint-headers.md b/skills/terra-unified-api/rules/auth-integrations-endpoint-headers.md similarity index 100% rename from skills/terra-api/rules/auth-integrations-endpoint-headers.md rename to skills/terra-unified-api/rules/auth-integrations-endpoint-headers.md diff --git a/skills/terra-api/rules/auth-parse-scopes.md b/skills/terra-unified-api/rules/auth-parse-scopes.md similarity index 100% rename from skills/terra-api/rules/auth-parse-scopes.md rename to skills/terra-unified-api/rules/auth-parse-scopes.md diff --git a/skills/terra-api/rules/auth-reauth-id-swap.md b/skills/terra-unified-api/rules/auth-reauth-id-swap.md similarity index 100% rename from skills/terra-api/rules/auth-reauth-id-swap.md rename to skills/terra-unified-api/rules/auth-reauth-id-swap.md diff --git a/skills/terra-api/rules/auth-reconcile-connections.md b/skills/terra-unified-api/rules/auth-reconcile-connections.md similarity index 100% rename from skills/terra-api/rules/auth-reconcile-connections.md rename to skills/terra-unified-api/rules/auth-reconcile-connections.md diff --git a/skills/terra-api/rules/auth-reference-id.md b/skills/terra-unified-api/rules/auth-reference-id.md similarity index 100% rename from skills/terra-api/rules/auth-reference-id.md rename to skills/terra-unified-api/rules/auth-reference-id.md diff --git a/skills/terra-api/rules/data-coalesce-enrichment-scores.md b/skills/terra-unified-api/rules/data-coalesce-enrichment-scores.md similarity index 100% rename from skills/terra-api/rules/data-coalesce-enrichment-scores.md rename to skills/terra-unified-api/rules/data-coalesce-enrichment-scores.md diff --git a/skills/terra-api/rules/data-columns-over-blobs.md b/skills/terra-unified-api/rules/data-columns-over-blobs.md similarity index 100% rename from skills/terra-api/rules/data-columns-over-blobs.md rename to skills/terra-unified-api/rules/data-columns-over-blobs.md diff --git a/skills/terra-api/rules/data-date-part-only.md b/skills/terra-unified-api/rules/data-date-part-only.md similarity index 100% rename from skills/terra-api/rules/data-date-part-only.md rename to skills/terra-unified-api/rules/data-date-part-only.md diff --git a/skills/terra-api/rules/data-natural-keys.md b/skills/terra-unified-api/rules/data-natural-keys.md similarity index 100% rename from skills/terra-api/rules/data-natural-keys.md rename to skills/terra-unified-api/rules/data-natural-keys.md diff --git a/skills/terra-api/rules/data-superset-overwrite.md b/skills/terra-unified-api/rules/data-superset-overwrite.md similarity index 100% rename from skills/terra-api/rules/data-superset-overwrite.md rename to skills/terra-unified-api/rules/data-superset-overwrite.md diff --git a/skills/terra-api/rules/data-timestamp-localization.md b/skills/terra-unified-api/rules/data-timestamp-localization.md similarity index 100% rename from skills/terra-api/rules/data-timestamp-localization.md rename to skills/terra-unified-api/rules/data-timestamp-localization.md diff --git a/skills/terra-api/rules/devices-enrichment-provider-agnostic.md b/skills/terra-unified-api/rules/devices-enrichment-provider-agnostic.md similarity index 100% rename from skills/terra-api/rules/devices-enrichment-provider-agnostic.md rename to skills/terra-unified-api/rules/devices-enrichment-provider-agnostic.md diff --git a/skills/terra-api/rules/devices-expect-cross-device-duplicates.md b/skills/terra-unified-api/rules/devices-expect-cross-device-duplicates.md similarity index 100% rename from skills/terra-api/rules/devices-expect-cross-device-duplicates.md rename to skills/terra-unified-api/rules/devices-expect-cross-device-duplicates.md diff --git a/skills/terra-api/rules/testing-cover-event-edge-cases.md b/skills/terra-unified-api/rules/testing-cover-event-edge-cases.md similarity index 100% rename from skills/terra-api/rules/testing-cover-event-edge-cases.md rename to skills/terra-unified-api/rules/testing-cover-event-edge-cases.md diff --git a/skills/terra-api/rules/testing-mock-boundaries.md b/skills/terra-unified-api/rules/testing-mock-boundaries.md similarity index 100% rename from skills/terra-api/rules/testing-mock-boundaries.md rename to skills/terra-unified-api/rules/testing-mock-boundaries.md diff --git a/skills/terra-api/rules/webhooks-ack-within-timeout.md b/skills/terra-unified-api/rules/webhooks-ack-within-timeout.md similarity index 100% rename from skills/terra-api/rules/webhooks-ack-within-timeout.md rename to skills/terra-unified-api/rules/webhooks-ack-within-timeout.md diff --git a/skills/terra-api/rules/webhooks-archive-raw-payloads.md b/skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md similarity index 100% rename from skills/terra-api/rules/webhooks-archive-raw-payloads.md rename to skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md diff --git a/skills/terra-api/rules/webhooks-dedupe-terra-reference.md b/skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md similarity index 100% rename from skills/terra-api/rules/webhooks-dedupe-terra-reference.md rename to skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md diff --git a/skills/terra-api/rules/webhooks-handle-informational-events.md b/skills/terra-unified-api/rules/webhooks-handle-informational-events.md similarity index 100% rename from skills/terra-api/rules/webhooks-handle-informational-events.md rename to skills/terra-unified-api/rules/webhooks-handle-informational-events.md diff --git a/skills/terra-api/rules/webhooks-verify-raw-body.md b/skills/terra-unified-api/rules/webhooks-verify-raw-body.md similarity index 100% rename from skills/terra-api/rules/webhooks-verify-raw-body.md rename to skills/terra-unified-api/rules/webhooks-verify-raw-body.md From fb9bc6e2ccd33900f5a41a718d87025d0d491c94 Mon Sep 17 00:00:00 2001 From: Maximilian Matthews Date: Thu, 16 Jul 2026 11:55:36 +0100 Subject: [PATCH 2/3] fix: point doc links at the renamed unified-api docs space The docs space moved from /health-and-fitness-api to /unified-api, which broke all 11 links check-links was flagging. Each path maps one-to-one onto the new prefix and was verified against the live docs. Links under /reference/health-and-fitness-api are a separate space that is still live and are left alone. --- skills/terra-mobile-sdk/README.md | 2 +- skills/terra-mobile-sdk/SKILL.md | 6 +++--- skills/terra-mobile-sdk/metadata.json | 10 +++++----- skills/terra-mobile-sdk/references/android.md | 6 +++--- skills/terra-mobile-sdk/references/flutter.md | 6 +++--- skills/terra-mobile-sdk/references/ios.md | 8 ++++---- skills/terra-mobile-sdk/references/react-native.md | 6 +++--- skills/terra-streaming/SKILL.md | 2 +- skills/terra-unified-api/metadata.json | 4 ++-- .../rules/auth-reconcile-connections.md | 2 +- skills/terra-unified-api/rules/auth-reference-id.md | 2 +- skills/terra-unified-api/rules/data-date-part-only.md | 2 +- skills/terra-unified-api/rules/data-natural-keys.md | 2 +- .../terra-unified-api/rules/data-superset-overwrite.md | 2 +- .../rules/webhooks-ack-within-timeout.md | 2 +- .../rules/webhooks-archive-raw-payloads.md | 2 +- .../rules/webhooks-dedupe-terra-reference.md | 2 +- .../rules/webhooks-verify-raw-body.md | 2 +- 18 files changed, 34 insertions(+), 34 deletions(-) diff --git a/skills/terra-mobile-sdk/README.md b/skills/terra-mobile-sdk/README.md index 57acdd7..86ab291 100644 --- a/skills/terra-mobile-sdk/README.md +++ b/skills/terra-mobile-sdk/README.md @@ -2,7 +2,7 @@ Integration guidance for the [Terra API](https://tryterra.co) mobile SDK – the on-device path for health sources that have **no web API**: Apple Health (HealthKit), Samsung Health, and Health Connect. -Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api), covered by the `terra-unified-api` skill. This skill is for the three sources you can only reach on-device. +Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/unified-api), covered by the `terra-unified-api` skill. This skill is for the three sources you can only reach on-device. `SKILL.md` carries the six-step workflow and every cross-platform gotcha inline; the `references/` files carry per-platform setup detail and code. diff --git a/skills/terra-mobile-sdk/SKILL.md b/skills/terra-mobile-sdk/SKILL.md index 862302e..c6b1143 100644 --- a/skills/terra-mobile-sdk/SKILL.md +++ b/skills/terra-mobile-sdk/SKILL.md @@ -20,7 +20,7 @@ The mobile SDK exists for one reason: to reach health sources that have **no web - **Samsung Health** (Android) - **Health Connect** (Android) -Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api), not the SDK. Google Fit can be read through the SDK via Health Connect, but the web API is the preferred, more reliable route for it. If a provider you need has a web API, use the web API. +Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/unified-api), not the SDK. Google Fit can be read through the SDK via Health Connect, but the web API is the preferred, more reliable route for it. If a provider you need has a web API, use the web API. Data captured by the SDK flows to the same Data Destination (webhook) as web API data, and connections are managed with the same auth model. If you are building the receiving webhook or storing the health data, that is the `terra-unified-api` skill's territory; this skill covers the on-device connection. @@ -35,7 +35,7 @@ The shape is identical on every platform. Platform differences are in the `refer 5. **Validate with `getUserId` on every re-initialization.** `getUserId` is synchronous and returns the `user_id` if the connection is live or `nil`/`null` if not. Call it right after every init; on `nil`, call `initConnection` again to reconnect. Re-connecting an already-connected user triggers no popup and does not interrupt the user. 6. **iOS only: enable background delivery.** Call `Terra.setUpBackgroundDelivery()` in your `AppDelegate`'s `didFinishLaunchingWithOptions`. Without it, Apple Health data is not pushed automatically. -**Deauthenticating** a user uses the same endpoint as web integrations: `DELETE /auth/deauthenticateUser`, called from your backend. See [the web API auth reference](https://docs.tryterra.co/health-and-fitness-api). +**Deauthenticating** a user uses the same endpoint as web integrations: `DELETE /auth/deauthenticateUser`, called from your backend. See [the web API auth reference](https://docs.tryterra.co/unified-api). ## Permission popup behavior (read before shipping) @@ -83,4 +83,4 @@ Read the file for the platform you are building on: - **`references/react-native.md`** – read when integrating **terra-react**: install, iOS + Android native setup, `initTerra`/`initConnection`, the AppDelegate background-delivery edit, `postActivity` (Apple Health only). - **`references/flutter.md`** – read when integrating **terra_flutter_bridge**: `flutter pub`, native setup, `TerraFlutter` API, AppDelegate background delivery, getters. -Full docs: [docs.tryterra.co](https://docs.tryterra.co) (append `.md` to any docs URL for a markdown version). Where a signature or enum is not shown here, see the SDK reference linked from [docs.tryterra.co](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources). If the terra-docs MCP server (`https://docs.tryterra.co/~gitbook/mcp`) is connected, use its tools to search and fetch the docs instead. +Full docs: [docs.tryterra.co](https://docs.tryterra.co) (append `.md` to any docs URL for a markdown version). Where a signature or enum is not shown here, see the SDK reference linked from [docs.tryterra.co](https://docs.tryterra.co/unified-api/mobile-only-sources). If the terra-docs MCP server (`https://docs.tryterra.co/~gitbook/mcp`) is connected, use its tools to search and fetch the docs instead. diff --git a/skills/terra-mobile-sdk/metadata.json b/skills/terra-mobile-sdk/metadata.json index a742670..38b1426 100644 --- a/skills/terra-mobile-sdk/metadata.json +++ b/skills/terra-mobile-sdk/metadata.json @@ -4,10 +4,10 @@ "date": "July 2026", "abstract": "Integration guidance for the Terra API mobile SDK, the on-device path for health sources with no web API: Apple Health (HealthKit), Samsung Health, and Health Connect. Covers the install/init/token/connect/validate/background-delivery workflow, permission-popup behavior, and per-platform setup for TerraiOS, TerraAndroid, terra-react, and terra_flutter_bridge.", "references": [ - "https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources", - "https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift", - "https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/android-kotlin", - "https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/react-native", - "https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/flutter" + "https://docs.tryterra.co/unified-api/mobile-only-sources", + "https://docs.tryterra.co/unified-api/mobile-only-sources/ios-swift", + "https://docs.tryterra.co/unified-api/mobile-only-sources/android-kotlin", + "https://docs.tryterra.co/unified-api/mobile-only-sources/react-native", + "https://docs.tryterra.co/unified-api/mobile-only-sources/flutter" ] } diff --git a/skills/terra-mobile-sdk/references/android.md b/skills/terra-mobile-sdk/references/android.md index c56b918..763424a 100644 --- a/skills/terra-mobile-sdk/references/android.md +++ b/skills/terra-mobile-sdk/references/android.md @@ -1,6 +1,6 @@ # Android (Kotlin) – TerraAndroid -Native Kotlin integration for **Samsung Health** and **Health Connect**. Source: [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/android-kotlin](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/android-kotlin). +Native Kotlin integration for **Samsung Health** and **Health Connect**. Source: [docs.tryterra.co/unified-api/mobile-only-sources/android-kotlin](https://docs.tryterra.co/unified-api/mobile-only-sources/android-kotlin). ## 1. Install @@ -106,7 +106,7 @@ fun initialiseUserConnection() { - `connection`: `Connections.SAMSUNG` (Samsung Health) or `Connections.HEALTH_CONNECT`. - `schedulerOn = true`: lets Terra API make scheduled requests while the app is in the foreground. - `startIntent`: **deprecated, always pass `null`**. -- `customPermissions`: maps to Health Connect / Samsung data types – see [Permissions mapping](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources). +- `customPermissions`: maps to Health Connect / Samsung data types – see [Permissions mapping](https://docs.tryterra.co/unified-api/mobile-only-sources). **Popup fires once.** Health Connect forbids the permission popup from appearing more than once per permission, so a second `initConnection` does nothing. It re-appears only if you expand `customPermissions`, the app is reinstalled, or you request a permission Google has not approved for release. @@ -146,4 +146,4 @@ fun requestData() { } ``` -Disconnect via the same backend endpoint as web integrations (`DELETE /auth/deauthenticateUser`). There is no iOS-style background-delivery setup on Android – foreground scheduled requests are controlled by `schedulerOn`. See the SDK reference on [docs.tryterra.co](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/android-kotlin) for the full function list. +Disconnect via the same backend endpoint as web integrations (`DELETE /auth/deauthenticateUser`). There is no iOS-style background-delivery setup on Android – foreground scheduled requests are controlled by `schedulerOn`. See the SDK reference on [docs.tryterra.co](https://docs.tryterra.co/unified-api/mobile-only-sources/android-kotlin) for the full function list. diff --git a/skills/terra-mobile-sdk/references/flutter.md b/skills/terra-mobile-sdk/references/flutter.md index 07c622e..fcd84b6 100644 --- a/skills/terra-mobile-sdk/references/flutter.md +++ b/skills/terra-mobile-sdk/references/flutter.md @@ -1,6 +1,6 @@ # Flutter – terra_flutter_bridge -Cross-platform integration for **Apple Health** (iOS), **Samsung Health**, and **Health Connect** (Android). Source: [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/flutter](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/flutter). +Cross-platform integration for **Apple Health** (iOS), **Samsung Health**, and **Health Connect** (Android). Source: [docs.tryterra.co/unified-api/mobile-only-sources/flutter](https://docs.tryterra.co/unified-api/mobile-only-sources/flutter). ## 1. Install and native setup @@ -78,7 +78,7 @@ Future _initialiseConnection() async { - `type`: `Connection.appleHealth`, `Connection.samsung`, or `Connection.healthConnect`. - `schedulerOn`: **no effect on iOS** (background delivery is via `setUpBackgroundDelivery`); on Android, `true` enables foreground scheduled requests. -- `customPermissions`: see [Permissions mapping](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources). +- `customPermissions`: see [Permissions mapping](https://docs.tryterra.co/unified-api/mobile-only-sources). Popup behavior: Apple Health and Health Connect show the popup once (re-triggers only on expanded `customPermissions`, reinstall, or – Health Connect – a permission Google has not approved). The HealthKit popup is a WebView; WebView-based apps must interrupt their WebView, call `initConnection`, then reopen. @@ -134,4 +134,4 @@ Future getData() async { } ``` -Set `toWebhook: false` to receive the payload in the response instead of pushing to your destination. Disconnect via the same backend endpoint as web integrations (`DELETE /auth/deauthenticateUser`). See the SDK reference on [docs.tryterra.co](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/flutter) for the full function list. +Set `toWebhook: false` to receive the payload in the response instead of pushing to your destination. Disconnect via the same backend endpoint as web integrations (`DELETE /auth/deauthenticateUser`). See the SDK reference on [docs.tryterra.co](https://docs.tryterra.co/unified-api/mobile-only-sources/flutter) for the full function list. diff --git a/skills/terra-mobile-sdk/references/ios.md b/skills/terra-mobile-sdk/references/ios.md index 5f1d777..565f94a 100644 --- a/skills/terra-mobile-sdk/references/ios.md +++ b/skills/terra-mobile-sdk/references/ios.md @@ -1,6 +1,6 @@ # iOS (Swift) – TerraiOS -Native Swift integration for **Apple Health**. Source: [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift). `TerraiOS` supports Apple Health only. +Native Swift integration for **Apple Health**. Source: [docs.tryterra.co/unified-api/mobile-only-sources/ios-swift](https://docs.tryterra.co/unified-api/mobile-only-sources/ios-swift). `TerraiOS` supports Apple Health only. ## 1. Install and add capabilities @@ -59,7 +59,7 @@ terra.initConnection( } ``` -`schedulerOn` has no effect on iOS; background delivery is controlled by `setUpBackgroundDelivery()`. `customReadTypes` maps to HealthKit types – see [Permissions mapping](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources). The popup fires once (re-triggers only on expanded `customPermissions` or reinstall), and it is a WebView (WebView-based apps must interrupt their WebView, call `initConnection`, then reopen). +`schedulerOn` has no effect on iOS; background delivery is controlled by `setUpBackgroundDelivery()`. `customReadTypes` maps to HealthKit types – see [Permissions mapping](https://docs.tryterra.co/unified-api/mobile-only-sources). The popup fires once (re-triggers only on expanded `customPermissions` or reinstall), and it is a WebView (WebView-based apps must interrupt their WebView, call `initConnection`, then reopen). ## 4. Validate with getUserId on every re-init @@ -178,7 +178,7 @@ let activityData = TerraActivityData( terra.postActivity(type: .APPLE_HEALTH, payload: activityData) { success, error in /* ... */ } ``` -`postBody` and `postNutrition` follow the same shape with `TerraBodyData` / `TerraNutritionData` payloads. Fetch [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift.md](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift.md) for the full payload field lists when building the request body. +`postBody` and `postNutrition` follow the same shape with `TerraBodyData` / `TerraNutritionData` payloads. Fetch [docs.tryterra.co/unified-api/mobile-only-sources/ios-swift.md](https://docs.tryterra.co/unified-api/mobile-only-sources/ios-swift.md) for the full payload field lists when building the request body. ## Planned workout sync (iOS 17+) @@ -188,4 +188,4 @@ Planned workouts are created via Terra API's REST API on your backend; the iOS S - `syncPlannedWorkoutsFromBackend(type:)` – manually trigger a sync of pending actions. - `isPlannedWorkoutBackendSyncEnabled` – current state. -Observe `.terraPlannedWorkoutSynced` and `.terraPlannedWorkoutSyncCompleted` via `NotificationCenter` for per-workout and completion events. See the SDK reference linked from [the iOS docs](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/ios-swift) for the event object shapes. +Observe `.terraPlannedWorkoutSynced` and `.terraPlannedWorkoutSyncCompleted` via `NotificationCenter` for per-workout and completion events. See the SDK reference linked from [the iOS docs](https://docs.tryterra.co/unified-api/mobile-only-sources/ios-swift) for the event object shapes. diff --git a/skills/terra-mobile-sdk/references/react-native.md b/skills/terra-mobile-sdk/references/react-native.md index 73972a7..4b11859 100644 --- a/skills/terra-mobile-sdk/references/react-native.md +++ b/skills/terra-mobile-sdk/references/react-native.md @@ -1,6 +1,6 @@ # React Native – terra-react -Cross-platform integration for **Apple Health** (iOS), **Samsung Health**, and **Health Connect** (Android). Source: [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/react-native](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/react-native). +Cross-platform integration for **Apple Health** (iOS), **Samsung Health**, and **Health Connect** (Android). Source: [docs.tryterra.co/unified-api/mobile-only-sources/react-native](https://docs.tryterra.co/unified-api/mobile-only-sources/react-native). ## 1. Install and native setup @@ -80,7 +80,7 @@ const initializeConnection = async () => { - `type`: `Connections.APPLE_HEALTH`, `Connections.SAMSUNG`, or `Connections.HEALTH_CONNECT`. - `schedulerOn`: **no effect on iOS** (background delivery is via `setUpBackgroundDelivery`); on Android, `true` enables foreground scheduled requests. -- `customPermissions`: see [Permissions mapping](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources). +- `customPermissions`: see [Permissions mapping](https://docs.tryterra.co/unified-api/mobile-only-sources). Popup behavior: Apple Health and Health Connect show the popup once (re-triggers only on expanded `customPermissions`, reinstall, or – Health Connect – a permission Google has not approved). The HealthKit popup is a WebView; WebView-based apps must interrupt their WebView, call `initConnection`, then reopen. @@ -163,4 +163,4 @@ const activityPayload: Activity = { const resp = await postActivity(Connections.APPLE_HEALTH, activityPayload); ``` -Fetch [docs.tryterra.co/health-and-fitness-api/mobile-only-sources/react-native.md](https://docs.tryterra.co/health-and-fitness-api/mobile-only-sources/react-native.md) for the full payload fields, function list, and `ActivityType` enum when building the request body. +Fetch [docs.tryterra.co/unified-api/mobile-only-sources/react-native.md](https://docs.tryterra.co/unified-api/mobile-only-sources/react-native.md) for the full payload fields, function list, and `ActivityType` enum when building the request body. diff --git a/skills/terra-streaming/SKILL.md b/skills/terra-streaming/SKILL.md index fe3f726..4a68f71 100644 --- a/skills/terra-streaming/SKILL.md +++ b/skills/terra-streaming/SKILL.md @@ -14,7 +14,7 @@ Guidelines for building on the Terra API Streaming (Real-Time) API, which delive ## Streaming vs Health & Fitness -The Streaming API is for realtime, sub-second-to-per-second signals only: heart rate, steps, distance covered, acceleration, ECG, HRV, calories, location, and gyroscope. Anything with a longer span – workouts, sleep, daily totals, body, nutrition – belongs to the [Health & Fitness API](https://docs.tryterra.co/health-and-fitness-api/getting-started), not here. If you need a completed workout summary rather than a live feed, you are on the wrong API. +The Streaming API is for realtime, sub-second-to-per-second signals only: heart rate, steps, distance covered, acceleration, ECG, HRV, calories, location, and gyroscope. Anything with a longer span – workouts, sleep, daily totals, body, nutrition – belongs to the [Health & Fitness API](https://docs.tryterra.co/unified-api/getting-started), not here. If you need a completed workout summary rather than a live feed, you are on the wrong API. Devices only appear on the stream when they actually broadcast over BLE, ANT+, or a supported custom Bluetooth protocol (heart-rate straps like the Polar H10 or Wahoo TICKR, and some watches). No broadcast means no stream. diff --git a/skills/terra-unified-api/metadata.json b/skills/terra-unified-api/metadata.json index 8ef5fbb..f6d5cdb 100644 --- a/skills/terra-unified-api/metadata.json +++ b/skills/terra-unified-api/metadata.json @@ -5,8 +5,8 @@ "abstract": "Production-tested best practices for integrating Terra API: webhook verification and idempotency, health data storage strategies, connection lifecycle handling, multi-device merging, and testing.", "references": [ "https://docs.tryterra.co", - "https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/webhooks", - "https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates", + "https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks", + "https://docs.tryterra.co/unified-api/managing-user-health-data/receiving-data-updates", "https://docs.tryterra.co/reference/health-and-fitness-api/event-types", "https://docs.tryterra.co/reference/health-and-fitness-api/data-models" ] diff --git a/skills/terra-unified-api/rules/auth-reconcile-connections.md b/skills/terra-unified-api/rules/auth-reconcile-connections.md index 0d9b866..d1d3dbb 100644 --- a/skills/terra-unified-api/rules/auth-reconcile-connections.md +++ b/skills/terra-unified-api/rules/auth-reconcile-connections.md @@ -43,4 +43,4 @@ async function syncTerraConnections(appUserId: string) { } ``` -Reference: [Getting started](https://docs.tryterra.co/health-and-fitness-api/getting-started) +Reference: [Getting started](https://docs.tryterra.co/unified-api/getting-started) diff --git a/skills/terra-unified-api/rules/auth-reference-id.md b/skills/terra-unified-api/rules/auth-reference-id.md index 2f4aa4a..2410760 100644 --- a/skills/terra-unified-api/rules/auth-reference-id.md +++ b/skills/terra-unified-api/rules/auth-reference-id.md @@ -33,4 +33,4 @@ const res = await client.authentication.authenticateuser({ // every webhook for this connection now carries reference_id = appUser.id ``` -Reference: [Getting started](https://docs.tryterra.co/health-and-fitness-api/getting-started) +Reference: [Getting started](https://docs.tryterra.co/unified-api/getting-started) diff --git a/skills/terra-unified-api/rules/data-date-part-only.md b/skills/terra-unified-api/rules/data-date-part-only.md index 7f1e274..0e7ab3c 100644 --- a/skills/terra-unified-api/rules/data-date-part-only.md +++ b/skills/terra-unified-api/rules/data-date-part-only.md @@ -33,4 +33,4 @@ CREATE TABLE terra_daily ( ); ``` -Reference: [Receiving data updates](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates) +Reference: [Receiving data updates](https://docs.tryterra.co/unified-api/managing-user-health-data/receiving-data-updates) diff --git a/skills/terra-unified-api/rules/data-natural-keys.md b/skills/terra-unified-api/rules/data-natural-keys.md index 3348e27..cb2c607 100644 --- a/skills/terra-unified-api/rules/data-natural-keys.md +++ b/skills/terra-unified-api/rules/data-natural-keys.md @@ -47,4 +47,4 @@ INSERT INTO terra_activity (summary_id, ...) VALUES (...) ON CONFLICT (summary_id) DO UPDATE SET ...; ``` -Reference: [Receiving data updates](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates) +Reference: [Receiving data updates](https://docs.tryterra.co/unified-api/managing-user-health-data/receiving-data-updates) diff --git a/skills/terra-unified-api/rules/data-superset-overwrite.md b/skills/terra-unified-api/rules/data-superset-overwrite.md index 93ce6d4..399bc4d 100644 --- a/skills/terra-unified-api/rules/data-superset-overwrite.md +++ b/skills/terra-unified-api/rules/data-superset-overwrite.md @@ -31,4 +31,4 @@ ON CONFLICT (terra_connection_id, date) DO UPDATE SET WHERE excluded.ordering_ts >= terra_daily.ordering_ts; -- reordered retries never regress data ``` -Reference: [Receiving data updates](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates) +Reference: [Receiving data updates](https://docs.tryterra.co/unified-api/managing-user-health-data/receiving-data-updates) diff --git a/skills/terra-unified-api/rules/webhooks-ack-within-timeout.md b/skills/terra-unified-api/rules/webhooks-ack-within-timeout.md index 3868954..c875da1 100644 --- a/skills/terra-unified-api/rules/webhooks-ack-within-timeout.md +++ b/skills/terra-unified-api/rules/webhooks-ack-within-timeout.md @@ -37,4 +37,4 @@ app.post("/api/terra/webhook", async (c) => { Mark the recorded event `processed` or `failed` when the background work finishes so failures are visible and replayable. -Reference: [Webhooks](https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/webhooks) +Reference: [Webhooks](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks) diff --git a/skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md b/skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md index 52da272..24efe4d 100644 --- a/skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md +++ b/skills/terra-unified-api/rules/webhooks-archive-raw-payloads.md @@ -34,4 +34,4 @@ async function processEvent( } ``` -Reference: [Webhooks](https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/webhooks) +Reference: [Webhooks](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks) diff --git a/skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md b/skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md index 53627d6..3fdc7e6 100644 --- a/skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md +++ b/skills/terra-unified-api/rules/webhooks-dedupe-terra-reference.md @@ -42,4 +42,4 @@ c.executionCtx.waitUntil(processEvent(inserted.rows[0].id, event)); return c.text("ok", 200); ``` -Reference: [Receiving data updates](https://docs.tryterra.co/health-and-fitness-api/managing-user-health-data/receiving-data-updates) +Reference: [Receiving data updates](https://docs.tryterra.co/unified-api/managing-user-health-data/receiving-data-updates) diff --git a/skills/terra-unified-api/rules/webhooks-verify-raw-body.md b/skills/terra-unified-api/rules/webhooks-verify-raw-body.md index 03946d8..4cbabf1 100644 --- a/skills/terra-unified-api/rules/webhooks-verify-raw-body.md +++ b/skills/terra-unified-api/rules/webhooks-verify-raw-body.md @@ -47,4 +47,4 @@ app.post("/api/terra/webhook", async (c) => { The `terra-api` SDK ships `verifyTerraWebhookSignature()`; prefer it over hand-rolled HMAC code. -Reference: [Webhooks](https://docs.tryterra.co/health-and-fitness-api/integration-setup/setting-up-data-destinations/webhooks) +Reference: [Webhooks](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks) From a14dc9c243971534c688dd658f313d49d95511ef Mon Sep 17 00:00:00 2001 From: Maximilian Matthews Date: Thu, 16 Jul 2026 11:57:16 +0100 Subject: [PATCH 3/3] docs: call the product Unified API in prose, matching the docs The docs renamed the product from Health & Fitness API to Unified API. Updates the five prose mentions across terra-unified-api, terra-mobile-sdk, and terra-streaming so link text matches its target. Frontmatter descriptions keep the lowercase 'unified health & fitness data API' descriptor, which carries search keywords. --- skills/terra-mobile-sdk/README.md | 2 +- skills/terra-mobile-sdk/SKILL.md | 2 +- skills/terra-streaming/README.md | 2 +- skills/terra-streaming/SKILL.md | 2 +- skills/terra-unified-api/SKILL.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/terra-mobile-sdk/README.md b/skills/terra-mobile-sdk/README.md index 86ab291..077cca4 100644 --- a/skills/terra-mobile-sdk/README.md +++ b/skills/terra-mobile-sdk/README.md @@ -2,7 +2,7 @@ Integration guidance for the [Terra API](https://tryterra.co) mobile SDK – the on-device path for health sources that have **no web API**: Apple Health (HealthKit), Samsung Health, and Health Connect. -Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/unified-api), covered by the `terra-unified-api` skill. This skill is for the three sources you can only reach on-device. +Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Unified API](https://docs.tryterra.co/unified-api), covered by the `terra-unified-api` skill. This skill is for the three sources you can only reach on-device. `SKILL.md` carries the six-step workflow and every cross-platform gotcha inline; the `references/` files carry per-platform setup detail and code. diff --git a/skills/terra-mobile-sdk/SKILL.md b/skills/terra-mobile-sdk/SKILL.md index c6b1143..f60c424 100644 --- a/skills/terra-mobile-sdk/SKILL.md +++ b/skills/terra-mobile-sdk/SKILL.md @@ -20,7 +20,7 @@ The mobile SDK exists for one reason: to reach health sources that have **no web - **Samsung Health** (Android) - **Health Connect** (Android) -Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Health & Fitness API](https://docs.tryterra.co/unified-api), not the SDK. Google Fit can be read through the SDK via Health Connect, but the web API is the preferred, more reliable route for it. If a provider you need has a web API, use the web API. +Every other provider (Garmin, Fitbit, Oura, Whoop, Strava, Dexcom, and 500+ more) connects through the [Unified API](https://docs.tryterra.co/unified-api), not the SDK. Google Fit can be read through the SDK via Health Connect, but the web API is the preferred, more reliable route for it. If a provider you need has a web API, use the web API. Data captured by the SDK flows to the same Data Destination (webhook) as web API data, and connections are managed with the same auth model. If you are building the receiving webhook or storing the health data, that is the `terra-unified-api` skill's territory; this skill covers the on-device connection. diff --git a/skills/terra-streaming/README.md b/skills/terra-streaming/README.md index 547fe22..6824e84 100644 --- a/skills/terra-streaming/README.md +++ b/skills/terra-streaming/README.md @@ -18,7 +18,7 @@ cp -r skills/terra-streaming ~/.claude/skills/ ## Highlights -- Streaming carries per-second signals only (heart rate, steps, distance, acceleration, ECG, HRV, calories, location, gyroscope); workouts, sleep, and daily totals belong to the Health & Fitness API +- Streaming carries per-second signals only (heart rate, steps, distance, acceleration, ECG, HRV, calories, location, gyroscope); workouts, sleep, and daily totals belong to the Unified API - One websocket endpoint for both roles; the IDENTIFY `type` (0 producer, 1 consumer) sets the role - **Every token is single-use** – the server deletes it after IDENTIFY, so each reconnect needs a fresh one - `seq` is monotonic but **sparse** – gaps are normal, not lost data diff --git a/skills/terra-streaming/SKILL.md b/skills/terra-streaming/SKILL.md index 4a68f71..1cbd306 100644 --- a/skills/terra-streaming/SKILL.md +++ b/skills/terra-streaming/SKILL.md @@ -14,7 +14,7 @@ Guidelines for building on the Terra API Streaming (Real-Time) API, which delive ## Streaming vs Health & Fitness -The Streaming API is for realtime, sub-second-to-per-second signals only: heart rate, steps, distance covered, acceleration, ECG, HRV, calories, location, and gyroscope. Anything with a longer span – workouts, sleep, daily totals, body, nutrition – belongs to the [Health & Fitness API](https://docs.tryterra.co/unified-api/getting-started), not here. If you need a completed workout summary rather than a live feed, you are on the wrong API. +The Streaming API is for realtime, sub-second-to-per-second signals only: heart rate, steps, distance covered, acceleration, ECG, HRV, calories, location, and gyroscope. Anything with a longer span – workouts, sleep, daily totals, body, nutrition – belongs to the [Unified API](https://docs.tryterra.co/unified-api/getting-started), not here. If you need a completed workout summary rather than a live feed, you are on the wrong API. Devices only appear on the stream when they actually broadcast over BLE, ANT+, or a supported custom Bluetooth protocol (heart-rate straps like the Polar H10 or Wahoo TICKR, and some watches). No broadcast means no stream. diff --git a/skills/terra-unified-api/SKILL.md b/skills/terra-unified-api/SKILL.md index 1c94c95..0ded738 100644 --- a/skills/terra-unified-api/SKILL.md +++ b/skills/terra-unified-api/SKILL.md @@ -76,4 +76,4 @@ Read the individual rule file in `rules/` when working on that area, e.g. read ` ## Related Terra API Surfaces -This skill covers the core Health & Fitness API integration. Terra API also offers mobile SDKs for on-device sources (Apple Health, Samsung Health, Health Connect), a realtime Streaming API over websockets, an MCP server exposing health-data query tools to AI agents, planned workouts and routes (write-to-device products), and lab reports. See [docs.tryterra.co](https://docs.tryterra.co) for those surfaces. +This skill covers the core Unified API integration. Terra API also offers mobile SDKs for on-device sources (Apple Health, Samsung Health, Health Connect), a realtime Streaming API over websockets, an MCP server exposing health-data query tools to AI agents, planned workouts and routes (write-to-device products), and lab reports. See [docs.tryterra.co](https://docs.tryterra.co) for those surfaces.