API-Endpunkt

Der API-Endpunkt ist ein Exportziel für Benutzer, die Health.md-Daten an ihren eigenen Server, Webhook, ihre Datenbank, ihr Dashboard oder ihre Automatisierung übertragen möchten. Das iPhone liest weiterhin Apple Health; statt Dateien zu schreiben, sendet es JSON per POST an den von Ihnen konfigurierten Endpunkt.

Hinweis zum Datenschutz.

Dieses Ziel sendet ausgewählte Gesundheitsdaten bewusst an die von Ihnen eingegebene URL. Verwenden Sie einen Endpunkt, den Sie kontrollieren oder dem Sie vertrauen, bevorzugen Sie HTTPS und beschränken Sie die Metriken auf das, was Ihr Dienst tatsächlich benötigt.

Ziel einrichten

1. Öffnen Sie Health.md auf dem iPhone.
2. Wechseln Sie zu Export.
3. Wählen Sie unter Export Target den Eintrag API Endpoint.
4. Geben Sie eine URL wie https://api.example.com/healthmd/ingest ein.
5. Optional: Geben Sie ein Bearer-Token ein. Health.md speichert es im Schlüsselbund.
6. Tippen Sie auf Done, wählen Sie Datumsbereich und Metriken und tippen Sie anschließend auf Export.

Wenn Sie ein reines Token eingeben, sendet Health.md es als Authorization: Bearer <token>. Beginnt der Wert bereits mit Bearer oder Basic , sendet Health.md ihn unverändert.

Struktur der Nutzlast

Health.md sendet pro Exportvorgang eine POST-Anfrage. Der Request-Body ist ein unabhängig versionierter API-Envelope vom Typ healthmd.api_export mit täglichen Datensätzen des öffentlichen Schemas v8 healthmd.health_data. Der API-Envelope v1 enthält die täglichen Datensätze; v2 kann zusätzlich Provider-Sidecars enthalten, ohne das Schema der täglichen Datensätze zu ändern.

records

Vollständige tägliche Schema-v8-Objekte, die für den angeforderten Zeitraum beibehalten wurden, einschließlich vollständig leerer Datensätze, deren Abfragemanifest als Nachweis dient.

failed_date_details

Datumswerte, bei denen ein Fehler auftrat, bevor ein Tagesdokument beibehalten werden konnte.

daily_record_schema_version

Die Version des täglichen Schemas innerhalb von records. Sie wird unabhängig von der Version des API-Envelopes weiterentwickelt.

Provider-Sidecars

Bedingte externe v2-Datensätze mit eigenem Schema und eigenen Identitätsregeln, wenn ein verbundener Provider aktiviert ist.

Prüfen Sie den vollständigen, mit dem Produktcode erzeugten API-Envelope v1 und den API-Envelope v2 mit Provider-Sidecar. Der API- und CLI-Vertrag dokumentiert jedes Feld, jede Versionsgrenze und jede Akzeptanzregel.

Anforderungen an den Endpunkt

Methode

Akzeptieren Sie POST.

Inhaltstyp

Akzeptieren Sie application/json.

Erfolg

Geben Sie einen beliebigen 2xx-Status zurück, nachdem die Nutzlast sicher angenommen wurde.

Fehler

Geben Sie bei abgelehnten Anfragen 4xx oder 5xx zurück. Health.md zeigt, sofern verfügbar, eine kurze Vorschau der Antwort an.

Gestalten Sie Ihren Endpunkt für eine zuverlässige Aufnahme pro Datum idempotent. Benutzer können denselben Exportzeitraum erneut senden, nachdem sie Metriken geändert oder einen Serverfehler behoben haben.

Tipps

• Testen Sie zunächst mit einem Tag, bevor Sie umfangreiche historische Daten hochladen.
• Lassen Sie Lossless Health Records aktiviert, wenn die Vollständigkeit der Quelldaten wichtig ist; verkürzen Sie den Zeitraum bei dichten Routen, klinischen Dokumenten, EKGs oder Anhängen.
• Validieren Sie das Token serverseitig, bevor Sie Nutzdaten speichern.
• Verwenden Sie records[].date als primären Schlüssel pro Tag.
• Geben Sie einen knappen Fehlertext zurück; Health.md zeigt nur eine kurze Vorschau an.

Fehlerbehebung

Problem	Übliche Ursache	Lösung
API-Ziel ist nicht bereit	URL ist leer oder ungültig	Öffnen Sie die Einstellungen für API Endpoint erneut und geben Sie eine gültige HTTP(S)-URL ein.
HTTP 401 oder 403	Token fehlt oder wurde abgelehnt	Aktualisieren Sie das Token oder die Authentifizierungsregeln des Servers.
HTTP 404	URL-Pfad ist falsch	Prüfen Sie die Route auf Ihrem Server.
HTTP 413	Nutzlast ist zu groß	Exportieren Sie weniger Tage; verwenden Sie eine reine Zusammenfassung nur, wenn der Empfänger keine kanonischen Quelldatensätze benötigt.
Einige Datumswerte fehlen	Für diese Tage sind keine aktivierten HealthKit-Daten vorhanden	Prüfen Sie failed_date_details und Ihre Metrikauswahl.

Verwandte Themen

QuelleExport — Ziele und Datumsbereiche auswählen und manuelle Exporte ausführen. SchemaAPI- und CLI-Referenz — exakte API-Envelopes, Versionen, Fehlerverhalten und generierte Beispiele. AusgabeFormatanpassung — JSON, CSV, Markdown, Einheiten und Felder.