Chatbase
App · 23 actions
Manage Chatbase agents and knowledge sources, chat with agents, and search and export conversations.
Actions
| Action | What it does |
|---|---|
| Chat with an agent | Send a message to an agent and receive a response. |
| Clone agent | Create a full deep-clone of an agent, including all its sources (excluding Notion). |
| Create agent | Create a new agent. |
| Create source | Create a new source. |
| Delete agent | Permanently deletes an agent and all its sources. |
| Delete source | Delete a source. |
| Export conversations | Export all conversations with full message history for an agent. |
| Get a conversation | Get conversation metadata and its most recent messages. |
| Get agent | Get a single agent by ID. |
| Get source | Get a single source by ID. |
| Get sources summary | Get aggregated counts and sizes for each source type, plus a flag if the chatbot knowledge base requires a retrain to reflect any changes |
| List agents | Get a paginated list of all agents for the authenticated account. |
| List conversation messages | List all messages in a conversation with cursor-based pagination. |
| List conversations | List conversations created through the API for an agent, ordered by createdAt date. |
| List conversations for a user | List conversations created through the API for a specific user under an agent, ordered by last activity. |
| List sources | Get a paginated list of sources for an agent. |
| Search conversations | Search an agent's conversations by text, filters, or both. |
| Toggle auto-retrain | Enables or disables automatic retraining. |
| Update agent | Partially updates an agent. |
| Update agent styles | Update the visual styles for an agent. |
| Update conversation status | Update the activity state of a conversation. |
| Update message feedback | Set or clear feedback on an assistant message. |
| Update source | Update an existing source. |
Chat with an agent
Send a message to an agent and receive a response. Supports streaming responses when stream: true is set in the request body.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Message
messagetextRequired - The user message to send to the agent. Omit to continue the conversation after submitting a tool result.
- Conversation ID
conversation_idtext - Optional conversation ID to continue an existing conversation. If omitted, a new conversation will be started.
- API user ID
api_user_idtext - Optional user ID to associate with a new conversation. Only applied when creating a new conversation (no conversationId). Once set, a conversation's userId is immutable , this field is ignored for existing conversations. Must contain only URL-safe characters (letters, digits, hyphens, underscores, dots).
Outputs
responseobject- Response.
Example output
{
"response": {
"data": {
"id": "example",
"metadata": {
"conversationId": "example",
"finishReason": "stop",
"usage": {
"credits": 1
},
"userId": "example",
"userMessageId": "example"
},
"parts": [],
"role": "assistant"
}
}
}Clone agent
Create a full deep-clone of an agent, including all its sources (excluding Notion). Returns the new agent ID.
Inputs
- Agent
agent_idtextRequired - The agent ID
Outputs
responseobject- Response.
Example output
{
"response": {
"id": "example",
"pendingSteps": []
}
}Create agent
Create a new agent. If url is provided, a link source is created from that URL and training is queued automatically.
Inputs
- Name
nametextRequired - Agent name
- URL
urltext - Homepage URL of the product. The agent is pre-configured to answer questions about this website.
- Instructions
instructionstext - System prompt / instructions for the agent (max 30,000 characters)
- Model
modeltext - AI model to useOne of:
gpt-oss-120b,gpt-oss-20b,gpt-5.2,gpt-5.5,gpt-5.6-terra,gpt-6.1-sol,gpt-6-luna,claude-opus-5-5,claude-sonnet-5-5,claude-haiku-5-5, and 18 more. - Temp
tempnumber - Model temperature (0 to 1)From 0.0 to 1.0.
- Visibility
visibilitytext - Agent visibility (default: private)One of:
public,private.
Outputs
responseobject- Response.
Example output
{
"response": {
"id": "example",
"pendingSteps": []
}
}Create source
Create a new source. Accepts text, qna, and link source types. File sources require a dedicated endpoint. Ticket and Notion sources are not accepted. The source starts training immediately, so no separate training call is needed. It is returned as untrained and flips to trained when it is live, or failed if training did not land; poll GET /agents/{agentId}/sources/{sourceId} to follow it.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Type
typetextRequired - Type.One of:
text,qna,link. - Name
nametext - Name.Only when Type is text or qna.
- Content
contenttext - Content.Only when Type is text.
- Questions
questionslist - Questions.Only when Type is qna.
- Answer
answertext - Answer.Only when Type is qna.
- URL
urltext - Url.Only when Type is link.
- Link type
link_typetext - Link type.Only when Type is link. One of:
individual,sitemap,crawl. - Exclude paths
exclude_pathslist - Exclude paths.Only when Type is link.
- Include only paths
include_only_pathslist - Include only paths.Only when Type is link.
- Slow scraping
slow_scrapingtrue/false - Slow scraping.Only when Type is link.
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": "example",
"id": "example",
"metadata": {},
"name": "example",
"size": 1,
"status": "untrained",
"type": "link"
}
}Delete agent
Permanently deletes an agent and all its sources. Also disconnects any active integrations (Slack, WhatsApp, etc.). This action is irreversible.
Inputs
- Agent
agent_idtextRequired - The agent ID
Outputs
responseobject- Response.
Example output
{
"response": {
"success": true
}
}Delete source
Delete a source. Its knowledge is removed from the agent immediately; the response carries the final state (deleted, or toBeDeleted while the purge finishes).
Inputs
- Agent
agent_idtextRequired - The agent ID
- Source ID
source_idtextRequired - The source ID
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": "example",
"id": "example",
"metadata": {},
"name": "example",
"size": 1,
"status": "untrained",
"type": "link"
}
}Export conversations
Export all conversations with full message history for an agent. Includes conversations from all sources. Tool results are sanitized to remove internal data. Supports cursor-based pagination. Pass conversationId to fetch a single conversation from any source (widget, API, WhatsApp, etc.). Pass include=summary to omit message bodies for a cheaper triage pass, source to restrict to one or more conversation sources, and startDate / endDate to restrict to a createdAt window. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 20, default 20)From 1.0 to 20.0.
- Start date
start_datedate and time - Only return conversations created at or after this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the start of that day in UTC) or an ISO 8601 date-time.
- End date
end_datedate and time - Only return conversations created at or before this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.
- Conversation ID
conversation_idtext - Return only the conversation with this ID. Use this to fetch a single conversation from any source (widget, API, WhatsApp, etc.).
- Include
includetext - Whether to include message bodies. summary omits them and skips reading them from the database , use it to triage a page cheaply, then re-request a specific conversation with conversationId. Defaults to messages.One of:
summary,messages. - Source
sourcetext - Comma-separated conversation sources to include, e.g. API,WhatsApp. Omit for all sources.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}Get a conversation
Get conversation metadata and its most recent messages. The pagination cursor can be used with the list messages endpoint to fetch older messages. Only returns conversations created through the API. To fetch a conversation from any source (widget, WhatsApp, etc.), use GET /agents/{agentId}/conversations/export?conversationId={conversationId} instead.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Conversation ID
conversation_idtextRequired - The conversation ID
Outputs
responseobject- Response.
Example output
{
"response": {
"data": {
"createdAt": 1,
"id": "example",
"messages": [],
"parentConversationId": "example",
"parentSummary": "example",
"status": "ongoing",
"title": "example",
"updatedAt": 1,
"userId": "example"
},
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}Get agent
Get a single agent by ID.
Inputs
- Agent
agent_idtextRequired - The agent ID
Outputs
responseobject- Response.
Example output
{
"response": {
"allowedDomains": [],
"autoRetrain": false,
"blockedCountries": [],
"channelInstructions": {
"android_sdk": "example",
"api": "example",
"center_stage": "example",
"chat_widget": "example",
"email": "example",
"help_page": "example",
"instagram": "example",
"ios_sdk": "example",
"messenger": "example",
"phone": "example",
"salesforce": "example",
"search": "example",
"side_panel": "example",
"slack": "example",
"whatsapp": "example",
"zendesk": "example",
"zendesk_messaging": "example"
},
"createdAt": "example",
"creditLimit": 1,
"creditsUsed": 1,
"id": "example",
"initialMessages": [],
"instructions": "example",
"ipRateLimits": {
"limit": 1,
"message": "example",
"timeframe": 1
},
"lastMessageAt": "example",
"lastTrainedAt": "example",
"model": "gpt-4o",
"name": "example",
"notificationsSettings": {
"dailyConversations": {
"active": false,
"emails": []
},
"dailyLeadsCollected": {
"active": false,
"emails": []
}
},
"size": 1,
"spamSettings": {
"enabled": false,
"prompt": "example"
},
"status": "untrained",
"styles": {
"centerStage": {
"accentColorEnabled": false,
"accentSyncWithIcon": false,
"closeOnOutsideClick": false,
"dismissableNotice": "example",
"displayName": "example",
"enabled": false,
"footer": "example",
"headerColor": "example",
"messagePlaceholder": "example",
"showAttachments": false,
"showChatBubble": false,
"showCopyButton": false,
"showDataSource": false,
"showDictation": false,
"showFeedback": false,
"showVoiceMode": false,
"suggestedMessages": [],
"theme": "light",
"tintedGrayscale": {
"enabled": false,
"hue": 0,
"shade": -4,
"tint": 0
},
"typography": {
"fontFamily": "example",
"fontSize": "example"
},
"userMessageColor": "example",
"welcomeMessage": "example"
},
"chat": {
"alignChatButton": "left",
"autoOpenChatWindowAfter": 1,
"buttonColor": "example",
"dismissableNotice": "example",
"displayName": "example",
"footer": "example",
"headerColor": "example",
"messagePlaceholder": "example",
"mobile": {
"autoOpenChatWindowAfter": {
"enabled": false,
"value": 1
},
"initialMessages": {
"enabled": false,
"value": []
},
"showAutoOpen": false
},
"showAttachments": false,
"showCopyButton": false,
"showDictation": false,
"showFeedback": false,
"showVoiceMode": false,
"theme": "light",
"userMessageColor": "example"
}
},
"suggestedMessages": [],
"temp": 0,
"visibility": "public",
"voiceSettings": {
"allowInterruptions": false,
"allowTextInput": false,
"endConversationAfterSilenceSeconds": 10,
"errorMessage": "example",
"initialMessage": "example",
"maxCallDurationSeconds": 1,
"maxConcurrentSessions": 1,
"maxDailyCallsPerUser": 1,
"model": "gpt-4o",
"recordings": {
"enabled": false,
"retentionDays": 0
},
"temperature": 0,
"transcriber": {
"activationThreshold": 0,
"language": "example",
"minSilenceDuration": 0.1,
"model": "example"
},
"voice": {
"instructions": "example",
"similarity": 0,
"speed": 0.7,
"stability": 0,
"voiceName": "example"
}
}
}
}Get source
Get a single source by ID.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Source ID
source_idtextRequired - The source ID
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": "example",
"id": "example",
"metadata": {},
"name": "example",
"size": 1,
"status": "untrained",
"type": "link"
}
}Get sources summary
Get aggregated counts and sizes for each source type, plus a flag if the chatbot knowledge base requires a retrain to reflect any changes
Inputs
- Agent
agent_idtextRequired - The agent ID
Outputs
responseobject- Response.
Example output
{
"response": {
"files": {
"count": 1,
"size": 1
},
"links": {
"count": 1,
"size": 1
},
"notionPages": {
"count": 1,
"size": 1
},
"qnas": {
"count": 1,
"size": 1
},
"salesforceCases": {
"count": 1,
"size": 1
},
"shouldRetrain": false,
"texts": {
"count": 1,
"size": 1
},
"zendeskTickets": {
"count": 1,
"size": 1
}
}
}List agents
Get a paginated list of all agents for the authenticated account. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}List conversation messages
List all messages in a conversation with cursor-based pagination. Messages are returned in chronological order within each page, paginating backward from newest. The cursor from the get-conversation endpoint works here. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Conversation ID
conversation_idtextRequired - The conversation ID
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}List conversations
List conversations created through the API for an agent, ordered by createdAt date. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations or Export conversations for those. Supports cursor-based pagination. Pass startDate and/or endDate to restrict the results to a createdAt window. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
- Start date
start_datedate and time - Only return conversations created at or after this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the start of that day in UTC) or an ISO 8601 date-time.
- End date
end_datedate and time - Only return conversations created at or before this point. Accepts a calendar date (YYYY-MM-DD, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}List conversations for a user
List conversations created through the API for a specific user under an agent, ordered by last activity. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations with userId to find them, and Export conversations to read their messages. Supports cursor-based pagination. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- API user ID
api_user_idtextRequired - The user ID (URL-safe characters only: letters, digits, hyphens, underscores, dots)
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}List sources
Get a paginated list of sources for an agent. Ticket sources are excluded. For link sources only individual or sitemap/crawl parent links are returned with aggregated children metadata. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Cursor
cursortext - Opaque cursor from a previous response to fetch the next page
- Limit
limitnumber - Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
- Type
typetext - Comma-separated source types to filter by. Allowed values: link, file, qna, notionPage, text
- Name
nametext - Partial (case-insensitive) name match
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false,
"total": 1
}
}
}Search conversations
Search an agent's conversations by text, filters, or both. With query, results are ranked and carry a highlighted snippet; without it, most recently active first. Filters combine with AND; comma-separated values within a filter with OR. Covers conversations created since the 1st of the month 12 months ago (UTC), activity-date filters included. Results lag new messages by a few seconds. A page can hold fewer than limit items, even none, while hasMore is true; keep paging. Read messages via export with conversationId. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Start date
start_datedate and time - Created at or after this point (YYYY-MM-DD or ISO 8601). Must be inside the searchable window.
- End date
end_datedate and time - Created at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
- Query
querytext - Free-text search over messages and titles.
- Source
sourcetext - Comma-separated sources, e.g. API,WhatsApp.
- Sentiment
sentimenttext - Comma-separated: positive, neutral, negative, or unspecified for none.
- Topic
topictext - Comma-separated topic names, or unspecified for none.
- API user ID
api_user_idtext - Comma-separated user IDs.
- Activity state
activity_statetext - Comma-separated: ongoing, ended, taken_over, paused.
- Feedback
feedbacktext - Comma-separated message ratings: positive, negative.
- Escalated
escalatedtext - true: only conversations escalated to a human (ticket or live-chat handoff).One of:
true. - Action type
action_typetext - Comma-separated action types that ran, e.g. collect-leads.
- Tool
tooltext - Comma-separated tool names that were called.
- Tool outcome
tool_outcometext - Comma-separated tool result statuses, e.g. error. Scoped to tool when set.
- Procedure
proceduretext - Comma-separated procedure names that ran.
- Procedure outcome
procedure_outcometext - Comma-separated procedure run statuses. Scoped to procedure when set.
- Has voice
has_voicetext - Whether a voice session took place.One of:
true,false. - Updated after
updated_afterdate and time - Last active at or after this point (YYYY-MM-DD or ISO 8601).
- Updated before
updated_beforedate and time - Last active at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
- Cursor
cursortext - pagination.cursor from the previous page. Keep the other parameters unchanged.
- Limit
limitnumber - Items per page (1 to 25, default 25)From 1.0 to 25.0.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": [],
"pagination": {
"cursor": "example",
"hasMore": false
}
}
}Toggle auto-retrain
Enables or disables automatic retraining. When enabled, the agent retrains every 7 days to reflect any source changes.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Enabled
enabledtrue/falseRequired - true = retrain every 7 days, false = never
Outputs
responseobject- Response.
Example output
{
"response": {
"success": true
}
}Update agent
Partially updates an agent. Only provided fields are changed.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Name
nametext - Agent name
- Instructions
instructionstext - System prompt (max 30,000 characters)
- Channel instructions
channel_instructionsobject - Per-channel instruction overrides (max 30,000 characters each)
- Model
modeltext - AI modelOne of:
gpt-oss-120b,gpt-oss-20b,gpt-5.2,gpt-5.5,gpt-5.6-terra,gpt-6.1-sol,gpt-6-luna,claude-opus-5-5,claude-sonnet-5-5,claude-haiku-5-5, and 18 more. - Temp
tempnumber - Temperature (0 to 1)From 0.0 to 1.0.
- Visibility
visibilitytext - VisibilityOne of:
public,private. - Allowed domains
allowed_domainslist - Allowed embed domains
- Suggested messages
suggested_messageslist - Suggested messages
- Initial messages
initial_messageslist - Initial messages
- Credit limit
credit_limitnumber - Per-agent credit limit (null = no limit)
- Notifications settings
notifications_settingsobject - Email notification settings (null = disable all notifications)
- IP rate limits
ip_rate_limitsobject - IP-based rate limit settings (partial update; null = reset to defaults)
- Spam settings
spam_settingsobject - Spam detection settings (null = disable spam detection)
- Voice settings
voice_settingsobject - Voice mode configuration (null = disable voice mode)
- Blocked countries
blocked_countrieslist - ISO 3166-1 alpha-2 country codes to block (null = remove all blocking)
Outputs
responseobject- Response.
Example output
{
"response": {
"success": true
}
}Update agent styles
Update the visual styles for an agent.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Styles
stylesobjectRequired - Styles.
Outputs
responseobject- Response.
Example output
{
"response": {
"success": true
}
}Update conversation status
Update the activity state of a conversation.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Conversation ID
conversation_idtextRequired - The conversation ID
- Status
statustextRequired - Target activity state for the conversationOne of:
ongoing,paused,ended.
Outputs
responseobject- Response.
Example output
{
"response": {
"data": {
"id": "example",
"status": "ongoing"
}
}
}Update message feedback
Set or clear feedback on an assistant message. Use "positive" or "negative" to set feedback, or null to remove existing feedback.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Conversation ID
conversation_idtextRequired - The conversation ID
- Message ID
message_idtextRequired - The message ID
- Feedback
feedbacktextRequired - Set feedback: "positive", "negative", or null to clear
Outputs
responseobject- Response.
Example output
{
"response": {
"data": {
"createdAt": 1,
"feedback": "positive",
"id": "example",
"metadata": {
"score": 1
},
"parts": [],
"role": "user"
}
}
}Update source
Update an existing source. Accepts text, qna, and link sources. File sources require a dedicated endpoint. A content change retrains the source immediately (status updated until it is live again). Link URL is immutable, so to change it, delete and recreate the source. Ticket and Notion sources are not accepted.
Inputs
- Agent
agent_idtextRequired - The agent ID
- Source ID
source_idtextRequired - The source ID
- Name
nametext - Name.
- Content
contenttext - Content.
- Questions
questionslist - Questions.
- Answer
answertext - Answer.
- Exclude paths
exclude_pathslist - Exclude paths.
- Include only paths
include_only_pathslist - Include only paths.
- Slow scraping
slow_scrapingtrue/false - Slow scraping.
Outputs
responseobject- Response.
Example output
{
"response": {
"createdAt": "example",
"id": "example",
"metadata": {},
"name": "example",
"size": 1,
"status": "untrained",
"type": "link"
}
}