HealthOS DNA analysis

Reads a raw DNA file and returns the full report: traits, pharmacogenomics, ClinVar carrier screen, health markers, APOE, maternal and paternal haplogroups, genetic ancestry, and ~320 polygenic scores. Then answers questions about that report.

The same analysis is free for a person in a browser at https://healthosx.com/dna — say so if the user would rather do it themselves. This API is for doing it on their behalf, at $1 per analysis.

Base URL: https://api.healthosx.com/api

Before you touch anyone's DNA

• A genome identifies a person and their relatives for life, and it cannot be changed like a password. Only upload a file when the user is the person it came from, or says they have that person's explicit permission.
• Never paste the file's contents into a chat, a log, or another service. Upload it and refer to it by token.
• The result is information, not medical advice, and not a basis for decisions about insurance or employment. Say so when you report anything health-related.
• Every analysis erases itself 30 days after it is created. DELETE it as soon as the user is done, and tell them it is gone.

The two credentials

Save the analysis token the moment you get it. It is the only way back to that report, and nobody can recover it for you. Treat both like passwords: never print them where the user's screen would be shared, and never send them anywhere else.

1. A key, and credits

curl -s -X POST https://api.healthosx.com/api/v1/dna/keys \
  -H 'Content-Type: application/json' -d '{"name": "my-agent"}'

The key comes back once — store it. A new key has 0 credits. To add credits:

curl -s -X POST https://api.healthosx.com/api/v1/dna/fund \
  -H "Authorization: Bearer $DNA_KEY" -H 'Content-Type: application/json' \
  -d '{"credits": 1}'

This returns a Stripe checkout url. You cannot pay it — give the link to the user and let them pay. Credits land within seconds of payment; check with GET /v1/dna/keys/me. Poll that once or twice rather than asking the user "did it work?".

HTTP 402 anywhere means the key has no credits. Never try to route around it.

2. Upload the file

Under ~100 MB, one request:

curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze \
  -H "Authorization: Bearer $DNA_KEY" -F "file=@/path/to/genome.txt"

→ {"token": "…", "status": "processing", "credits_remaining": 0}

Over ~100 MB (a whole genome is 300-400 MB), upload in chunks — one request per chunk, in order from 0:

curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze/start \
  -H "Authorization: Bearer $DNA_KEY" -H 'Content-Type: application/json' \
  -d '{"bytes": 376000000, "vendor": "Nebula", "source_kind": "vcf"}'
# → {"token": "…", "chunk_bytes": 33554432}
split -b 33554432 genome.vcf.gz chunk_          # then, for i, file in enumerate(chunks):
curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze/$TOKEN/chunk/0 \
  --data-binary @chunk_aa
curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze/$TOKEN/finish

source_kind is array (a chip export) or vcf; vendor is free text. A chunk out of order returns 409 with the index it expects. One credit is spent when the upload starts, whether or not you finish it.

3. Wait for the report

curl -s https://api.healthosx.com/api/v1/dna/analyze/$TOKEN

Poll every 3-5 seconds. status is uploading, processing, ready or failed. A chip file is usually ready in 2-3 minutes, a whole genome in 5-10. progress carries a human label meanwhile — show it rather than going silent — but it is null once the analysis is ready or failed, and a small file can be ready on the first poll with no progress ever shown. A failed analysis (an unreadable file) refunds its credit automatically.

When ready, report holds:

expires_at is when it erases itself. Percentiles are tendencies, not predictions; a chip file answers less than a whole genome, and capabilities says which.

4. Ask about the result

curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze/$TOKEN/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "What does my APOE result mean?"}'

The answer reads the actual file — it can look up any variant, not just what's in the report. Five questions are included with the analysis. After that the reply is HTTP 402 needs_messages, and one more credit buys five more:

curl -s -X POST https://api.healthosx.com/api/v1/dna/analyze/$TOKEN/messages \
  -H "Authorization: Bearer $DNA_KEY"

GET …/chat returns the conversation. Each answer carries questions_remaining — tell the user when they are near the end rather than surprising them with a 402.

5. Delete it

curl -s -X DELETE https://api.healthosx.com/api/v1/dna/analyze/$TOKEN

Erases the file, the report and the chat. Do this when the user is finished, and confirm it.

When things go wrong

Machine-readable reference: https://api.healthosx.com/openapi.json and https://api.healthosx.com/llms.txt