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