Oura Ring
Connect once with OAuth, then read the wearer's Oura Cloud data and optionally register webhook subscriptions on your HTTPS server.
Operational order
- Confirm the connection with the personal profile read (age, email, and profile fields when Oura exposes them).
- Morning check-in — daily readiness, daily sleep, and daily activity for a date window (start_date / end_date, YYYY-MM-DD).
- Deeper sleep — sleep period records when phase-level detail beats the daily sleep score.
- Heart rate — ISO start_datetime / end_datetime; keep windows to about one day; paginate with next_token.
- Context — workouts, wellness sessions, basic tags, and enhanced tags.
- Extended vitals — SpO2, stress, resilience, cardiovascular age, VO2 max when the ring and account support them.
- Device — ring configuration, battery samples, rest-mode periods, sleep timing recommendations.
Data model
- Daily summaries — readiness, sleep score, activity (steps, calories); one row per calendar day (activity days start 4 a.m. local).
- Sleep periods — granular nights with stages and heart rate during sleep.
- Heart rate / battery — dense time series; narrow datetime bounds.
- Tags & workouts — user labels and logged or auto-detected exercise.
- Webhooks — push {event_type, data_type, object_id, user_id} to a callback you host; fetch full rows with normal reads after each event.
Date and pagination
- Date lists use start_date / end_date (YYYY-MM-DD).
- Time series use start_datetime / end_datetime (ISO-8601).
- Pass next_token from the prior response to continue.
Webhooks (optional)
Registration needs a public HTTPS endpoint that answers Oura's GET verification (verification_token, challenge → JSON {"challenge": "…"}) and accepts POST events. Subscription management is app-scoped on Oura's side; data reads use the wearer's OAuth token. Subscriptions expire — renew before lapse. One subscription per (event_type, data_type) pair.
Gotchas
- Read-only health rows — the API does not create sleep or activity; the ring and Oura app ingest data.
- Empty date ranges — the wearer may have no history yet, or the ring has not synced; widen dates or ask them to sync the app.
- Interbeat interval — research scope on the OAuth app; omit unless granted.
- Webhook create — fails if the callback URL is unreachable or does not echo the challenge.
