Wearables API reference

Every cloud wearables route, in full. Examples use the sandbox host, https://api.sandbox.ovok.com.

RoutesCopy Anchor Link

ConventionsCopy Anchor Link

Authentication. Admin and patient routes take a bearer token: Authorization: Bearer <access token>. The project, and for patient routes the Patient, come from the token; no route takes a project or patient parameter. The OAuth callback and the webhooks take no token.

export OVOK_TOKEN='<access token>'

:provider is one of oura, whoop, strava, withings, polar, suunto, garmin, ultrahuman. Any other value answers 422 VALIDATION_FAILED.

Errors are Problem Details (application/problem+json). Branch on type and status, never on detail, and keep traceId when you report a problem:

{
  "type": "https://docs.ovok.com/errors/provider-not-available",
  "status": 404,
  "detail": "oura is not set up or not enabled for this project.",
  "instance": "/v1/wearables/connections/oura/authorize",
  "traceId": "877c7c38-e426-4c3d-bac0-0c4725a9df73",
  "errors": []
}

Secrets (secret, subscriptionKey, webhookSecret, provider tokens) are encrypted before they are stored and never returned by any route. No wearables route sends email.

Provider setupCopy Anchor Link

These routes manage the project's OAuth app at each provider. The caller needs a project admin token, and must also be a Practitioner, an admin, or hold the System Owner access policy. Reading is admin-only too, because the answer names the project's client IDs. Every write is logged with the acting user, the project and the provider.

The provider objectCopy Anchor Link

GET, POST and PATCH answer with this object; GET /v1/wearables/providers with a list of them.

List providersCopy Anchor Link

GET /v1/wearables/providers

Returns every supported provider, set up or not, always in this order: oura, whoop, strava, withings, polar, suunto, garmin, ultrahuman. Use it to find the callback URL to register and to check webhookReady.

Auth: project admin. Parameters: none.

curl --request GET \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

200, shortened to three of the eight entries:

{
  "providers": [
    {
      "provider": "oura",
      "configured": true,
      "enabled": true,
      "clientId": "<client id>",
      "redirectUri": "https://api.sandbox.ovok.com/v1/wearables/oauth/oura/callback",
      "webhookUrl": null,
      "webhookReady": null
    },
    {
      "provider": "polar",
      "configured": true,
      "enabled": true,
      "clientId": "<client id>",
      "redirectUri": "https://api.sandbox.ovok.com/v1/wearables/oauth/polar/callback",
      "webhookUrl": "https://api.sandbox.ovok.com/v1/wearables/webhooks/<project id>/polar",
      "webhookReady": true
    },
    {
      "provider": "suunto",
      "configured": false,
      "enabled": false,
      "clientId": null,
      "redirectUri": "https://api.sandbox.ovok.com/v1/wearables/oauth/suunto/callback",
      "webhookUrl": null,
      "webhookReady": false
    }
  ]
}

Status codesCopy Anchor Link

Side effects: none.

Get a providerCopy Anchor Link

GET /v1/wearables/providers/:provider

Returns one provider object, set up or not.

Auth: project admin.

curl --request GET \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers/withings' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

200:

{
  "provider": "withings",
  "configured": true,
  "enabled": true,
  "clientId": "<client id>",
  "redirectUri": "https://api.sandbox.ovok.com/v1/wearables/oauth/withings/callback",
  "webhookUrl": "https://api.sandbox.ovok.com/v1/wearables/webhooks/<project id>/withings/<token>",
  "webhookReady": true
}

Status codesCopy Anchor Link

Side effects: none.

Set up a providerCopy Anchor Link

POST /v1/wearables/providers

Saves the project's OAuth app at a provider, so the project's patients can connect it. Register the app at the provider first, with the provider's redirectUri from List providers. Set up providers has a quickstart per provider.

Auth: project admin.

Unknown fields are refused.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"oura","clientId":"<client id>","secret":"<client secret>"}'

Suunto, with its subscription key and notification secret:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"suunto","clientId":"<client id>","secret":"<client secret>","subscriptionKey":"<subscription key>","webhookSecret":"<notification secret>"}'

201, with Location: /v1/wearables/providers/oura:

{
  "provider": "oura",
  "configured": true,
  "enabled": true,
  "clientId": "<client id>",
  "redirectUri": "https://api.sandbox.ovok.com/v1/wearables/oauth/oura/callback",
  "webhookUrl": null,
  "webhookReady": null
}

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: stores the encrypted credentials on the project and logs the change; for Withings, makes the webhook secret; for Polar, creates or updates the webhook at Polar. A failed Polar webhook setup never undoes the stored credentials.

Change a providerCopy Anchor Link

PATCH /v1/wearables/providers/:provider

Changes a provider already set up. Fields you leave out keep their value. Send at least one.

Auth: project admin.

curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers/oura' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"secret":"<new client secret>"}'

200 with the provider object after the change.

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: stores the encrypted credentials and logs the change; for Polar with enabled: true, updates the webhook at Polar.

Remove a providerCopy Anchor Link

DELETE /v1/wearables/providers/:provider

Removes the project's credentials. Patients can no longer connect the provider, and existing connections stop syncing; they stay listed until the patient disconnects.

Auth: project admin.

curl --request DELETE \
  --url 'https://api.sandbox.ovok.com/v1/wearables/providers/oura' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

204 with no body.

Status codesCopy Anchor Link

