API / Entwicklerprogramm
Die HealthOSX API
Lies und schreib deine eigenen HealthOSX-Daten – Aktivität, Vitalwerte, Schlaf und Workouts aus Apple Health, das vollständige Rohdaten-Archiv, Glukose, Mahlzeiten, Bluttests, Scores und eigene Einträge – über eine REST-API, mit einem Scope für jede Art von Zugriff. Tokens sind persönlich, eingeschränkt und werden in der iPhone-App erstellt. Dazu kannst du jede DNA-Rohdatei mit der DNA-Analyse-API auswerten.
Früher Zugang: Das Entwicklerprogramm wird aktiv weiterentwickelt. Endpunkte, Scopes und Antwortformate können sich noch ändern.
Loslegen
Zwei Schritte: Erstell in der App ein Token und schick es als Bearer-Header mit. Ein Token erreicht nur deine eigenen Daten und nur über die Scopes, die du gewählt hast: Lese-Scopes lesen, Schreib-Scopes legen Einträge an und ändern sie.
1. Token erstellen
Öffne die HealthOSX-App auf deinem iPhone → Einstellungen → API-Zugang → Token erstellen. Wähl die Scopes, die du brauchst, und kopier das Token – es wird genau einmal angezeigt. Tokens lassen sich nur auf dem iPhone erstellen, nicht im Web.
2. Anfrage senden
Schick das Token als Bearer-Header an die Basis-URL. Jeder Endpunkt verlangt den passenden Scope auf dem Token. Anfragen, die Einträge anlegen, brauchen außerdem einen Idempotency-Key-Header.
https://api.healthosx.com/api
Authorization: Bearer $HEALTHOS_API_TOKENJede Anfrage trägt ein persönliches API-Token im Authorization-Header. Tokens laufen ab – du legst die Laufzeit beim Erstellen fest – und lassen sich in der App jederzeit widerrufen.
Scopes
Ein Token ist auf die Scopes beschränkt, die du auswählst. Lese-Scopes gehören zu den Endpunkten unten; mit Schreib-Scopes kann ein Token Einträge anlegen, ändern und löschen. assistant:chat, community und health:dna:write sind nie Teil einer Vorauswahl: Jeder muss einzeln gewählt werden.
Lese-Scopes
Schreib-Scopes
Endpunkte
Der Apple-Health-Teil der Token-API. Alle Pfade sind relativ zur Basis-URL. Glukose, Mahlzeiten, Bluttests, Scores, Einträge, DNA und die Schreib-Routen stehen in der OpenAPI-Spezifikation und in llms.txt, zusammen mit den App-internen Routen, die eine Sitzung brauchen.
Gesundheitsdaten (Token)
| Methode | Pfad | Nötiger Scope |
|---|---|---|
| GET | /v1/health/summary | health:summary:read |
| GET | /v1/health/summary/range | health:summary:read |
| GET | /v1/health/catalog | health:summary:read |
| GET | /v1/health/metrics | health:metrics:read |
| GET | /v1/health/sleep | health:sleep:read |
| GET | /v1/health/workouts | health:workouts:read |
| GET | /v1/health/archive/samples | health:metrics:read |
| GET | /v1/health/archive/events | health:metrics:read |
| GET | /v1/health/archive/workouts | health:workouts:read |
| GET | /v1/health/archive/workout-series | health:metrics:read |
| GET | /v1/health/archive/routes | health:metrics:read |
| GET | /v1/health/archive/ecg | health:metrics:read |
| GET | /v1/health/archive/coverage | health:metrics:read |
Token-Verwaltung (Sitzung)
| Methode | Pfad | Nötiger Scope |
|---|---|---|
| POST | /v1/tokens | — |
| GET | /v1/tokens | — |
| DELETE | /v1/tokens/{token_id} | — |
Beispiel
Hol dir die Tageszusammenfassung für ein Datum in einer bestimmten Zeitzone.
curl "https://api.healthosx.com/api/v1/health/summary?date=2026-09-12&tz=Europe/Berlin" \
-H "Authorization: Bearer $HEALTHOS_API_TOKEN"{
"date": "2026-09-12",
"activity": { "steps": 1765, "active_energy_kcal": 192.0 },
"vitals": {
"heart_rate_avg": 55.2,
"heart_rate_min": 42.0,
"heart_rate_max": 102.0,
"resting_heart_rate": 43.0,
"respiratory_rate": 14.6,
"hrv_sdnn_ms": 78.0,
"body_weight_kg": null
},
"sleep": { "samples": 62, "asleep_min": 566, "in_bed_min": 436 },
"workouts": { "count": 0, "calories": 0 },
"timezone": "Europe/Berlin",
"meta": {
"data_as_of": "2026-09-13T16:21:24.684311+00:00",
"phone_last_sync_at": "2026-09-13T16:21:24.684311+00:00"
}
}DNA-Analyse-API
Schick eine DNA-Rohdatei und erhalte den vollständigen HealthOSX-DNA-Bericht als JSON zurück, dazu einen Chat, der Fragen dazu beantwortet. Es ist dieselbe Auswertung, die das kostenlose Tool auf healthosx.com/dna macht, für Agents und Apps. Sie liest Exporte von 23andMe, AncestryDNA, MyHeritage, FamilyTreeDNA und Living DNA sowie Whole-Genome-VCFs (.vcf / .vcf.gz).
1 $ pro Auswertung, im Voraus bezahlt; der Chat zu dieser Auswertung ist inklusive. Der Preis soll Missbrauch eines rechenintensiven Endpunkts verhindern: Auf healthosx.com/dna können Menschen dieselbe Auswertung kostenlos nutzen. Kann eine Datei nicht gelesen werden, gibt es das Guthaben automatisch zurück.
1. Key erstellen und aufladen
POST /v1/dna/keys gibt einmalig einen dna_…-Key zurück. POST /v1/dna/fund mit dem Key gibt einen Stripe-Checkout-Link zurück; jedes Guthaben ist eine Auswertung.
2. Datei hochladen
POST /v1/dna/analyze mit der Datei als Multipart-Formular. Dateien über etwa 100 MB, zum Beispiel Whole-Genome-VCFs, gehen über /analyze/start, 32-MB-Teile, dann /finish.
3. Bericht lesen
Frag GET /v1/dna/analyze/{token} ab. Steht der Status auf "ready", enthält die Antwort den Bericht, darunter Merkmale, Herkunft und die mütterliche und väterliche Linie (mtDNA- und Y-Haplogruppen). Alle Felder stehen in der OpenAPI-Spezifikation.
4. Fragen stellen, dann löschen
POST /v1/dna/analyze/{token}/chat antwortet auf Grundlage der Auswertung. DELETE /v1/dna/analyze/{token} löscht Datei, Bericht und Chat.
DNA-Analyse (Key oder Analyse-Token)
| Methode | Pfad | Zugang |
|---|---|---|
| POST | /v1/dna/keys | keiner |
| GET | /v1/dna/keys/me | dna_-Key |
| DELETE | /v1/dna/keys/me | dna_-Key |
| POST | /v1/dna/fund | dna_-Key |
| POST | /v1/dna/analyze | dna_-Key |
| POST | /v1/dna/analyze/start | dna_-Key |
| POST | /v1/dna/analyze/{token}/chunk/{index} | Analyse-Token |
| POST | /v1/dna/analyze/{token}/finish | Analyse-Token |
| GET | /v1/dna/analyze/{token} | Analyse-Token |
| POST | /v1/dna/analyze/{token}/chat | Analyse-Token |
| POST | /v1/dna/analyze/{token}/messages | dna_-Key |
| GET | /v1/dna/analyze/{token}/chat | Analyse-Token |
| DELETE | /v1/dna/analyze/{token} | Analyse-Token |
# 1. Create a key (shown once) and fund it
curl -X POST https://api.healthosx.com/api/v1/dna/keys -H "Content-Type: application/json" \
-d '{"name": "my-agent"}'
curl -X POST https://api.healthosx.com/api/v1/dna/fund -H "Authorization: Bearer $DNA_KEY" \
-H "Content-Type: application/json" -d '{"credits": 5}' # open the returned url and pay
# 2. Analyze a raw file
curl -X POST https://api.healthosx.com/api/v1/dna/analyze -H "Authorization: Bearer $DNA_KEY" \
-F "file=@genome_23andMe.txt"
# 3. Poll until ready, then ask
curl https://api.healthosx.com/api/v1/dna/analyze/$TOKEN
curl -X POST https://api.healthosx.com/api/v1/dna/analyze/$TOKEN/chat -H "Content-Type: application/json" \
-d '{"message": "How do I metabolise caffeine?"}'{
"token": "…",
"status": "ready",
"report": {
"file": { "kind": "array", "vendor": "AncestryDNA", "build": "GRCh37", "rows": 434818, "called": 434459 },
"report": { "traits": [ … ], "health_markers": [ … ], "pharmacogenomics": [ … ] },
"apoe": { … },
"maternal_line": { … },
"paternal_line": { … },
"carrier": { … },
"polygenic": { … }
}
}Die Datei wird verschlüsselt gespeichert. Der Key bezahlt; nur das Analyse-Token liest einen Bericht, so kannst du eine einzelne Auswertung an einen Worker geben, ohne den Key zu teilen. Nichts davon ist eine medizinische Diagnose oder ein Medizinprodukt.
Referenz
Die vollständige OpenAPI-Spezifikation und ein maschinenlesbarer Index liegen direkt neben der API.
Früher Zugang & Support
Fragen, Feedback oder Fehlerberichte – schreib uns eine E-Mail, wir melden uns.
developers@healthosx.com