API Endpoint

API Endpoint is an export target for users who want Health.md data to flow into their own server, webhook, database, dashboard, or automation. The iPhone still reads Apple Health. Instead of writing files, it POSTs JSON to the endpoint you configure.

Privacy reminder.

This target intentionally sends selected health data to the URL you enter. Use an endpoint you control or trust, prefer HTTPS, and limit metrics to what your service actually needs.

Set up the target

1. Open Health.md on iPhone.
2. Go to Export.
3. In Export Target, choose API Endpoint.
4. Enter a URL such as https://api.example.com/healthmd/ingest.
5. Optional: enter a bearer token. Health.md stores it in Keychain.
6. Tap Done, choose your date range and metrics, then tap Export.

If you enter a plain token, Health.md sends it as Authorization: Bearer <token>. If the value already starts with Bearer or Basic , Health.md sends it as entered.

Payload shape

Health.md sends one POST per export action. The body is an independently versioned healthmd.api_export envelope containing public schema-v8 healthmd.health_data daily records. API envelope v1 carries the daily records. V2 can additionally carry provider sidecars without changing the daily-record schema.

records

Complete daily schema-v8 objects retained for the requested range, including complete-empty records whose query manifest is evidence.

failed_date_details

Dates that failed before a daily document could be retained.

daily_record_schema_version

The daily schema version inside records. It advances independently from the API envelope version.

Provider sidecars

Conditional v2 external records with their own schema and identity rules when a connected provider is enabled.

Inspect the complete production-generated API v1 envelope and API v2 provider-sidecar envelope. The API and CLI contract documents every field, version boundary, and acceptance rule.

Endpoint requirements

Method

Accept POST.

Content type

Accept application/json.

Success

Return any 2xx status after the payload is safely accepted.

Failures

Return 4xx or 5xx for rejected requests. Health.md shows a short response preview when available.

For reliable ingestion, make your endpoint idempotent by date. A user may repeat the same export range after changing metrics or fixing a server error.

Tips

• Test with one day before uploading a long backfill.
• Keep Lossless Health Records enabled when source completeness matters. Reduce the date range for dense routes, clinical documents, ECGs, or attachments.
• Validate the token server-side before storing any payload.
• Use records[].date as the primary per-day key.
• Return a concise error body. Health.md only displays a short preview.

Troubleshooting

Problem	Usually means	Fix
API target is not ready	URL is empty or invalid	Reopen API Endpoint settings and enter a valid HTTP(S) URL.
HTTP 401 or 403	Token missing or rejected	Update the token or server auth rules.
HTTP 404	URL path is wrong	Check the route on your server.
HTTP 413	Payload is too large	Export fewer days; use summary-only output only when your receiver does not require canonical source records.
Some dates are missing	No enabled HealthKit data for those dates	Check failed_date_details and your metric selection.

Related

SourceExport, choose targets, date ranges, and run manual exports. SchemaAPI and CLI Reference, exact envelopes, versions, failure behavior, and generated examples. OutputFormat Customization, JSON, CSV, Markdown, units, and fields.