API reference
All endpoints of version 1 under https://api.ultimo-bots.com/v1, grouped by topic. Each topic page describes every endpoint with its parameters, request and response fields, examples in curl, Python and Node.js, and its errors. The machine-readable contract is the OpenAPI file openapi.json: import it into Postman, Insomnia or an SDK generator.
Responses
| Endpoint | Purpose | Permission |
|---|---|---|
POST/v1/responses | Send a message | chat:write |
GET/v1/responses/{response_id} | Get a response | chat:write |
Conversations
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/conversations | List conversations | chat:write |
GET/v1/conversations/{conversation_id} | Get a conversation | chat:write |
GET/v1/conversations/{conversation_id}/messages | Conversation history | chat:write |
PUT/v1/conversations/{conversation_id}/auto-response | Switch answers on or off | chat:write |
DELETE/v1/conversations/{conversation_id} | Delete a conversation | chat:write |
Agents
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents | List agents | agents:read |
GET/v1/agents/{agent_id} | Get an agent | agents:read |
GET/v1/agents/{agent_id}/business-context | Read the Business Context | agents:context:read |
PUT/v1/agents/{agent_id}/business-context | Replace the Business Context | agents:context:write |
GET/v1/agents/{agent_id}/behaviors | Read the behavior rules | agents:behaviors:read |
Widget
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents/{agent_id}/widget | Widget settings | widget:read |
PATCH/v1/agents/{agent_id}/widget | Change the widget | widget:write |
GET/v1/agents/{agent_id}/embed | Embed code | widget:read |
Knowledge
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents/{agent_id}/knowledge | List knowledge sources | knowledge:read |
GET/v1/agents/{agent_id}/knowledge/{knowledge_id} | A knowledge source with content | knowledge:read |
POST/v1/agents/{agent_id}/knowledge | Add a source | knowledge:write |
POST/v1/agents/{agent_id}/knowledge/uploads | Prepare a file upload | knowledge:write |
PUT/v1/agents/{agent_id}/knowledge/{knowledge_id} | Change an FAQ or replace a document | knowledge:write |
DELETE/v1/agents/{agent_id}/knowledge/{knowledge_id} | Delete a source | knowledge:write |
POST/v1/agents/{agent_id}/knowledge/refresh | Read sources again | knowledge:write |
GET/v1/operations/{operation_id} | State of a long operation | knowledge:read |
All conversations
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents/{agent_id}/conversations | All conversations of an agent | conversations:read_all |
GET/v1/agents/{agent_id}/conversations/{reference}/messages | History of any conversation | conversations:read_all |
GET/v1/agents/{agent_id}/live-sessions | Open handoffs | livechat:read |
Leads and exports
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents/{agent_id}/leads | List leads | leads:read |
GET/v1/agents/{agent_id}/leads/{lead_id} | Get a lead | leads:read |
PATCH/v1/agents/{agent_id}/leads/{lead_id} | Mark a lead as read or unread | leads:write |
DELETE/v1/agents/{agent_id}/leads/{lead_id} | Delete a lead | leads:write |
POST/v1/agents/{agent_id}/exports | Export conversations or leads as CSV | exports:read |
Insights and credits
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/agents/{agent_id}/insights | Key figures | reports:read |
GET/v1/agents/{agent_id}/credits | AI credits and usage | credits:read |
Webhook endpoints
| Endpoint | Purpose | Permission |
|---|---|---|
GET/v1/webhook-endpoints | List webhook endpoints | webhooks:write |
POST/v1/webhook-endpoints | Create a webhook endpoint | webhooks:write |
GET/v1/webhook-endpoints/{endpoint_id} | Get a webhook endpoint | webhooks:write |
PATCH/v1/webhook-endpoints/{endpoint_id} | Change a webhook endpoint | webhooks:write |
DELETE/v1/webhook-endpoints/{endpoint_id} | Delete a webhook endpoint | webhooks:write |
POST/v1/webhook-endpoints/{endpoint_id}/test | Send a test event | webhooks:write |
POST/v1/webhook-endpoints/{endpoint_id}/rotate-secret | Rotate the signing secret | webhooks:write |
GET/v1/events | Events and their deliveries | webhooks:write |
POST/v1/events/{event_id}/resend | Send an event again | webhooks:write |
Webhook events
Answers, leads, handoffs, knowledge operations and AI credit warnings arrive as signed webhooks. Every event with its fields and an example: Webhook events.
Not in the API
Account, team, billing and checkout, credentials of other apps, connecting channels (it needs a sign-in with the provider in the browser), building skills (Mo in the AI Studio) and deleting agents or the account stay in the portal.