canonical: https://jentic.com/apis/openwearables.io/openwearables

# Open Wearables API

Open Wearables API ingests and queries health data from wearable devices through a unified surface. Endpoints cover user management, OAuth provider connection flows for upstream wearable platforms (Fitbit, Whoop, Oura, etc.), timeseries data retrieval, and structured event feeds for workouts and sleep sessions. The API uses an X-Open-Wearables-API-Key header for authentication and provides a single integration point that abstracts vendor-specific OAuth flows and data shapes.

## For AI agents

Ingest, normalize, and query wearable device health data - heart rate timeseries, workouts, sleep, plus OAuth-based provider connections - across vendors.

## Scope

Does not handle medical-grade diagnostics, clinical EHR integration, or device firmware control - use for consumer wearable health data ingestion and querying only.

## Capabilities

- Create and list users in the Open Wearables tenant via `/api/v1/users`
- Retrieve a user's connected wearable provider list with `/api/v1/users/{user_id}/connections`
- Pull normalised timeseries health data (heart rate, steps, etc.) via `/api/v1/users/{user_id}/timeseries`
- Fetch a user's workout events with `/api/v1/users/{user_id}/events/workouts`
- Fetch a user's sleep sessions with `/api/v1/users/{user_id}/events/sleep`
- Initiate an OAuth authorization flow for a provider with `/api/v1/oauth/{provider}/authorize` and list supported providers via `/api/v1/oauth/providers`
- Trigger a backfill or fresh sync from a provider with POST `/api/v1/providers/{provider}/users/{user_id}/sync`

## Use cases

### Unified Wearable Data for Health Apps

Health and fitness apps that want to support multiple wearable brands without maintaining a separate Fitbit, Whoop, Oura, and Garmin integration each can use Open Wearables as a single backend. `/api/v1/oauth/{provider}/authorize` starts the per-vendor OAuth flow and stores the resulting tokens, then `/api/v1/users/{user_id}/timeseries` returns normalised heart rate, steps, and similar metrics. The app code talks to one schema regardless of the underlying device.

Example prompt: POST `/api/v1/users` to create a user, redirect to `/api/v1/oauth/fitbit/authorize`, then GET `/api/v1/users/{user_id}/timeseries` for the heart_rate metric

### Workout Feed for Coaching Platforms

Personal training and coaching platforms can pull each athlete's workout history via `/api/v1/users/{user_id}/events/workouts.` The response is normalised across providers so a Whoop strain workout and a Garmin run share the same field structure (start_at, duration, distance, calories). This avoids per-vendor parsing in the coaching app and keeps the coach's dashboard consistent.

Example prompt: GET `/api/v1/users/{user_id}/events/workouts`?start=2026-06-01&end=2026-06-11 and aggregate total distance and duration

### Sleep Tracking Integration

Sleep research and wellness apps can call `/api/v1/users/{user_id}/events/sleep` for nightly sleep sessions including duration, stages, and quality scores when the upstream provider exposes them. `/api/v1/providers/{provider}/users/{user_id}/sync` can be used to force a backfill if a study participant's data is stale, ensuring research timelines aren't blocked by sync gaps.

Example prompt: GET `/api/v1/users/{user_id}/events/sleep` for the last 30 nights and compute average total sleep time

### AI Agent Health Coach

An AI agent acting as a health coach can use Open Wearables through Jentic to fetch a user's recent timeseries, workouts, and sleep without integrating each wearable vendor directly. Jentic supplies the X-Open-Wearables-API-Key from the vault and resolves the agent's intent ('how did I sleep last night') into the right `/events/sleep` call.

