Retrieve a paginated history of conversations for a specific chatbot, filterable by date range and source, with full message transcripts.
openapi: 3.0.1
info:
title: Chatbase API
description: >-
REST API for the Chatbase custom AI chatbot / AI agent platform. Message an
agent (with streaming), create and retrain chatbots/agents, update settings,
list and delete agents, manage agent images, retrieve conversation history
and captured leads, and manage contacts and their custom-attribute schema.
All requests are authenticated with a Bearer API key created in the Chatbase
dashboard under Workspace Settings -> API Keys.
termsOfService: https://www.chatbase.co/legal/terms
contact:
name: Chatbase Support
url: https://www.chatbase.co/docs
version: '1.0'
servers:
- url: https://www.chatbase.co/api/v1
security:
- bearerAuth: []
tags:
- name: Chat
description: Message an agent and receive a response, with optional streaming.
- name: Chatbots
description: Create, retrain, configure, list, and delete chatbots/agents.
- name: Conversations
description: Retrieve conversation history for a chatbot.
- name: Leads
description: Retrieve leads captured by a chatbot.
- name: Contacts
description: Manage contacts and custom attributes for a chatbot.
paths:
/chat:
post:
operationId: chat
tags:
- Chat
summary: Message an agent
description: >-
Send a message to a chatbot and receive a response. Provide the prior
turns in the messages array (roles user and assistant). Set stream=true
to receive the response word by word as a raw text stream instead of a
single JSON body.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatRequest'
responses:
'200':
description: The agent response. When stream=false a JSON body is returned; when stream=true the response is streamed as raw text.
content:
application/json:
schema:
$ref: '#/components/schemas/ChatResponse'
text/plain:
schema:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/create-chatbot:
post:
operationId: createChatbot
tags:
- Chatbots
summary: Create a chatbot
description: Create a new chatbot/agent and train it from the supplied sources.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateChatbotRequest'
responses:
'200':
description: The created chatbot.
content:
application/json:
schema:
$ref: '#/components/schemas/Chatbot'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/update-chatbot-data:
post:
operationId: updateChatbotData
tags:
- Chatbots
summary: Update and retrain a chatbot
description: >-
Update a chatbot, changing its name and/or replacing its training
material. The agent is retrained on the new content.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateChatbotDataRequest'
responses:
'200':
description: The updated chatbot.
content:
application/json:
schema:
$ref: '#/components/schemas/Chatbot'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/update-chatbot-settings:
post:
operationId: updateChatbotSettings
tags:
- Chatbots
summary: Update chatbot settings
description: Update configuration settings for an existing chatbot.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateChatbotSettingsRequest'
responses:
'200':
description: Confirmation of the updated settings.
content:
application/json:
schema:
$ref: '#/components/schemas/Chatbot'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/get-chatbots:
get:
operationId: getChatbots
tags:
- Chatbots
summary: List chatbots
description: Retrieve all chatbots for the authenticated account.
responses:
'200':
description: The list of chatbots on the account.
content:
application/json:
schema:
type: object
properties:
chatbots:
type: array
items:
$ref: '#/components/schemas/Chatbot'
'401':
$ref: '#/components/responses/Unauthorized'
/delete-chatbot:
delete:
operationId: deleteChatbot
tags:
- Chatbots
summary: Delete a chatbot
description: Permanently delete a chatbot and all of its associated data.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- chatbotId
properties:
chatbotId:
type: string
responses:
'200':
description: Deletion confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'401':
$ref: '#/components/responses/Unauthorized'
/get-conversations:
get:
operationId: getConversations
tags:
- Conversations
summary: Get conversations
description: >-
Retrieve conversations for a specific chatbot, optionally filtered by
date range and source, with pagination.
parameters:
- name: chatbotId
in: query
required: true
schema:
type: string
description: The ID of the chatbot to retrieve conversations for.
- name: startDate
in: query
required: false
schema:
type: string
format: date
description: Inclusive lower bound on conversation date (YYYY-MM-DD).
- name: endDate
in: query
required: false
schema:
type: string
format: date
description: Inclusive upper bound on conversation date (YYYY-MM-DD).
- name: filteredSources
in: query
required: false
schema:
type: string
description: Comma-separated list of sources to filter by (e.g. API, Widget or iframe).
- name: page
in: query
required: false
schema:
type: integer
default: 1
description: Page number for pagination.
- name: size
in: query
required: false
schema:
type: integer
default: 20
description: Number of conversations per page.
responses:
'200':
description: A paginated list of conversations.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Conversation'
'401':
$ref: '#/components/responses/Unauthorized'
/get-leads:
get:
operationId: getLeads
tags:
- Leads
summary: Get leads
description: Retrieve leads captured by a specific chatbot's lead form.
parameters:
- name: chatbotId
in: query
required: true
schema:
type: string
description: The ID of the chatbot to retrieve leads for.
- name: startDate
in: query
required: false
schema:
type: string
format: date
- name: endDate
in: query
required: false
schema:
type: string
format: date
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: size
in: query
required: false
schema:
type: integer
default: 20
responses:
'200':
description: A list of captured leads.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Lead'
'401':
$ref: '#/components/responses/Unauthorized'
/chatbots/{chatbotId}/contacts:
post:
operationId: createContacts
tags:
- Contacts
summary: Create contacts
description: Create one or more contacts for a chatbot (up to 1000 per request).
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
contacts:
type: array
maxItems: 1000
items:
$ref: '#/components/schemas/ContactInput'
responses:
'200':
description: The created contacts.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listContacts
tags:
- Contacts
summary: List contacts
description: Retrieve a paginated list of contacts for a chatbot.
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
- name: limit
in: query
required: false
schema:
type: integer
description: Maximum number of contacts to return per page.
- name: cursor
in: query
required: false
schema:
type: string
description: Cursor for fetching the next page of results.
responses:
'200':
description: A paginated list of contacts.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
'401':
$ref: '#/components/responses/Unauthorized'
/chatbots/{chatbotId}/contacts/{contactId}:
get:
operationId: getContact
tags:
- Contacts
summary: Get a contact
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
- $ref: '#/components/parameters/ContactIdPath'
responses:
'200':
description: The requested contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: updateContact
tags:
- Contacts
summary: Update a contact
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
- $ref: '#/components/parameters/ContactIdPath'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactInput'
responses:
'200':
description: The updated contact.
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteContact
tags:
- Contacts
summary: Delete a contact
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
- $ref: '#/components/parameters/ContactIdPath'
responses:
'200':
description: Deletion confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'401':
$ref: '#/components/responses/Unauthorized'
/chatbots/{chatbotId}/custom-attributes:
post:
operationId: createCustomAttribute
tags:
- Contacts
summary: Create a custom attribute
description: Define a new custom attribute on the contact schema for a chatbot.
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomAttribute'
responses:
'200':
description: The created custom attribute.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomAttribute'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getCustomAttributes
tags:
- Contacts
summary: Get the custom-attribute schema
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
responses:
'200':
description: The custom-attribute schema for contacts.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomAttribute'
'401':
$ref: '#/components/responses/Unauthorized'
/chatbots/{chatbotId}/custom-attributes/{name}:
put:
operationId: updateCustomAttribute
tags:
- Contacts
summary: Update a custom attribute
parameters:
- $ref: '#/components/parameters/ChatbotIdPath'
- name: name
in: path
required: true
schema:
type: string
description: The identifier of the custom attribute to update.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomAttribute'
responses:
'200':
description: The updated custom attribute.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomAttribute'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer API key created in the Chatbase dashboard (Workspace Settings -> API Keys).
parameters:
ChatbotIdPath:
name: chatbotId
in: path
required: true
schema:
type: string
description: The ID of the chatbot.
ContactIdPath:
name: contactId
in: path
required: true
schema:
type: string
description: The ID of the contact.
responses:
BadRequest:
description: The request was malformed or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Message:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- user
- assistant
description: Who sent the message. user is the human; assistant is the chatbot.
content:
type: string
description: The text content of the message.
ChatRequest:
type: object
required:
- messages
- chatbotId
properties:
messages:
type: array
description: The chat history. A maximum of the most recent messages is used as context.
items:
$ref: '#/components/schemas/Message'
chatbotId:
type: string
description: The ID of the chatbot/agent to message.
conversationId:
type: string
description: Optional ID of an existing conversation to continue.
stream:
type: boolean
default: false
description: When true, the response is streamed word by word as raw text.
temperature:
type: number
minimum: 0
maximum: 1
description: Sampling temperature controlling response randomness.
model:
type: string
description: Optional model override for this request.
ChatResponse:
type: object
properties:
text:
type: string
description: The agent's generated response.
conversationId:
type: string
description: The conversation this turn belongs to.
CreateChatbotRequest:
type: object
required:
- chatbotName
- sourceText
properties:
chatbotName:
type: string
description: Display name of the new chatbot.
sourceText:
type: string
description: Training text the agent is built from.
urlsToScrape:
type: array
items:
type: string
description: Optional list of URLs to crawl as training sources.
UpdateChatbotDataRequest:
type: object
required:
- chatbotId
properties:
chatbotId:
type: string
description: The ID of the chatbot to update.
chatbotName:
type: string
description: New display name for the chatbot.
sourceText:
type: string
description: Replacement training text; the agent is retrained on it.
UpdateChatbotSettingsRequest:
type: object
required:
- chatbotId
properties:
chatbotId:
type: string
chatbotName:
type: string
model:
type: string
temperature:
type: number
instructions:
type: string
description: System prompt / base instructions for the agent.
visibility:
type: string
enum:
- private
- public
Chatbot:
type: object
properties:
chatbotId:
type: string
chatbotName:
type: string
model:
type: string
temperature:
type: number
createdAt:
type: string
format: date-time
Conversation:
type: object
properties:
id:
type: string
chatbotId:
type: string
source:
type: string
description: Where the conversation originated (e.g. API, Widget or iframe).
createdAt:
type: string
format: date-time
messages:
type: array
items:
$ref: '#/components/schemas/Message'
Lead:
type: object
properties:
id:
type: string
chatbotId:
type: string
name:
type: string
email:
type: string
format: email
phone:
type: string
createdAt:
type: string
format: date-time
ContactInput:
type: object
properties:
name:
type: string
email:
type: string
format: email
phone:
type: string
customAttributes:
type: object
additionalProperties: true
description: Values for any custom attributes defined on the contact schema.
Contact:
allOf:
- $ref: '#/components/schemas/ContactInput'
- type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
CustomAttribute:
type: object
required:
- name
- type
properties:
name:
type: string
description: The attribute identifier.
type:
type: string
enum:
- text
- number
- boolean
- date
description: The data type of the attribute.
Status:
type: object
properties:
status:
type: string
example: success
message:
type: string
Error:
type: object
properties:
error:
type: string
message:
type: string