Getting started

Five minutes from "what's the API?" to a streaming agent answer about your own data.

The Amy backend is live at https://amy.heyamy.xyz. This page gets you talking to it.

You need two things

A bearer token. Clerk is the source of truth — the API verifies Clerk session JWTs directly. Pick the path that fits where you're calling from:

Surface	How to get a token
Terminal / scripts (this page)	First install the `amy` CLI. Then `amy login` once → `amy whoami --print-key` prints a 30-day Amy JWT. Also lives at `~/.amy/credentials.json`.
Mobile / web app	Use Clerk in-process: `await getToken()` from `@clerk/expo` (mobile) or `@clerk/react` (web). Send it as `Authorization: Bearer …` — no exchange step. See SDK: TypeScript.

An environment for curl / SDK.

export AMY_BASE_URL="https://amy.heyamy.xyz"
export AMY_API_KEY="$(amy whoami --print-key)"

That's it. Every example below uses curl with the CLI-minted token; mobile/web code samples use apiKeyProvider and Clerk directly.

Sanity check

curl -s "$AMY_BASE_URL/v1/me" \
  -H "Authorization: Bearer $AMY_API_KEY" | jq .

You should see your user record:

{
  "user_id": "user_…",
  "email": "you@…",
  "connections": [{ "provider": "whoop", "connected_at": "…" }],
  "env": "production"
}

No signup step required. The first authenticated request (/v1/me or any other) lazily inserts a row into the backend's users table — INSERT … ON CONFLICT DO NOTHING on the Clerk user_id. So sign in with Clerk, call any endpoint, and the backend user exists. See Concepts: Auth.

Your first turn (start + poll)

TURN_ID=$(curl -s -X POST "$AMY_BASE_URL/v1/turns" \
  -H "Authorization: Bearer $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What was my sleep score last night?"}]}' \
  | jq -r .id)

while true; do
  STATUS=$(curl -s "$AMY_BASE_URL/v1/turns/$TURN_ID" \
    -H "Authorization: Bearer $AMY_API_KEY" | jq -r .status)
  echo "status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done

curl -s "$AMY_BASE_URL/v1/turns/$TURN_ID" \
  -H "Authorization: Bearer $AMY_API_KEY" | jq .result.answer

Specific questions (one DS pull) complete in ~20–60 s. Vague questions that fan out across investigator + validator + specialists can take 2–4 minutes — they cost more, but you get a reasoning trace you can stand behind.

Your first streaming turn

TURN_ID=$(curl -s -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)

# Long sessions are the norm — leave curl's timeout off.
curl -N --no-buffer \
  -H "Authorization: Bearer $AMY_API_KEY" \
  -H "Accept: text/event-stream" \
  "$AMY_BASE_URL/v1/turns/$TURN_ID/events"

You'll see : connected immediately, then : heartbeat every ~5 s while the workflow boots, then the real event stream: turn.started → phase → routing → agent_start → agent_end → validation_end → synthesis_delta (many) → turn.completed. Full catalog: Concepts: Streaming.

With the TypeScript SDK

@amy/sdk isn't on npm — it's a workspace:* package inside this monorepo. Add your script under apps/ and import the SDK from there (full walkthrough in SDK: TypeScript):

git clone https://github.com/yatendra2001/amy_health_assistant.git
cd amy_health_assistant
bun install

# Scaffold a tiny script app and declare the SDK as a workspace dep:
#   apps/hello-amy/package.json → "dependencies": { "@amy/sdk": "workspace:*" }
#   add "apps/*" to the root package.json `workspaces` array
bun install

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

const amy = new Amy({
  apiKey: process.env.AMY_API_KEY!,
  baseUrl: process.env.AMY_BASE_URL ?? "https://amy.heyamy.xyz",
});

const me = await amy.me.get();
console.log("Hi", me.email ?? me.user_id);

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 === "synthesis_delta") process.stdout.write(event.data.text);
  if (event.type === "turn.completed")
    console.log("\n\n", event.data.result.answer);
}

bun apps/hello-amy/hello.ts

Where to go next

Want to…	Read
See every endpoint with Try-It-Now	API explorer
Look up a response shape	API reference
Understand the agent pipeline	Internals: Agent orchestration
Build a mobile app	Recipe: Build a mobile app
Hack on Amy itself	Internals: Local development