Skip to main content
POST
/
{provider}
/
users
/
{user_id}
/
sync
Sync Data
curl --request POST \
  --url https://api.example.com/{provider}/users/{user_id}/sync
{
  "success": true,
  "async": true,
  "task_id": "<string>",
  "message": "<string>",
  "details": {}
}

​
Overview

Triggers data synchronization from a wearable provider (Garmin, Strava, Polar, Suunto, Whoop) for a user. Supports both asynchronous (recommended) and synchronous execution modes.
Provider-Specific Behavior:
  • Garmin: Data arrives primarily via webhooks. This endpoint triggers a 30-day backfill.
  • Polar: Supports workouts only (no 24/7 data).
  • Suunto: Supports both workouts and 24/7 data with full pagination.
  • Whoop: Supports workouts and 24/7 data (sleep/recovery).
  • Strava: Activities are synced via webhooks.

​
Authentication

Requires a valid API key in the X-API-Key header.

​
Path Parameters

​
provider
string
required
Data provider name: garmin, strava, polar, suunto, or whoop
​
user_id
string
required
UUID of the user to sync data for

​
Query Parameters

​
General Parameters

​
data_type
string
default:"all"
Type of data to sync:
  • workouts: Activities/exercises only
  • 247: 24/7 data (sleep, recovery, activity samples)
  • all: All available data types
​
async
boolean
default:"true"
Run sync asynchronously via Celery worker. Set to false for synchronous execution (may timeout for large datasets).

​
Suunto-Specific Parameters

​
since
integer
default:"0"
Unix timestamp to synchronize data since. Use 0 for all available data.
​
limit
integer
default:"50"
Maximum number of items per request (max 100)
​
offset
integer
default:"0"
Pagination offset
​
filter_by_modification_time
boolean
default:"true"
Filter by modification time instead of creation time

​
Polar-Specific Parameters

​
samples
boolean
default:"false"
Include sample data (heart rate, speed, etc.)
​
zones
boolean
default:"false"
Include heart rate zones data
​
route
boolean
default:"false"
Include GPS route data

​
Garmin-Specific Parameters

​
summary_start_time
string
Activity start time as Unix timestamp or ISO 8601 date
​
summary_end_time
string
Activity end time as Unix timestamp or ISO 8601 date

​
Response (Async Mode)

When async=true (default), returns immediately with task information.
​
success
boolean
Always true when task is queued successfully
​
async
boolean
Indicates async mode is active (always true in this mode)
​
task_id
string
Celery task ID for tracking sync progress
​
message
string
Human-readable status message

​
Response (Sync Mode)

When async=false, waits for completion and returns detailed results.
​
success
boolean
true if all data types synced successfully
​
details
object
Per-data-type sync results:
  • workouts: Result of workout sync
  • data_247: Result of 24/7 data sync

​
Example Requests

curl -X POST "https://api.openwearables.com/api/v1/garmin/users/550e8400-e29b-41d4-a716-446655440000/sync?data_type=all&async=true" \
  -H "X-API-Key: your_api_key_here"

​
Example Responses

200 - Async Mode (Success)
{
  "success": true,
  "async": true,
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Sync task queued for garmin. Check task status for results."
}
200 - Sync Mode (Success)
{
  "success": true,
  "details": {
    "workouts": true,
    "data_247": true
  }
}
200 - Sync Mode (Partial Success)
{
  "success": false,
  "details": {
    "workouts": true,
    "data_247": false
  }
}
401 - Unauthorized
{
  "detail": "Invalid or missing API key"
}
404 - Connection Not Found
{
  "detail": "No active connection found for provider"
}
501 - Not Implemented
{
  "detail": "Provider 'polar' does not support 247 data (sleep/recovery/activity)"
}

​
Data Type Support by Provider

ProviderWorkouts24/7 DataNotes
Garmin✓✓Webhook-based, 30-day backfill
Strava✓✗Webhook-based
Polar✓✗Exercises only
Suunto✓✓Full pagination support
Whoop✓✓Sleep and recovery included

​
Async vs Sync Mode

  • Returns immediately with task ID
  • Prevents timeout errors on large datasets
  • Allows parallel processing of multiple users
  • Check task status using Celery task ID

​
Sync Mode

  • Waits for completion before returning
  • Risk of timeout for large date ranges
  • Useful for testing and small data requests
  • Returns detailed success/failure per data type

​
Error Handling

The endpoint returns HTTP 200 even for partial failures in sync mode. Check the success field and details object to determine if all data types synced successfully. For async mode, errors are logged in the Celery task. Use task monitoring tools to track failures.

​
Rate Limits

Provider API rate limits apply:
  • Garmin: Webhook-based, no direct API limits
  • Strava: 100 requests per 15 minutes, 1000 per day
  • Polar: No documented limits
  • Suunto: 100 requests per 15 minutes
  • Whoop: No documented limits

Build docs developers (and LLMs) love

Get started for freeTalk to us