API 端点

API 端点是一种导出目标，适合希望将 Health.md 数据发送到自有服务器、Webhook、数据库、仪表板或自动化流程的用户。iPhone 仍负责读取 Apple Health；与写入文件不同，它会将 JSON POST 到您配置的端点。

隐私提醒。

此目标会有意将所选健康数据发送到您输入的 URL。请使用您控制或信任的端点，优先使用 HTTPS，并且只选择您的服务确实需要的指标。

设置目标位置

1. 在 iPhone 上打开 Health.md。
2. 前往导出。
3. 在导出目标中选择API 端点。
4. 输入 URL，例如 https://api.example.com/healthmd/ingest。
5. 可选：输入持有者令牌。Health.md 会将其存储在钥匙串中。
6. 轻点完成，选择日期范围和指标，再轻点导出。

如果输入普通令牌，Health.md 会以 Authorization: Bearer <token> 形式发送。如果该值已经以 Bearer 或 Basic 开头，Health.md 会原样发送。

载荷结构

每次导出操作会发送一个 POST。正文是独立版本化的 healthmd.api_export 封装，其中包含采用公开 schema-v8 的 healthmd.health_data 每日记录。API 封装 v1 携带每日记录；v2 还可以携带提供方辅助记录，而无需更改每日记录架构。

records

请求范围内保留的完整每日 schema-v8 对象，包括查询清单可作为证据的完整空记录。

failed_date_details

在每日文档得以保留前便处理失败的日期。

daily_record_schema_version

records 内的每日架构版本。它与 API 封装版本分别演进。

提供方辅助记录

启用已连接的提供方时，v2 可按条件包含使用自身架构和身份规则的外部记录。

可查看由生产实现生成的完整 API v1 封装和 API v2 提供方辅助记录封装。API 与 CLI 契约记录了每个字段、版本边界和接受规则。

端点要求

方法

接受 POST。

内容类型

接受 application/json。

成功

安全接收载荷后，返回任意 2xx 状态。

失败

拒绝请求时返回 4xx 或 5xx。如果响应内容可用，Health.md 会显示简短预览。

为确保可靠接收，请让端点按日期保持幂等。用户更改指标或修复服务器错误后，可能会重复导出相同日期范围。

建议

• 上传长时间范围的历史数据前，先用一天的数据测试。
• 如果来源完整性很重要，请保持启用“无损健康记录”；对于密集路线、临床文档、ECG 或附件，请缩小日期范围。
• 存储任何载荷前，先在服务器端验证令牌。
• 使用 records[].date 作为每日主键。
• 返回简洁的错误正文；Health.md 只显示简短预览。

故障排除

问题	通常表示	解决方法
API 目标尚未就绪	URL 为空或无效	重新打开 API 端点设置，并输入有效的 HTTP(S) URL。
HTTP 401 或 403	令牌缺失或被拒绝	更新令牌或服务器身份验证规则。
HTTP 404	URL 路径错误	检查服务器上的路由。
HTTP 413	载荷过大	减少导出天数；只有接收方不需要规范来源记录时，才使用仅摘要输出。
部分日期缺失	这些日期没有已启用的 HealthKit 数据	检查 failed_date_details 和指标选择。

相关内容

来源导出——选择目标位置和日期范围，并运行手动导出。 架构API 与 CLI 参考——精确封装、版本、失败行为和生成示例。 输出格式自定义——JSON、CSV、Markdown、单位和字段。