Chatbase

App · 23 actions

Manage Chatbase agents and knowledge sources, chat with agents, and search and export conversations.

Actions

ActionWhat it does
Chat with an agentSend a message to an agent and receive a response.
Clone agentCreate a full deep-clone of an agent, including all its sources (excluding Notion).
Create agentCreate a new agent.
Create sourceCreate a new source.
Delete agentPermanently deletes an agent and all its sources.
Delete sourceDelete a source.
Export conversationsExport all conversations with full message history for an agent.
Get a conversationGet conversation metadata and its most recent messages.
Get agentGet a single agent by ID.
Get sourceGet a single source by ID.
Get sources summaryGet aggregated counts and sizes for each source type, plus a flag if the chatbot knowledge base requires a retrain to reflect any changes
List agentsGet a paginated list of all agents for the authenticated account.
List conversation messagesList all messages in a conversation with cursor-based pagination.
List conversationsList conversations created through the API for an agent, ordered by createdAt date.
List conversations for a userList conversations created through the API for a specific user under an agent, ordered by last activity.
List sourcesGet a paginated list of sources for an agent.
Search conversationsSearch an agent's conversations by text, filters, or both.
Toggle auto-retrainEnables or disables automatic retraining.
Update agentPartially updates an agent.
Update agent stylesUpdate the visual styles for an agent.
Update conversation statusUpdate the activity state of a conversation.
Update message feedbackSet or clear feedback on an assistant message.
Update sourceUpdate 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

Agentagent_idtextRequired
The agent ID
MessagemessagetextRequired
The user message to send to the agent. Omit to continue the conversation after submitting a tool result.
Conversation IDconversation_idtext
Optional conversation ID to continue an existing conversation. If omitted, a new conversation will be started.
API user IDapi_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

Agentagent_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

NamenametextRequired
Agent name
URLurltext
Homepage URL of the product. The agent is pre-configured to answer questions about this website.
Instructionsinstructionstext
System prompt / instructions for the agent (max 30,000 characters)
Modelmodeltext
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.
Temptempnumber
Model temperature (0 to 1)From 0.0 to 1.0.
Visibilityvisibilitytext
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

Agentagent_idtextRequired
The agent ID
TypetypetextRequired
Type.One of: text, qna, link.
Namenametext
Name.Only when Type is text or qna.
Contentcontenttext
Content.Only when Type is text.
Questionsquestionslist
Questions.Only when Type is qna.
Answeranswertext
Answer.Only when Type is qna.
URLurltext
Url.Only when Type is link.
Link typelink_typetext
Link type.Only when Type is link. One of: individual, sitemap, crawl.
Exclude pathsexclude_pathslist
Exclude paths.Only when Type is link.
Include only pathsinclude_only_pathslist
Include only paths.Only when Type is link.
Slow scrapingslow_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

Agentagent_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

Agentagent_idtextRequired
The agent ID
Source IDsource_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

Agentagent_idtextRequired
The agent ID
Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
Number of items per page (1 to 20, default 20)From 1.0 to 20.0.
Start datestart_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 dateend_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 IDconversation_idtext
Return only the conversation with this ID. Use this to fetch a single conversation from any source (widget, API, WhatsApp, etc.).
Includeincludetext
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.
Sourcesourcetext
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

Agentagent_idtextRequired
The agent ID
Conversation IDconversation_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

Agentagent_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

Agentagent_idtextRequired
The agent ID
Source IDsource_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

Agentagent_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

Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
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

Agentagent_idtextRequired
The agent ID
Conversation IDconversation_idtextRequired
The conversation ID
Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
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

Agentagent_idtextRequired
The agent ID
Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
Start datestart_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 dateend_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

Agentagent_idtextRequired
The agent ID
API user IDapi_user_idtextRequired
The user ID (URL-safe characters only: letters, digits, hyphens, underscores, dots)
Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
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

Agentagent_idtextRequired
The agent ID
Cursorcursortext
Opaque cursor from a previous response to fetch the next page
Limitlimitnumber
Number of items per page (1 to 100, default 20)From 1.0 to 100.0.
Typetypetext
Comma-separated source types to filter by. Allowed values: link, file, qna, notionPage, text
Namenametext
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

