Getting started

Ten minutes from zero to your first turn against a live Amy backend. Pick whichever path matches you.

Pick your path

You are…	Go here
Building a client against an Amy backend that already exists	Path A: Use a running backend
Standing up your own Amy backend for the first time	Path B: Deploy a fresh backend
Working on Amy itself (CLI, agents, the API)	Path C: Local development

Path A — Use a running backend

You need two things:

The base URL of an Amy backend, e.g. https://api.amy.health.
An API key for your user (amy_live_…).

If you have those, you can hit the API from anywhere.

With curl

export AMY_BASE_URL="https://api.amy.health"
export AMY_API_KEY="amy_live_…"

# Sanity check: who am I?
curl -s "$AMY_BASE_URL/v1/me" \
  -H "Authorization: Bearer $AMY_API_KEY" | jq .

You should see your user record.

Your first turn

# Start a non-streaming turn (blocks until done, up to ~7 min)
curl -X POST "$AMY_BASE_URL/v1/turns" \
  -H "Authorization: Bearer $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "What is my average HRV this month?" }],
    "stream": false
  }' | jq .result.answer

Your first streaming turn

# Step 1: kick off the turn
TURN_ID=$(curl -X POST "$AMY_BASE_URL/v1/turns" \
  -H "Authorization: Bearer $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"How is my recovery trending?"}]}' \
  | jq -r .id)

# Step 2: stream events as they happen
curl -N -H "Authorization: Bearer $AMY_API_KEY" \
  "$AMY_BASE_URL/v1/turns/$TURN_ID/events"

You'll see SSE frames stream in. Press Ctrl-C to disconnect; you can always re-subscribe from the last event ID.

With the TypeScript SDK

mkdir hello-amy && cd hello-amy
bun init -y
bun add @amy/sdk

// hello.ts
import { Amy } from "@amy/sdk";

const amy = new Amy({
  apiKey: process.env.AMY_API_KEY!,
  baseUrl: process.env.AMY_BASE_URL!,
});

const me = await amy.me.get();
console.log("Hi", me.name);

const turn = await amy.turns.create({
  messages: [{ role: "user", content: "How's my recovery?" }],
});

for await (const event of amy.turns.stream(turn.id)) {
  if (event.type === "agent.thought") process.stdout.write(event.delta);
  if (event.type === "turn.completed") console.log("\n\n", event.result.answer);
}

bun hello.ts

That's the full surface. Next:

Connect a wearable: Recipe: Connect a wearable.
Upload a lab: Recipe: Upload a lab report.
Build a UI on top: Recipe: Build a mobile app.

Path B — Deploy a fresh backend

You'll deploy your own Amy backend to Cloudflare. ~30 minutes, mostly one-time account setup. See the full Deploying to Cloudflare guide — or skim the summary:

Sign up for Cloudflare (free tier is fine to start).
Sign up for Clerk (auth).
Sign up for Terra (wearable + lab data).
Either get an Anthropic API key, an OpenRouter key, or sign in with claude login.
Clone the repo, copy .env.example to .env, fill in the secrets.
From the cloud/ directory: bun install && bunx wrangler deploy.
The Worker URL Cloudflare prints is your base URL.

Detailed instructions, secret setup, DNS, and rollback are in Deploying to Cloudflare.

What to read next

Curiosity	Doc
What's actually inside this backend?	Architecture
How do I keep the API in sync as my client changes?	SDK: TypeScript
What events does the stream emit?	Concepts: Streaming
What can go wrong?	Concepts: Errors
How does the agent actually answer a question?	Internals: Agent orchestration

Getting started

On this page