Keeping a local copy in sync
A client that keeps its own copy of a user's records (a mobile app that works offline) asks GET /sync what changed since it last asked, instead of downloading every list again. All paths are under /api/v1.
What it covers
type |
Records | Scope |
|---|---|---|
activity |
Activities, with private_notes, media and the thumbnail, as their owner reads them |
activities:read |
health_weight, health_steps, health_sleep, health_water, health_poop, health_fasting |
Health records; sleep carries its sleep_stages |
health:read |
health_targets |
The health targets | health-targets:read |
gear |
Gear, with its totals | gears:read |
gear_component |
Gear components | gears:read |
Every one of these records carries updated_at, when it last changed. It moves on every change, including one the server makes on its own (a map thumbnail, a geocoded place), and version moves only when an editable field does.
A gear's total_distance and total_time are computed from its activities, so a change to an activity does not report the gear again. Read the gear when its activities changed and you show its totals.
Laps, streams, workout sets and workout steps are not synced: they are written once with the activity, so read them when a new activity arrives.
The loop
GET /sync first sync: every record
GET /sync?cursor=<next_cursor> while has_more is true, right away
... has_more is false: store next_cursor
GET /sync?cursor=<stored> next time: only what changed since
A page is {"changes": [...], "next_cursor": "...", "has_more": false}. Each change is one record:
{"type": "health_weight", "id": "5f0c2a7e-91b4-4d3a-8e6c-1a2b3c4d5e6f", "changed_at": "2026-11-11T07:30:00Z", "record": {"id": "5f0c2a7e-91b4-4d3a-8e6c-1a2b3c4d5e6f", "weight_kg": 70.4, "updated_at": "2026-11-11T07:30:00Z", "...": "..."}}
{"type": "activity", "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "changed_at": "2026-11-11T08:02:11Z", "record": null}
- A change carries the whole record as
GETon the record returns it: replace your copy. - A deletion carries
record: null: delete your copy. A deletion of a record you never had is harmless. - Changes come oldest first, and the same record can appear twice in one walk when it changed again meanwhile. Apply them in order.
- Keep
next_cursorafter the last page too. It is where the next sync starts, and it is renewed on every request, even one that found nothing. num_recordssets the page size (default 100, at most 200).typeslimits the walk to some types; repeat it (?types=activity&types=gear). Withouttypes, every type your scopes can read is walked, and a type asked for without its scope is403.
Limits
- Changes appear about two minutes after they happen. The server holds a change back until every transaction that could still commit an earlier change has ended, so a page never skips one. Do not sync more often than that expecting a fresher answer.
- A cursor lasts 90 days. Deletions are remembered for 90 days, so a cursor older than that may have missed one. The server answers
410withurn:endurain:error:sync-expired: discard your copy and sync from the start, with no cursor. - A cursor is opaque and only this server can read it. A cursor the server did not issue is
400. - Deleting the account deletes everything at once and reports nothing: the account can no longer sign in to sync.