Quickstart

One call, start to finish. Five minutes, no SDK.

1. Get a key

Every call is authenticated with a per-client API key, sent as X-Api-Key. Keys look like amy_live_<keyId>.<secret> and the secret half is shown exactly once, when the key is issued.

Create an account, then mint one yourself from Console → API keys: name it, optionally give it an expiry, and copy the key from the dialog. The secret is shown only once — if you lose it, revoke that key and create another; it cannot be recovered. Put it in your environment rather than in code:

shell 
export AMY_API_KEY="amy_live_…"

To rotate, create the next key before retiring the current one — both work until the old one is revoked or expires, so there is no cutover. Revoking takes effect on the key's very next request, so move your callers over first and wait for Last used on the old key to stop moving. That column is written at most once every five minutes, and the console page refreshes itself while you watch — so give it more than five minutes of stillness before you decide the key is idle.

2. Connect a model provider

Amy runs agents on a model provider you choose, with your own key for it. Before your first call, open Console → AI Providers, choose the Organization tab, add a key on the LLM tab and pick a default model. Skip this and the call below fails before it starts:

422 application/problem+json (shortened) 
{
  "title": "No AI provider configured.",
  "status": 422,
  "code": "no_provider_credential"
}

If your agreement includes Amy-provided model access, we enable it for your organisation and you can skip this step. The full walk-through, with the rest of the set-up, is Set up your organisation.

3. Make the call

The simplest shape is await: one request, one JSON answer, no streaming to handle. amy is the default coordinator agent; if your organisation has its own agents, use that slug instead.

request 
curl -X POST https://api.askamy.co.za/v1/agents/amy/runs/await \
  -H "X-Api-Key: $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "In one sentence: what is an agentic AI backend?",
    "endUserRef": "quickstart-1"
  }'

You get back the run id, the answer, and the coordinator’s token usage. For the run’s whole cost — delegation included — read GET /v1/runs/{runId}; see Usage.

200 application/json 
{
  "runId": "01936c2f-6d1a-7f60-9a53-2f0f1c9a77e1",
  "status": "completed",
  "message": "An agentic AI backend runs the reason-act loop for you…",
  "usage": { "inputTokens": 184, "outputTokens": 61, "totalTokens": 245 }
}

4. Stream it instead

Drop /await and the same run streams back as Server-Sent Events — tokens as the model produces them, plus every tool call it makes along the way. -N stops curl buffering.

request 
curl -N -X POST https://api.askamy.co.za/v1/agents/amy/runs \
  -H "X-Api-Key: $AMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Count to three, slowly."}'

Each frame is an event: line and a data: JSON payload. The streaming guide lists every event a run can emit.

5. When it goes wrong

A rejected key fails immediately, before any run starts, with a ProblemDetails body rather than a hang:

401 application/problem+json 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401
}

Once a stream has opened, an HTTP status can no longer change — so a failure after that point arrives in-band as an error event on a 200 response. That distinction is the one thing worth knowing before you write your error handling; see Errors.

Next