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.

1 min read Updated

Responses

EndpointPurposePermission
POST/v1/responsesSend a messagechat:write
GET/v1/responses/{response_id}Get a responsechat:write

All responses endpoints with fields and examples

Conversations

EndpointPurposePermission
GET/v1/conversationsList conversationschat:write
GET/v1/conversations/{conversation_id}Get a conversationchat:write
GET/v1/conversations/{conversation_id}/messagesConversation historychat:write
PUT/v1/conversations/{conversation_id}/auto-responseSwitch answers on or offchat:write
DELETE/v1/conversations/{conversation_id}Delete a conversationchat:write

All conversations endpoints with fields and examples

Agents

EndpointPurposePermission
GET/v1/agentsList agentsagents:read
GET/v1/agents/{agent_id}Get an agentagents:read
GET/v1/agents/{agent_id}/business-contextRead the Business Contextagents:context:read
PUT/v1/agents/{agent_id}/business-contextReplace the Business Contextagents:context:write
GET/v1/agents/{agent_id}/behaviorsRead the behavior rulesagents:behaviors:read

All agents endpoints with fields and examples

Widget

EndpointPurposePermission
GET/v1/agents/{agent_id}/widgetWidget settingswidget:read
PATCH/v1/agents/{agent_id}/widgetChange the widgetwidget:write
GET/v1/agents/{agent_id}/embedEmbed codewidget:read

All widget endpoints with fields and examples

Knowledge

EndpointPurposePermission
GET/v1/agents/{agent_id}/knowledgeList knowledge sourcesknowledge:read
GET/v1/agents/{agent_id}/knowledge/{knowledge_id}A knowledge source with contentknowledge:read
POST/v1/agents/{agent_id}/knowledgeAdd a sourceknowledge:write
POST/v1/agents/{agent_id}/knowledge/uploadsPrepare a file uploadknowledge:write
PUT/v1/agents/{agent_id}/knowledge/{knowledge_id}Change an FAQ or replace a documentknowledge:write
DELETE/v1/agents/{agent_id}/knowledge/{knowledge_id}Delete a sourceknowledge:write
POST/v1/agents/{agent_id}/knowledge/refreshRead sources againknowledge:write
GET/v1/operations/{operation_id}State of a long operationknowledge:read

All knowledge endpoints with fields and examples

All conversations

EndpointPurposePermission
GET/v1/agents/{agent_id}/conversationsAll conversations of an agentconversations:read_all
GET/v1/agents/{agent_id}/conversations/{reference}/messagesHistory of any conversationconversations:read_all
GET/v1/agents/{agent_id}/live-sessionsOpen handoffslivechat:read

All all conversations endpoints with fields and examples

Leads and exports

EndpointPurposePermission
GET/v1/agents/{agent_id}/leadsList leadsleads:read
GET/v1/agents/{agent_id}/leads/{lead_id}Get a leadleads:read
PATCH/v1/agents/{agent_id}/leads/{lead_id}Mark a lead as read or unreadleads:write
DELETE/v1/agents/{agent_id}/leads/{lead_id}Delete a leadleads:write
POST/v1/agents/{agent_id}/exportsExport conversations or leads as CSVexports:read

All leads and exports endpoints with fields and examples

Insights and credits

EndpointPurposePermission
GET/v1/agents/{agent_id}/insightsKey figuresreports:read
GET/v1/agents/{agent_id}/creditsAI credits and usagecredits:read

All insights and credits endpoints with fields and examples

Webhook endpoints

EndpointPurposePermission
GET/v1/webhook-endpointsList webhook endpointswebhooks:write
POST/v1/webhook-endpointsCreate a webhook endpointwebhooks:write
GET/v1/webhook-endpoints/{endpoint_id}Get a webhook endpointwebhooks:write
PATCH/v1/webhook-endpoints/{endpoint_id}Change a webhook endpointwebhooks:write
DELETE/v1/webhook-endpoints/{endpoint_id}Delete a webhook endpointwebhooks:write
POST/v1/webhook-endpoints/{endpoint_id}/testSend a test eventwebhooks:write
POST/v1/webhook-endpoints/{endpoint_id}/rotate-secretRotate the signing secretwebhooks:write
GET/v1/eventsEvents and their deliverieswebhooks:write
POST/v1/events/{event_id}/resendSend an event againwebhooks:write

All webhook endpoints endpoints with fields and examples

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.

Next steps