Quickstart: Garmin Sync with Progress Tracking

This guide provides a quick overview of how to use the simplified Garmin sync functionality with progress tracking.

1. Initiate a Synchronization

To start a synchronization for activities, workouts, or health metrics, send a POST request to the respective endpoint. The system will only allow one sync to run at a time.

Sync Activities

curl -X POST "http://localhost:8000/api/v1/garmin/activities" \
     -H "accept: application/json"

Sync Workouts

curl -X POST "http://localhost:8000/api/v1/garmin/workouts" \
     -H "accept: application/json"

Sync Health Metrics

curl -X POST "http://localhost:8000/api/v1/garmin/health" \
     -H "accept: application/json"

Expected Response (Success):

{
  "message": "Activity synchronization initiated successfully."
}

Expected Response (Conflict - if another sync is in progress):

{
  "detail": "A synchronization is already in progress. Please wait or check status."
}

2. Poll for Sync Status

To check the current status and progress of the active synchronization job, send a GET request to the status endpoint. This endpoint will always return the status of the single active sync.

curl -X GET "http://localhost:8000/api/v1/garmin/sync/status" \
     -H "accept: application/json"

Expected Response (Sync in Progress):

{
  "status": "in_progress",
  "progress": 0.5,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": null,
  "error_message": null,
  "job_type": "activities"
}

Expected Response (Sync Completed):

{
  "status": "completed",
  "progress": 1.0,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": "2025-10-11T10:15:00Z",
  "error_message": null,
  "job_type": "activities"
}

Expected Response (Sync Failed):

{
  "status": "failed",
  "progress": 0.75,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": "2025-10-11T10:10:00Z",
  "error_message": "Failed to connect to Garmin API.",
  "job_type": "activities"
}

Expected Response (No Sync Active):

{
  "status": "idle",
  "progress": 0.0,
  "start_time": "1970-01-01T00:00:00Z",
  "end_time": null,
  "error_message": null,
  "job_type": null
}

3. Handling Concurrent Sync Attempts

If you attempt to initiate a new sync while another is already in progress, the system will return a 409 Conflict status code with an informative message. You must wait for the current sync to complete or fail before starting a new one.

2.5 KiB Raw Blame History