Skip to main content
The Public API lets you access your agent’s conversations, analytics, customers, and more programmatically. All endpoints are authenticated with an API key and return JSON responses.

API Reference (Swagger)

Browse the full API reference with request/response schemas and try endpoints directly.

​
Authentication

All API requests require a Bearer token in the Authorization header. The token is your agent’s API key. 
curl -H "Authorization: Bearer tb_pk_your_api_key_here" \
  https://api.totebot.ai/v1/agent

​
Generate an API Key

1

Open Settings

Navigate to Dashboard → Settings → API Key for your agent.
2

Generate Key

Click Generate API Key. Your key will be displayed once — copy it immediately and store it securely.
3

Use the Key

Include the key as a Bearer token in the Authorization header of every API request.
Treat your API key like a password. It provides full read access to your agent’s data. If compromised, revoke it immediately from Settings and generate a new one.

​
Rate Limits

The API allows 60 requests per 60 seconds per agent per IP address. If you exceed this limit, you’ll receive a 429 Too Many Requests response.

​
Endpoints

​
Agent

MethodEndpointDescription
GET/v1/agentGet agent info (name, model, training status)

​
Chat

MethodEndpointDescription
POST/v1/chatSend a message to the agent (streaming SSE response)
The chat endpoint accepts a message, optional conversationId to continue an existing conversation, and optional identity object for user tracking. Responses are streamed as Server-Sent Events with types: chunk, completed, tool_call, action_started, action_completed, error.

​
Conversations

MethodEndpointDescription
GET/v1/conversationsList conversations (paginated, with filters)
GET/v1/conversations/:conversationIdGet a single conversation with full data
GET/v1/conversations/:conversationId/messagesList messages only (lighter payload)
PATCH/v1/conversations/:conversationId/messages/:messageId/feedbackSubmit feedback (POSITIVE or NEGATIVE)
Filters for listing conversations: page, limit (max 250), startDate, endDate, source (PREVIEW, EMBED, TELEGRAM, WHATSAPP, EMAIL), sentiment (POSITIVE, NEGATIVE, NEUTRAL), product, purchased (yes/no), customerId.

​
Analytics

MethodEndpointDescription
GET/v1/analyticsChat opens, messages, unique users, cart adds, checkout initiations
GET/v1/analytics/revenueTotal revenue, order count, currency, daily breakdown
Both endpoints accept optional from and to query parameters (ISO 8601 dates) to filter by date range.

​
Insights

MethodEndpointDescription
GET/v1/insights/sentimentSentiment distribution (positive/negative/neutral counts and scores)
GET/v1/insights/intentsTop 3 conversation intents sorted by score
GET/v1/insights/productsProduct mentions with sentiment and frequency
GET/v1/insights/questionsTop questions grouped by semantic similarity

​
Customers

MethodEndpointDescription
GET/v1/customersList all customers who interacted with the agent
Supports sortBy parameter: a-z, z-a, oldest, newest.

​
Knowledge

MethodEndpointDescription
GET/v1/knowledgeList knowledge sources (documents, Q&A, links, text) with status

​
Orders

MethodEndpointDescription
GET/v1/ordersPaginated orders attributed to the agent
Supports skip (default 0) and take (1-250, default 20) query parameters.

​
Leads

MethodEndpointDescription
GET/v1/leadsList all leads captured by the agent

​
Emails

MethodEndpointDescription
GET/v1/emailsList emails collected through the chat widget

​
Integrations

MethodEndpointDescription
GET/v1/integrationsList all active integrations (channels and e-commerce)