Ultimo API
The Ultimo API builds your agents into your own product: an intranet chat, a ticket system, a CRM workflow or your own app sends messages and gets the agent's answers, keeps your knowledge in sync and receives webhooks. It is a REST API with JSON and server-to-server keys.
What you can do
- Send messages and get the agent's answer as JSON, as a stream or asynchronously.
- Keep conversations under your own ids, read their history, mute the agent or delete them.
- Mirror your knowledge from a wiki, intranet or file store: websites, FAQs and documents.
- Read every conversation of an agent, from the website, WhatsApp and other channels.
- Take over leads into your CRM, or export leads and conversations as CSV.
- Report key figures per day and channel, and watch the AI credits.
- Manage agents their Business Context, widget design and embed code.
- Receive webhooks for new leads, handoffs, finished answers and knowledge imports.
The API is part of the Ultimo plan, per agent. Keys, permissions and access are explained in Authentication and keys; paging, errors, retries and limits in Conventions.
Your first request
Create an integration
In the portal, open the agents overview, click API in the sidebar, then + Integration. Give it a name, keep Chat only and copy the key. Never put the key into a website or app: it is for your server only.
Find your agent id
curl
curl https://api.ultimo-bots.com/v1/agents -H "Authorization: Bearer $ULTIMO_API_KEY"Send a message
curl https://api.ultimo-bots.com/v1/responses \ -H "Authorization: Bearer $ULTIMO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "YOUR_AGENT_ID", "input": "When are you open on Saturday?", "external_id": "ticket-4711", "end_user": {"id": "u-17", "name": "Anna"} }'import os, uuid, requests r = requests.post( "https://api.ultimo-bots.com/v1/responses", headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={"agent_id": "YOUR_AGENT_ID", "input": "When are you open on Saturday?", "external_id": "ticket-4711"}, timeout=130, ) body = r.json() if r.status_code != 200: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") print(body["output"]["text"])const res = await fetch("https://api.ultimo-bots.com/v1/responses", { method: "POST", headers: { Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() }, body: JSON.stringify({ agent_id: "YOUR_AGENT_ID", input: "When are you open on Saturday?", external_id: "ticket-4711" }) }); const answer = await res.json(); if (!res.ok) throw new Error(`${answer.error.code}: ${answer.error.message}`); console.log(answer.output.text);
The answer:
JSON
{
"id": "resp_6tZ0wq8Hn2cB3kQx1mJ4rV7y",
"object": "response",
"status": "completed",
"agent_id": "YOUR_AGENT_ID",
"conversation_id": "conv_9fK2pX7aQ1mL3sT8vW0yZ4bC",
"external_id": "ticket-4711",
"output": {"text": "On Saturday we are open from 9 am to 2 pm.", "format": "markdown", "language": "en"},
"handoff": {"requested": false, "status": null},
"input_message_id": "msg_0000000000081234",
"output_message_id": "msg_0000000000081235",
"end_user": {"id": "u-17", "name": "Anna"},
"metadata": {},
"usage": {"credits": 1},
"error": null
}Send the next message with the same external_id and the agent continues the conversation. Streams, async answers and conversations step by step: Send messages. Every field of the request and the answer: Responses reference.