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.

Basis-URL · Authentifizierung
terminal
https://api.healthosx.com/api
Authorization: Bearer $HEALTHOS_API_TOKEN

Jede 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

health:summary:readhealth:metrics:readhealth:sleep:readhealth:workouts:readhealth:nutrition:readhealth:glucose:readhealth:labs:readhealth:dna:readhealth:export:readhealth:logs:readprofile:readgoals:readmedia:readinsights:readdiscovery:readmemory:readnotifications:readaccount:readconsents:readorders:readcommunity:read

Schreib-Scopes

health:nutrition:writehealth:labs:writehealth:logs:writehealth:dna:writeprofile:writegoals:writemedia:writeaccount:writeinsights:writediscovery:writememory:writenotifications:writeconsents:writecommunity:writeassistant:chat

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)

MethodePfadNötiger Scope
GET/v1/health/summaryhealth:summary:read
GET/v1/health/summary/rangehealth:summary:read
GET/v1/health/cataloghealth:summary:read
GET/v1/health/metricshealth:metrics:read
GET/v1/health/sleephealth:sleep:read
GET/v1/health/workoutshealth:workouts:read
GET/v1/health/archive/sampleshealth:metrics:read
GET/v1/health/archive/eventshealth:metrics:read
GET/v1/health/archive/workoutshealth:workouts:read
GET/v1/health/archive/workout-serieshealth:metrics:read
GET/v1/health/archive/routeshealth:metrics:read
GET/v1/health/archive/ecghealth:metrics:read
GET/v1/health/archive/coveragehealth:metrics:read

Token-Verwaltung (Sitzung)

MethodePfadNö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.

Anfrage
shell
curl "https://api.healthosx.com/api/v1/health/summary?date=2026-09-12&tz=Europe/Berlin" \
  -H "Authorization: Bearer $HEALTHOS_API_TOKEN"
Antwort
application/json
{
  "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)

MethodePfadZugang
POST/v1/dna/keyskeiner
GET/v1/dna/keys/medna_-Key
DELETE/v1/dna/keys/medna_-Key
POST/v1/dna/funddna_-Key
POST/v1/dna/analyzedna_-Key
POST/v1/dna/analyze/startdna_-Key
POST/v1/dna/analyze/{token}/chunk/{index}Analyse-Token
POST/v1/dna/analyze/{token}/finishAnalyse-Token
GET/v1/dna/analyze/{token}Analyse-Token
POST/v1/dna/analyze/{token}/chatAnalyse-Token
POST/v1/dna/analyze/{token}/messagesdna_-Key
GET/v1/dna/analyze/{token}/chatAnalyse-Token
DELETE/v1/dna/analyze/{token}Analyse-Token
Anfrage
shell
# 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?"}'
Antwort
application/json
{
  "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