Documentation
Internal docs for the Amy backend. The production API is live at amy.heyamy.xyz — this site shows how to call it, what it returns, and what the agent does inside.
Amy is our personal health agent. It reads each user's wearable data + bloodwork and runs a multi-agent reasoning pipeline that gates every quantitative claim before it reaches the user.
The CLI is a real app today. The production backend is live at amy.heyamy.xyz. Mobile and web clients sit on top of the same API.
Who is this for? Us — engineers on the Amy team and the AI assistants (Claude Code, Cursor) that pair with us. Same docs, both audiences.
Start here
| You want to… | Go to |
|---|---|
| Talk to the API for the first time | Getting started |
| Try every endpoint with one click | Interactive API explorer |
| Understand how the pieces fit | Architecture |
| Look up an endpoint or response shape | API reference |
| Build a mobile app on top of Amy | Build a mobile app |
| Build a web app | Build a web app |
| Use the TypeScript SDK | SDK · TypeScript |
| Add a new wearable source | Add a new adapter |
| Hack on the agents themselves | Internals: Local development |
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 five minutes to your first agent answer
│ └── using-the-cli the `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 the team)
├── runtime Workers, Workflows, Queues, Crons
├── agent-orchestration the 9-step runTurn pipeline
├── data-pipeline webhook → queue → D1
├── storage D1 + R2 + KV layout
├── local-development inner dev loop (wrangler dev, hot reload)
└── deploying Cloudflare deploy runbook (re-provision / staging)A 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.