Example prompt: Through Jentic, search 'get user sleep sessions', resolve to GET `/api/v1/users/{user_id}/events/sleep`, and execute for the past 7 days

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/users` | Create a user in the Open Wearables tenant |
| GET | `/api/v1/users/{user_id}/connections` | List a user's wearable provider connections |
| GET | `/api/v1/users/{user_id}/timeseries` | Get normalised health metric timeseries |
| GET | `/api/v1/users/{user_id}/events/workouts` | List a user's workout events |
| GET | `/api/v1/users/{user_id}/events/sleep` | List a user's sleep sessions |
| GET | `/api/v1/oauth/providers` | List supported wearable providers |
| GET | `/api/v1/oauth/{provider}/authorize` | Start an OAuth flow for a provider |
| POST | `/api/v1/providers/{provider}/users/{user_id}/sync` | Trigger a fresh sync from a provider |

## Key resources

- **Users** — Create users, list users, and fetch a user's record.
- **Connections** — Inspect which wearable providers a user has linked.
- **Timeseries** — Normalised health metric timeseries (heart rate, steps, etc.) per user.
- **Workouts** — Structured workout events per user across providers.
- **Sleep** — Sleep sessions per user including stages where supported.
- **OAuth** — List supported providers and initiate per-vendor authorization flows.
- **Providers Sync** — Force a fresh sync of a user's data from a specific provider.

## Why Jentic

- **Setup:** Wiring the Open Wearables API by hand means sending the X-Open-Wearables-API-Key header on every call and driving the per-provider OAuth connect and sync flow before any timeseries is available. Through Jentic you install once, import the Open Wearables API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Open Wearables puts the user id in the URL path (`/api/v1/users/{user_id}/...`), so a rule can pin your agent to one user: it can read that user's timeseries, workouts, and sleep and nothing else. You choose the operations it may call, so actions like triggering a provider sync are not included unless you add them.
- **Credential handling:** Your X-Open-Wearables-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get user heart rate timeseries' or 'list a user's workouts', and Jentic returns the matching Open Wearables operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Fitbit Web API** — Direct Fitbit API for full vendor-specific data; Open Wearables abstracts Fitbit and other providers behind one schema.
- **Strava API** — Strava's API focuses on activities and social fitness; Open Wearables ingests broader health metrics.
- **Openverse API (Creative Commons Catalog)** — Different domain, but useful when a wearable-data app needs free-licence imagery for content cards.

## FAQ

### What authentication does the Open Wearables API use?

Open Wearables uses an API key passed in the X-Open-Wearables-API-Key header. Through Jentic the key is stored encrypted in the vault and injected at request time, so the raw value never enters the agent's prompt or logs.

### Can I pull heart rate data for a specific time window with the Open Wearables API?

Yes - GET `/api/v1/users/{user_id}/timeseries` accepts metric, start, and end query parameters. Specify metric=heart_rate and the desired window to get back normalised samples regardless of which upstream provider supplied the raw data.

### What are the rate limits for the Open Wearables API?

Open Wearables enforces tenant-level rate limits documented at docs.openwearables.io. Limits scale with plan; bulk syncs should use POST `/api/v1/providers/{provider}/users/{user_id}/sync` rather than tight polling on /timeseries to stay within the budget.

### How do I connect a user's Fitbit through Jentic?

Search Jentic for 'connect a wearable provider', load the GET `/api/v1/oauth/{provider}/authorize` schema, and execute with provider=fitbit and the user_id. Jentic returns the redirect URL the user follows to complete the upstream OAuth handshake.

### Which wearable brands does the Open Wearables API support?

Call GET `/api/v1/oauth/providers` for the live list. Open Wearables typically supports Fitbit, Whoop, Oura, Garmin, and similar consumer wearables; the providers endpoint is the source of truth because the list evolves.

### How do I trigger a backfill of a user's data from their wearable?

POST `/api/v1/providers/{provider}/users/{user_id}/sync` forces a fresh pull from the upstream provider for that user. Useful when a study or coaching window requires complete historical data rather than the default ongoing sync.

### Can I limit what my agent is allowed to do with the Open Wearables API?

Yes. Because you run Jentic One yourself, your own rules decide which Open Wearables operations and credentials the agent may use. Since the user id lives in the URL path (`/api/v1/users/{user_id}/...`), a rule can pin the agent to a single user and let it only read that user's timeseries, workouts, and sleep. You pick the operations it may call, so a write action like POST `/api/v1/providers/{provider}/users/{user_id}/sync` stays off limits unless you add it.