Devices — API Reference

GET /users/{user_id}/devices List devices

Returns all devices connected to a user.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID

Example Request

bash

curl -X GET \
  "https://api.sonarhealth.co/v1/users/:user_id/devices" \
  -H "Authorization: Bearer $TOKEN"

Response 200 Device list

json

{
  "data": [
    {
      "id": "dev_001",
      "provider": "apple_health",
      "status": "active",
      "connected_at": "2025-01-01T10:00:00Z",
      "last_sync_at": "2025-01-20T08:30:00Z"
    },
    {
      "id": "dev_002",
      "provider": "garmin",
      "status": "active",
      "connected_at": "2025-01-10T14:00:00Z",
      "last_sync_at": "2025-01-20T07:45:00Z"
    }
  ]
}

POST /users/{user_id}/devices Connect a device (Cloud API)

Initiates a Cloud API device connection. Returns an OAuth URL for the user to authorize. For on-device sources (Apple Health, Health Connect), use the Mobile SDK instead.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID

Example Request

bash

curl -X POST \
  "https://api.sonarhealth.co/v1/users/:user_id/devices" \
  -H "Authorization: Bearer $TOKEN"

Response 200 Connection initiated — redirect user to auth_url

json

{
  "data": {
    "id": "dev_003",
    "provider": "garmin",
    "status": "pending",
    "auth_url": "https://connect.garmin.com/oauthConfirm?oauth_token=..."
  }
}

DELETE /users/{user_id}/devices/{device_id} Disconnect a device

Disconnects a device, de-authorizes with the provider, and stops syncing. Historical data is removed.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID
`device_id`	path	`string`	required	Device ID

Example Request

bash

curl -X DELETE \
  "https://api.sonarhealth.co/v1/users/:user_id/devices/:device_id" \
  -H "Authorization: Bearer $TOKEN"