Documentation
Getting started
Choose hosted storage or your own server, connect Apple Health, and verify your first sync.
Read as Markdown1. Choose where your data goes
HealthSync reads Apple Health on your iPhone after you grant permission. You can use the app's hosted HealthSync storage or run the open source FastAPI backend with Postgres. A managed Postgres database alone is not a sync endpoint: you still need to run the API.
- Hosted HealthSync storage: the app provisions a private workspace. No server setup is needed.
- Your own backend: you operate the API, database, HTTPS, backups, and updates. Xcode is not required to run the server.
2. Connect Apple Health
Install HealthSync on your iPhone and tap Continue. The default setup creates hosted storage and asks you to review Apple Health read permissions. Choose the categories you want to sync.
To use your own server, open Settings, choose your own backend, and enter its reachable base URL and auth token. Enter the base URL without /api/apple-health/sync; the app adds that path. For the standard self-hosted server, the auth token is API_TOKEN.
3. Verify a real sync
- Choose a category that has samples in Apple Health, then run Sync last 24 hours.
- Review Sync Logs for a successful upload. If the samples are older, use Backfill date range.
- For your own backend, fetch /api/apple-health/metrics or /api/apple-health/workouts with API_TOKEN. For hosted storage, use the private agent endpoint and read-only agent token.
- An empty response can mean there are no permitted samples in the selected date range. A successful /health response only confirms the API is responding; a successful upload and fetch confirm storage works.
4. Set your sync preferences
In Settings, select data types and sync frequency. Background delivery is best effort: iOS controls when the app runs. Low Power Mode, a locked phone, rebooting, or force-quitting can delay sync. Manual sync and backfill are the reliable ways to request an update.