API / Developer Program

The HealthOS API

Read and write your own HealthOS data — Apple Health activity, vitals, sleep and workouts, the full raw archive, glucose, meals, blood tests, scores and manual logs — through one REST API, with a scope for each kind of access. Tokens are personal, scoped, and created in the iPhone app. And analyse any raw DNA file with the DNA analysis API.

Early access: the developer program is under active development. Endpoints, scopes, and response shapes may still change.

Get started

Two steps. Create a token in the app, then send it as a bearer header. A token reaches only your own data, and only through the scopes you picked: read scopes read, write scopes add and change entries.

1. Create a token

Open the HealthOS app on your iPhone → Settings → API access → Create token. Pick the scopes you need and copy the token — it is shown exactly once. Tokens can only be created on the iPhone, not on the web.

2. Make a request

Send the token as a bearer header against the base URL. Each endpoint requires the matching scope on the token. Requests that create entries also need an Idempotency-Key header.

Base URL · Authentication

terminal

https://api.healthosx.com/api
Authorization: Bearer $HEALTHOS_API_TOKEN

Every request carries a personal API token in the Authorization header. Tokens expire — set an expiry when you create one — and can be revoked at any time from the app.

Scopes

A token is limited to the scopes you select. Read scopes map to the endpoints below; write scopes let a token add, change and delete entries. assistant:chat, community and health:dna:write are never part of a preset: each has to be picked on its own.

Read 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

Write scopes

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

Endpoints

The Apple Health part of the token API. All paths are relative to the base URL. Glucose, meals, blood tests, scores, logs, DNA and the write routes are in the OpenAPI specification and in llms.txt, along with the app-internal, session-authenticated routes.

Health data (token auth)

Method	Path	Required 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 management (session auth)

Method	Path	Required scope
POST	/v1/tokens	—
GET	/v1/tokens	—
DELETE	/v1/tokens/{token_id}	—

Example

Fetch a one-day summary for a date in a specific timezone.

Request

shell

curl "https://api.healthosx.com/api/v1/health/summary?date=2026-09-12&tz=Europe/Berlin" \
  -H "Authorization: Bearer $HEALTHOS_API_TOKEN"

Response

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 analysis API

Send a raw DNA file and get the full HealthOS DNA report back as JSON, plus a chat that answers questions about it. It is the same analysis the free tool at healthosx.com/dna runs, for agents and apps. It accepts 23andMe, AncestryDNA, MyHeritage, FamilyTreeDNA and Living DNA exports, and whole-genome VCFs (.vcf / .vcf.gz).

$1 per analysis, prepaid, and chat on that analysis is included. The charge is there to stop abuse of a compute-heavy endpoint: people can use the same analysis free at healthosx.com/dna. An upload that cannot be read gets its credit back automatically.

1. Create and fund a key

POST /v1/dna/keys returns a dna_… key once. POST /v1/dna/fund with the key returns a Stripe Checkout link; each credit is one analysis.

2. Upload a file

POST /v1/dna/analyze with the file as multipart form data. Files over about 100MB, such as whole-genome VCFs, go through /analyze/start, 32MB chunks, then /finish.

3. Read the report

Poll GET /v1/dna/analyze/{token}. When status is "ready", the response holds the report: traits, health markers, pharmacogenomics, APOE, maternal and paternal lines (mtDNA and Y haplogroups), a carrier screen and polygenic tendencies.

4. Ask questions, then delete

POST /v1/dna/analyze/{token}/chat answers from the analysis. DELETE /v1/dna/analyze/{token} erases the file, report and chat.

DNA analysis (key or analysis token)

Method	Path	Credential
POST	/v1/dna/keys	none
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}	analysis token
POST	/v1/dna/analyze/{token}/finish	analysis token
GET	/v1/dna/analyze/{token}	analysis token
POST	/v1/dna/analyze/{token}/chat	analysis token
POST	/v1/dna/analyze/{token}/messages	dna_ key
GET	/v1/dna/analyze/{token}/chat	analysis token
DELETE	/v1/dna/analyze/{token}	analysis token

Request

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?"}'

Response

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": { … }
  }
}

The file is encrypted at rest. The key pays; only the analysis token reads a report, so you can hand one analysis to a worker without sharing the key. Polygenic tendencies are percentiles against the 2,504 people of 1000 Genomes, not predictions. Nothing here is a diagnosis or a medical device.

Reference

The full OpenAPI specification and a machine-readable index are published alongside the API.

OpenAPI specification llms.txt MCP server

Early access & support

Questions, feedback, or bug reports — email us and we will get back to you.

developers@healthosx.com