# HealthOS API

> The HealthOS API gives language models read access to a user's health data
> via personal tokens with granular read scopes, and analyses raw DNA files
> through the prepaid DNA analysis API.

## Machine-readable spec

- OpenAPI 3.1: `/openapi.json`
- Interactive docs: `/docs`

## Authentication

Create a personal token under `POST /api/v1/tokens` (cookie-authenticated),
then send it as `Authorization: Bearer <token>`. Tokens are scoped and
revocable; never log or echo them.

## Endpoints

- `GET /api/v1/health/summary?date=YYYY-MM-DD&tz=IANA` — one-day aggregate.
- `GET /api/v1/health/summary/range?from=YYYY-MM-DD&to=YYYY-MM-DD` — daily summaries.
- `GET /api/v1/health/metrics?metric_type=...&from=...&to=...&cursor=...` — projected series.
- `GET /api/v1/health/sleep` — projected sleep stages.
- `GET /api/v1/health/workouts` — projected workouts.
- `GET /api/v1/health/coverage` — per-family counts and date range.
- `GET /api/v1/health/archive/samples|events|workouts|workout-series|routes|ecg` — full canonical archive.
- `POST /api/v1/export/jobs` — async JSON/CSV/GPX/ZIP export.

## DNA analysis API

For software that analyses a raw DNA file on someone's behalf. People can use
the same analysis free at https://healthosx.com/dna. Guide:
https://healthosx.com/developers#dna

- Accepts 23andMe, AncestryDNA, MyHeritage, FamilyTreeDNA and Living DNA
  exports, and whole-genome `.vcf` / `.vcf.gz`.
- $1 per analysis, prepaid through Stripe. The price is there to stop abuse of
  the endpoint. An unreadable upload is refunded automatically; five chat
  questions are included, and one more credit buys five more.

### The two credentials

- The **key** (`dna_…`) funds and spends: send it as `Authorization: Bearer dna_…`
  on `/keys/me`, `/fund`, `/analyze`, `/analyze/start` and `/analyze/{token}/messages`.
  It can never read a report.
- The **analysis token** returned by `/analyze` is the capability for one
  analysis: `GET /analyze/{token}`, the chat, the chunk/finish uploads and
  `DELETE` need it in the path and **no** `Authorization` header at all. It is
  unguessable and it is the only thing that opens that report — store it, and
  treat it like a password.

### Working with an analysis

- `status` is one of `uploading`, `processing`, `ready`, `failed` (`error` says
  why, and a failed analysis is refunded), or the analysis is gone and the call
  is a 404. Poll `GET /analyze/{token}` every 3-5 seconds: a chip file is
  usually ready in 2-3 minutes, a whole genome in 5-10.
- The reply is `{token, status, progress, error, report, chat, expires_at}`.
  `report` is null until `ready`, then carries `file`, `apoe`, `markers`,
  `report.traits`, `report.health_markers`, `report.pharmacogenomics`,
  `maternal_line`, `paternal_line`, `carrier`, `ancestry`, `polygenic` and
  `capabilities`.
- `chat` is `{questions_used, questions_remaining}`. A chat turn returns
  `{message_id, text, status, steps, questions_remaining}`.
- Chunked upload: `POST /analyze/start` takes `{bytes, vendor?, source_kind?}`,
  where `source_kind` is `array` (a chip export) or `vcf`, and `vendor` is free
  text such as "23andMe". Send each chunk as a raw body, in order from 0.
- Every analysis erases itself 30 days after it was created — file, report and
  chat. `expires_at` says when. `DELETE` does it sooner.
- Whoever uploads a file must be the person it came from or have their explicit
  permission. Nothing here is medical advice, and nothing here is used to train
  anything.

- `POST /api/v1/dna/keys` — create a key (returned once, 0 credits). Body: `{"name": "..."}`.
- `GET /api/v1/dna/keys/me` — credits left. `DELETE` revokes the key.
- `POST /api/v1/dna/fund` — `{"credits": N}` → Stripe Checkout `url`; credits land after payment.
- `POST /api/v1/dna/analyze` — multipart `file`, spends one credit → `token`. HTTP 402 means no credits.
- `POST /api/v1/dna/analyze/start` → `/analyze/{token}/chunk/{index}` (32MB each) → `/analyze/{token}/finish` — for files over ~100MB.
- `GET /api/v1/dna/analyze/{token}` — `status` and, when `ready`, the `report`: traits, health markers, pharmacogenomics, APOE, maternal and paternal lines, carrier screen, polygenic tendencies.
- `POST /api/v1/dna/analyze/{token}/chat` — `{"message": "..."}`; `GET` returns the conversation. HTTP 402 `needs_messages` means the included questions are used.
- `POST /api/v1/dna/analyze/{token}/messages` — spend one credit for five more questions on this analysis.
- `DELETE /api/v1/dna/analyze/{token}` — erase the file, report and chat.

Polygenic tendencies are percentiles against the 2,504 people of 1000 Genomes,
not predictions. Nothing here is a diagnosis.

## Conventions

- Timestamps are ISO-8601 UTC; pass `tz` where a local day matters.
- List endpoints paginate with an opaque `cursor` returned as `next_cursor`.
- `from`/`to` are inclusive ISO-8601 instants (or `YYYY-MM-DD` for summaries).
- Reports are measurements, not medical advice; cite the date range and source
  coverage in every answer.