Side effects: deletes the stored credentials and logs the change; for Polar, deletes the client's webhook at Polar when it points at this project's webhookUrl. A failure at Polar never stops the removal. Patients' grants at the provider are not revoked.

Patient connectionsCopy Anchor Link

These routes act on the signed-in patient's own connections. Any session that is not a patient's answers 403 PATIENT_PROFILE_REQUIRED: an admin cannot connect, sync or disconnect on a patient's behalf.

List connectionsCopy Anchor Link

GET /v1/wearables/connections

Returns one entry per provider the project has enabled, plus any provider the patient is still connected to after the project disabled or removed it. Render your connect screen from it.

Auth: patient. Parameters: none.

curl --request GET \
  --url 'https://api.sandbox.ovok.com/v1/wearables/connections' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

200:

{
  "connections": [
    {
      "provider": "oura",
      "connection": {
        "connectedAt": "2026-10-21T09:00:00.000Z",
        "syncedThrough": "2026-10-22T08:00:00.000Z",
        "reconnectRequired": false
      }
    },
    { "provider": "withings", "connection": null }
  ]
}

Status codesCopy Anchor Link

Side effects: none.

Start a connectionCopy Anchor Link

POST /v1/wearables/connections/:provider/authorize

Returns the provider's consent page for the signed-in patient. Open it in the system browser or an auth session, never an embedded WebView. After consent the provider sends the browser to the OAuth callback, which ends at your patient app. Connect a patient walks through the flow.

Auth: patient. Body: none.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/connections/oura/authorize' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

200:

{
  "provider": "oura",
  "authorizationUrl": "https://cloud.ouraring.com/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…&scope=…"
}

authorizationUrl is valid for 10 minutes and one use; ask for a new one each time. The return address, from the project's PATIENT_APP_URL, is fixed when you call the route.

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: stores a one-time authorization for 10 minutes. Nothing is sent to the provider yet.

Sync a connectionCopy Anchor Link

POST /v1/wearables/connections/:provider/sync

Pulls the patient's latest data from the provider now and writes it as Observations, instead of waiting for the daily sync at 08:00 UTC. Sync and read the data describes the readings.

Auth: patient. Body: none.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/connections/oura/sync' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

200:

{ "provider": "oura", "created": 42, "syncedThrough": "2026-10-22T08:00:00.000Z" }

What is read: the last 30 days on the first sync, then from 2 days before syncedThrough, never further back than 30 days. At most one on-demand sync per connection every 15 minutes, counted from syncedThrough, so also just after the daily sync.

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: calls the provider's data API; refreshes and re-stores the access token when it expires within 5 minutes or the provider refuses it; creates or updates Observations; moves syncedThrough only after the writes. When the provider refuses the grant, marks the connection reconnectRequired.

DisconnectCopy Anchor Link

DELETE /v1/wearables/connections/:provider

Deletes the patient's connection. Its tokens are no longer readable through the API. Observations already written stay.

Auth: patient.

curl --request DELETE \
  --url 'https://api.sandbox.ovok.com/v1/wearables/connections/oura' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

204 with no body.

Per providerCopy Anchor Link

A failure at the provider never stops the disconnect.

Status codesCopy Anchor Link

Side effects: calls Withings or Polar as above; deletes the connection. Its resource history keeps earlier versions, with the tokens still encrypted.

OAuth callbackCopy Anchor Link

GET /v1/wearables/oauth/:provider/callback

Where the provider sends the patient's browser after consent. Register it as the app's redirect URL at the provider; never call it yourself.

Auth: none. The one-time state from Start a connection identifies the patient and project.

With a valid state, the answer is always 302 to <PATIENT_APP_URL>/wearables/<provider>?result=<result>:

HTTP/1.1 302 Found
Location: https://app.example.com/wearables/oura?result=connected

result is for display only; read List connections for the state of record.

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: spends the state; exchanges the code with the provider; stores the encrypted tokens and the provider's account id on the connection, replacing an earlier connection to the same provider; calls Withings or Polar as above.

WebhooksCopy Anchor Link

Withings, Polar and Suunto tell Ovok when a patient has new data. Use the provider's webhookUrl from List providers; never call these routes yourself.

Oura, WHOOP, Strava, Ultrahuman and Garmin send no notifications to Ovok.

Receive a notificationCopy Anchor Link

POST /v1/wearables/webhooks/:projectId/:provider, or POST /v1/wearables/webhooks/:projectId/:provider/:token for Withings

Takes a provider's new-data notification and queues a sync of each connection it names. It never writes data itself.

Auth: none. The provider's signature, or the URL token for Withings, is the proof. A call without a signature header, or without a token of the right shape, is refused before anything is looked up.

What Withings sends, for illustration only:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/wearables/webhooks/<project id>/withings/<token>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'userid=12345678&appli=44&startdate=1729551600&enddate=1729580400'

202:

{ "outcome": "queued" }

Per providerCopy Anchor Link

Status codesCopy Anchor Link

Side effects: queues one delayed sync per matching connection. A queued sync that finds the connection already syncing is queued once more, 30 seconds later. The notification itself writes no data.

Check a webhook URLCopy Anchor Link

HEAD /v1/wearables/webhooks/:projectId/:provider, or with /:token

Answers whether the project takes notifications from the provider, for providers that check a URL before using it (Withings does).

Auth: none. The token, when present, is not checked here.

curl --head 'https://api.sandbox.ovok.com/v1/wearables/webhooks/<project id>/suunto'

Status codesCopy Anchor Link

Side effects: none.