Agentagent_idtextRequired
The agent ID
Start datestart_datedate and time
Created at or after this point (YYYY-MM-DD or ISO 8601). Must be inside the searchable window.
End dateend_datedate and time
Created at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
Queryquerytext
Free-text search over messages and titles.
Sourcesourcetext
Comma-separated sources, e.g. API,WhatsApp.
Sentimentsentimenttext
Comma-separated: positive, neutral, negative, or unspecified for none.
Topictopictext
Comma-separated topic names, or unspecified for none.
API user IDapi_user_idtext
Comma-separated user IDs.
Activity stateactivity_statetext
Comma-separated: ongoing, ended, taken_over, paused.
Feedbackfeedbacktext
Comma-separated message ratings: positive, negative.
Escalatedescalatedtext
true: only conversations escalated to a human (ticket or live-chat handoff).One of: true.
Action typeaction_typetext
Comma-separated action types that ran, e.g. collect-leads.
Tooltooltext
Comma-separated tool names that were called.
Tool outcometool_outcometext
Comma-separated tool result statuses, e.g. error. Scoped to tool when set.
Procedureproceduretext
Comma-separated procedure names that ran.
Procedure outcomeprocedure_outcometext
Comma-separated procedure run statuses. Scoped to procedure when set.
Has voicehas_voicetext
Whether a voice session took place.One of: true, false.
Updated afterupdated_afterdate and time
Last active at or after this point (YYYY-MM-DD or ISO 8601).
Updated beforeupdated_beforedate and time
Last active at or before this point (YYYY-MM-DD, inclusive, or ISO 8601).
Cursorcursortext
pagination.cursor from the previous page. Keep the other parameters unchanged.
Limitlimitnumber
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

Agentagent_idtextRequired
The agent ID
Enabledenabledtrue/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

Agentagent_idtextRequired
The agent ID
Namenametext
Agent name
Instructionsinstructionstext
System prompt (max 30,000 characters)
Channel instructionschannel_instructionsobject
Per-channel instruction overrides (max 30,000 characters each)
Modelmodeltext
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.
Temptempnumber
Temperature (0 to 1)From 0.0 to 1.0.
Visibilityvisibilitytext
VisibilityOne of: public, private.
Allowed domainsallowed_domainslist
Allowed embed domains
Suggested messagessuggested_messageslist
Suggested messages
Initial messagesinitial_messageslist
Initial messages
Credit limitcredit_limitnumber
Per-agent credit limit (null = no limit)
Notifications settingsnotifications_settingsobject
Email notification settings (null = disable all notifications)
IP rate limitsip_rate_limitsobject
IP-based rate limit settings (partial update; null = reset to defaults)
Spam settingsspam_settingsobject
Spam detection settings (null = disable spam detection)
Voice settingsvoice_settingsobject
Voice mode configuration (null = disable voice mode)
Blocked countriesblocked_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

Agentagent_idtextRequired
The agent ID
StylesstylesobjectRequired
Styles.

Outputs

responseobject
Response.
Example output
{
  "response": {
    "success": true
  }
}

Update conversation status

Update the activity state of a conversation.

Inputs

Agentagent_idtextRequired
The agent ID
Conversation IDconversation_idtextRequired
The conversation ID
StatusstatustextRequired
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

Agentagent_idtextRequired
The agent ID
Conversation IDconversation_idtextRequired
The conversation ID
Message IDmessage_idtextRequired
The message ID
FeedbackfeedbacktextRequired
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

Agentagent_idtextRequired
The agent ID
Source IDsource_idtextRequired
The source ID
Namenametext
Name.
Contentcontenttext
Content.
Questionsquestionslist
Questions.
Answeranswertext
Answer.
Exclude pathsexclude_pathslist
Exclude paths.
Include only pathsinclude_only_pathslist
Include only paths.
Slow scrapingslow_scrapingtrue/false
Slow scraping.

Outputs

responseobject
Response.
Example output
{
  "response": {
    "createdAt": "example",
    "id": "example",
    "metadata": {},
    "name": "example",
    "size": 1,
    "status": "untrained",
    "type": "link"
  }
}

On this page