Documentation

Amy is an agentic AI backend you call over HTTP. You send a message; Amy plans, calls tools, delegates to specialist agents where it helps, and returns an answer — streamed, awaited, or queued.

The shape of the API

There are 14 operations under /v1, authenticated with a single X-Api-Key header. 3 of them answer with a stream of events rather than one JSON body, and a stream emits 13 kinds of event.

Your organisation

GET /v1/organisation/inference-privacy

The calling API key's organisation's inference privacy verification.

Start a run

POST /v1/agents/{agentId}/runs

Start an Amy run; streams tokens, tool calls/results, usage, and a terminal event over SSE.

POST /v1/agents/{agentId}/runs/await

Start an Amy run and return one JSON result when it completes.

POST /v1/agents/{agentId}/runs/submit

Submit an Amy run for asynchronous execution; returns 202 + a run id to poll via GET /v1/runs/{runId}.

Read and steer a run

GET /v1/runs/{runId}

The full persisted run (status, messages, usage); 404 covers cross-tenant ids and another client's runs.

POST /v1/runs/{runId}/approvals/{approvalId}

Resume an approval-paused run with approve/deny; streams the continuation over SSE.

POST /v1/runs/{runId}/retry

Retry a failed run from its committed trace — no tool is re-executed; streams the re-drive over SSE.

POST /v1/runs/{runId}/cancel

Cancel a run this client started; 404 covers cross-tenant ids and another client's runs.

GET /v1/runs/{runId}/files/{fileId}/content

Stream the bytes of a file attached to this run; 404 covers cross-tenant, other-client and unlinked ids.

GET /v1/runs/{runId}/workspace-files/{interactionId}/content

Stream a file this run wrote with its file tools; 404 covers cross-tenant, other-client, unknown and non-produced ids.

Read conversations back

GET /v1/conversations

One end user's conversations for the calling API-key client, most recently active first.

GET /v1/conversations/{conversationId}

One conversation's user and assistant text turns, in order; 404 unless it holds a run of this client for this end user.

Files

POST /v1/files

Upload a file in one multipart request; returns a file id usable as attachmentFileIds.

DELETE /v1/files/{id}

Delete a file your API client uploaded; 404 covers every file that is not.

Everything under API reference is generated from the API's own OpenAPI document, and a build gate fails if the two ever disagree — so what you read there is what the service does. The same page offers that document as a download.

Start here

  • Quickstart — Your first call in five minutes, with curl.
  • Build your product on Amy — The pattern for a product built on Amy, with a checklist that links every guide.
  • Set up your organisation — Sign-up, members, the model provider key, API keys and privacy: what to do before your first call.
  • Authentication — API keys, the X-Api-Key header, and what a key is scoped to.
  • Agents — The default agent, your own agents, and choosing one for a run.
  • Runs — Stream, await or submit — choosing how a run returns.
  • Streaming — The SSE event contract: every frame a run can emit.
  • Files — Send attachments into a run, and read what it produced.
  • Approvals — Pausing a run for a human decision, and resuming it.
  • Tools and MCP — Giving an agent your own tools over MCP: registering a server, naming tools on a run, and the per-run credential.
  • Webhooks — Signed events when a run finishes, fails or pauses: registering, verifying, retries and deduplication.
  • Usage — Where token usage and cost surface, and which number to read.
  • Limits — Rate limits, request sizes, per-run caps and the monthly token allowance, with what each looks like when hit.
  • Data and privacy — Memory and its scope, retention, erasing an end user, inference privacy and how secrets are handled.
  • Errors — ProblemDetails, in-band stream errors, and trace ids.
  • Versioning and support — /v1 stays stable, breaking changes come as /v2 with 90 days' notice, how to reach support, and the changes list.