Amy — Documentation
The complete reference for Amy, the personal health agent. Backend on Cloudflare, SDK in TypeScript, and recipes for shipping clients on top of it.
This is the full reference for Amy — a personal health agent that reads your real wearable data and blood panels, runs a multi-agent reasoning pipeline, and answers in plain language. Every quantitative claim is checked before it reaches you.
The CLI is a real app today. The backend is live at amy.heyamy.xyz on Cloudflare. Mobile and web clients sit on top of the same API.
Who is this for? Engineers wiring Amy into their own app, AI agents (Claude Code, Cursor) writing that integration for someone, and the team maintaining Amy. Same docs, three audiences.
Start here
| You want to… | Go to |
|---|---|
| Understand what Amy is and how the pieces fit | Architecture |
| Get the API running locally in ten minutes | Getting started |
| Build a mobile app on top of Amy | Build a mobile app |
| Build a web app | Build a web app |
| Look up an endpoint or response shape | API reference |
| Use the TypeScript SDK | SDK · TypeScript |
| Deploy your own Amy backend | Deploying |
| Add a new wearable source | Add a new adapter |
How the docs are organised
docs/
├── architecture the whole system, in one document
├── api-reference every endpoint, every shape
│
├── concepts/ the ideas behind the API
│ ├── turns the agent run loop
│ ├── streaming live token streams
│ ├── memory what Amy remembers
│ ├── webhooks Terra → Amy ingest
│ └── errors the error model + every code
│
├── guides/ how-to, in order
│ ├── getting-started ten minutes to your first turn
│ ├── local-development the inner dev loop
│ ├── deploying deploy to Cloudflare end to end
│ └── using-the-cli the existing `amy` command
│
├── recipes/ end-to-end builds
│ ├── ask-a-question minimum-viable turn
│ ├── stream-events subscribe to live token streams
│ ├── connect-a-wearable the Terra widget flow
│ ├── upload-a-lab-report multipart → R2 → Terra OCR
│ ├── build-a-mobile-app React Native via Claude Code
│ ├── build-a-web-app Next.js with streaming SSE
│ └── add-a-new-adapter plug in a new data source
│
├── sdk/ language SDKs
│ ├── index which SDK, when
│ └── typescript the TS reference
│
└── internals/ how Amy is built (for maintainers)
├── runtime Workers, Workflows, Queues, Crons
├── agent-orchestration the 9-step runTurn pipeline
├── data-pipeline webhook → queue → D1
└── storage D1 + R2 + KV layoutA reading order
Five minutes — read Architecture and look at the diagram.
Thirty minutes — Architecture, then Getting started, then Concepts · Turns.
Shipping a mobile app — Architecture → Build a mobile app → SDK · TypeScript → Streaming.
Shipping a web app — Architecture → Build a web app → Streaming.
If you're an AI agent reading this — start with the llms.txt index. Every page is also available as raw markdown by appending /content.md to the URL.
House conventions
- Every code block is copy-pasteable. Placeholders are in
<angle-brackets>and the surrounding text says what to substitute. - Every endpoint has a curl example, a TypeScript example, and the full request and response schemas.
- Every concept page has a "Common mistakes" section.
- Every error has a stable
codeand a docs link. - No HTML, no JavaScript, no tracking. Just markdown rendered as a site. Works in any browser, any editor, any LLM context window.
Amy gives you information, not medical advice. Talk to a clinician before acting on anything here.