Versioning and support

What stays put, what may grow, how much notice you get, and where to ask for help.

The version is in the path

Every call your product makes starts with /v1. That prefix is the version of the contract in the API reference.

What we promise on /v1

/v1 stays stable. We make no breaking change inside /v1: a client written against these docs keeps working.

What counts as a breaking change

• removing or renaming an endpoint, a field, or a parameter;
• changing the type or the meaning of a field, a parameter or a value;
• a new input that a request must now carry.

What does not

These can appear in /v1 at any time, without a new version:

• a new endpoint under /v1;
• a new optional field on a request;
• a new field on a response, on a stream event, or inside a webhook's data;
• a new stream event type, a new webhook event type, a new run status or error code value.

That is why a client must ignore what it does not know — see Write a client that expects it.

When a breaking change comes

A breaking change ships as /v2, beside /v1. We give you at least 90 days' notice before /v1 is switched off, so you have time to move.

Write a client that expects it

• Ignore fields you do not know. Do not reject a response, or a webhook, because it has an extra property. If you validate with a schema, allow unknown keys.
• Skip event types you do not know. On a stream, read the event: line and ignore a type you do not handle — the streaming guide lists today's 13. For webhooks, answer 2xx for an event type you do not use, so it is not retried.
• Treat enums as open. Have a default branch for an unknown status or error code. Fall back to the HTTP status.
• Branch on codes, not on text. The title, detail and message wording can be improved at any time. The HTTP status, the code member and the field names are the contract. See Errors.
• Do not depend on order or on a field being absent. JSON property order is not meaningful, and a field that is null today may carry a value tomorrow.

Changes

A dated list of what is added to /v1, newest first. It starts with the surface as it stands when this page was written; the operations below are read from the same generated reference as the rest of these docs, so the list cannot disagree with the reference.

2026-10-15 — the documented surface

The 14 operations of /v1:

• GET /v1/organisation/inference-privacy — The calling API key's organisation's inference privacy verification.
• 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}.
• 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/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.
• 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.
• 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.

The run stream carries 13 event types, listed in the streaming guide; webhooks carry the events listed in Webhooks.

Support

Support is by email: [To be supplied: our general contact email address].

What we do not promise yet

There is no uptime or availability promise yet.