openapi: 3.0.3
info:
  title: Chatbase API v1
  description: >
    Comprehensive API documentation for all Chatbase v1 endpoints.


    ## Authentication

    All endpoints require authentication using a Bearer token in the
    Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```
  version: 1.0.0
  contact:
    name: Chatbase Support
    url: https://chatbase.co/help
servers:
  - url: https://www.chatbase.co/api/v1
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Chatbots
    description: Chatbot management operations
  - name: Chat
    description: Chat conversation endpoints
  - name: Conversations
    description: Conversation history and management
  - name: Leads
    description: Lead collection and management
  - name: Contacts
    description: Contact management for chatbots
  - name: Assets
    description: File upload and management
paths:
  /chat:
    post:
      tags:
        - Chat
      summary: Chat with a chatbot
      x-mint:
        content: >
          <Note>

          **Looking for API v2?** The new Chatbase API v2 features structured
          error codes, cursor-based pagination, and SSE streaming. Note that API
          v2 is available starting from the Standard Plan. [Check out the API v2
          Reference →](/api-v2/overview)

          </Note>
      description: >
        Send a message to a chatbot and receive a response. Supports streaming
        responses.

        Can continue existing conversations by providing a conversationId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chatbotId
                - messages
              properties:
                chatbotId:
                  type: string
                  description: ID of the chatbot to chat with
                  example: ckl123abc456
                messages:
                  type: array
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                        description: Message sender role
                        example: user
                      content:
                        type: string
                        description: Message content
                        example: Hello, I need help with my order
                  description: Array of messages in the conversation
                conversationId:
                  type: string
                  description: >-
                    ID of existing conversation to continue, if not provided,
                    the conversation will not be saved
                  example: conv_abc123
                contactId:
                  type: string
                  description: External ID of the contact/user
                  example: user_123
                model:
                  $ref: '#/components/schemas/AIModel'
                temperature:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Temperature setting for AI response creativity
                  example: 0.7
                stream:
                  type: boolean
                  description: Whether to stream the response
                  default: false
      responses:
        '200':
          description: Chat response
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The chatbot's response text
                    example: Hello! How can I help you today?
            text/plain:
              schema:
                type: string
                description: Streaming response (when stream=true)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /create-chatbot:
    post:
      tags:
        - Chatbots
      summary: Create a new chatbot
      description: Creates a new chatbot with training data from text
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chatbotName
              properties:
                chatbotName:
                  type: string
                  minLength: 3
                  description: Name of the chatbot (minimum 3 characters)
                  example: Customer Support Bot
                sourceText:
                  type: string
                  description: Raw text content to train the chatbot
                  example: Welcome to our company...
      responses:
        '200':
          description: Chatbot created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chatbotId:
                    type: string
                    description: Unique identifier for the created chatbot
                    example: ckl123abc456
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /get-chatbots:
    get:
      tags:
        - Chatbots
      summary: Get all chatbots
      description: Retrieves all chatbots for the authenticated account
      responses:
        '200':
          description: List of chatbots retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chatbots:
                    type: array
                    items:
                      $ref: '#/components/schemas/Chatbot'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /get-conversations:
    get:
      tags:
        - Conversations
      summary: Get conversations for a chatbot
      x-mint:
        content: >
          <Note>

          **Looking for API v2?** The new Chatbase API v2 features structured
          error codes, cursor-based pagination, and SSE streaming. [Check out
          the API v2 Reference →](/api-v2/overview)

          </Note>
      description: Retrieves conversation history for a specific chatbot
      parameters:
        - name: chatbotId
          in: query
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: filteredSources
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated list of conversation sources to filter by. Example
            API,WhatsApp,Messenger,Instagram,Slack,Playground,Action
            preview,Widget or Iframe
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for conversation filtering (YYYY-MM-DD)
          example: '2024-01-01'
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for conversation filtering (YYYY-MM-DD)
          example: '2024-12-31'
        - name: page
          in: query
          required: false
          schema:
            type: string
          description: Page number for pagination
          example: '1'
        - name: size
          in: query
          required: false
          schema:
            type: string
          description: Number of items per page
          example: '10'
      responses:
        '200':
          description: Conversations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /get-leads:
    get:
      tags:
        - Leads
      summary: Get leads for a chatbot
      description: Retrieves collected leads/customers for a specific chatbot
      parameters:
        - name: chatbotId
          in: query
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for lead filtering (YYYY-MM-DD)
          example: '2024-01-01'
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for lead filtering (YYYY-MM-DD)
          example: '2024-12-31'
        - name: page
          in: query
          required: false
          schema:
            type: string
          description: Page number for pagination
          example: '1'
        - name: size
          in: query
          required: false
          schema:
            type: string
          description: Number of items per page
          example: '10'
      responses:
        '200':
          description: Leads retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  collectedCustomers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /delete-chatbot:
    delete:
      tags:
        - Chatbots
      summary: Delete a chatbot
      description: Permanently deletes a chatbot and all associated data
      parameters:
        - name: chatbotId
          in: query
          required: true
          schema:
            type: string
          description: ID of the chatbot to delete
          example: ckl123abc456
      responses:
        '200':
          description: Chatbot deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /update-chatbot-data:
    post:
      tags:
        - Chatbots
      summary: Update a chatbot
      description: Updates and retrains a chatbot with new content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chatbotId
                - chatbotName
              properties:
                chatbotId:
                  type: string
                  description: ID of the chatbot to update
                  example: ckl123abc456
                chatbotName:
                  type: string
                  minLength: 3
                  description: Updated name for the chatbot
                  example: Updated Bot Name
                sourceText:
                  type: string
                  description: New training text content
                  example: Updated training content...
      responses:
        '200':
          description: Chatbot updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chatbotId:
                    type: string
                    example: ckl123abc456
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /update-chatbot-settings:
    post:
      tags:
        - Chatbots
      summary: Update chatbot settings
      description: Updates various chatbot configuration settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chatbotId
              properties:
                chatbotId:
                  type: string
                  description: ID of the chatbot to update
                  example: ckl123abc456
                name:
                  type: string
                  description: Chatbot name
                  example: My Chatbot
                instructions:
                  type: string
                  description: System instructions for the chatbot
                  example: You are a helpful customer service assistant
                initialMessages:
                  type: array
                  items:
                    type: string
                  description: Initial greeting messages
                  example:
                    - Hello! How can I help you?
                suggestedMessages:
                  type: array
                  items:
                    type: string
                  description: Suggested conversation starters
                  example:
                    - What are your hours?
                    - How can I contact support?
                visibility:
                  type: string
                  enum:
                    - public
                    - private
                  description: Enable or disable access to the chatbot
                  example: public
                domains:
                  type: array
                  items:
                    type: string
                  description: Allowed domains for the chatbot
                  example:
                    - example.com
                    - subdomain.example.com
                onlyAllowOnAddedDomains:
                  type: boolean
                  description: Whether to restrict to allowed domains only
                  example: false
                ipLimit:
                  type: integer
                  description: Rate limit per IP address
                  example: 10
                ipLimitTimeframe:
                  type: integer
                  description: Timeframe for IP rate limiting
                  example: 3600
                ipLimitMessage:
                  type: string
                  description: Message shown when rate limit is exceeded
                  example: Too many requests. Please try again later.
                model:
                  $ref: '#/components/schemas/AIModel'
                temp:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: Temperature setting for AI responses
                  example: 0.7
                styles:
                  $ref: '#/components/schemas/ChatbotStyles'
                collectCustomerInformation:
                  $ref: '#/components/schemas/CollectLeadsSettings'
      responses:
        '202':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Your changes are saved.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /upload-chatbot-icon:
    post:
      tags:
        - Assets
      summary: Upload chatbot icon
      description: Uploads an icon image for the chatbot
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - chatbotId
                - chatbotIconFile
              properties:
                chatbotId:
                  type: string
                  description: ID of the chatbot
                  example: ckl123abc456
                chatbotIconFile:
                  type: string
                  format: binary
                  description: Icon image file
      responses:
        '200':
          description: Icon uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Chatbot chat icon uploaded successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /upload-chatbot-profile-picture:
    post:
      tags:
        - Assets
      summary: Upload chatbot profile picture
      description: Uploads a profile picture for the chatbot
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - chatbotId
                - profilePictureFile
              properties:
                chatbotId:
                  type: string
                  description: ID of the chatbot
                  example: ckl123abc456
                profilePictureFile:
                  type: string
                  format: binary
                  description: Profile picture image file
      responses:
        '200':
          description: Profile picture uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Chatbot Profile Picture uploaded successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /delete-chatbot-icon:
    delete:
      tags:
        - Assets
      summary: Delete chatbot icon
      description: Deletes the chatbot's icon image
      parameters:
        - name: chatbotId
          in: query
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
      responses:
        '200':
          description: Icon deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Chat Icon deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /delete-chatbot-profile-picture:
    delete:
      tags:
        - Assets
      summary: Delete chatbot profile picture
      description: Deletes the chatbot's profile picture
      parameters:
        - name: chatbotId
          in: query
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
      responses:
        '200':
          description: Profile picture deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Chatbot Profile Picture deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /chatbots/{chatbotId}/contacts:
    get:
      tags:
        - Contacts
      summary: Get contacts for a chatbot
      description: Retrieves paginated list of contacts for a specific chatbot
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 10
            maximum: 1000
          description: Number of contacts per page (10-1000)
          example: 100
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
          description: Page number (starts from 1)
          example: 1
      responses:
        '200':
          description: Contacts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  total:
                    type: integer
                    description: Total number of contacts
                    example: 250
                  pages:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 100
                      total_pages:
                        type: integer
                        example: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Contacts
      summary: Create contacts for a chatbot
      description: >-
        Creates one or more contacts for a specific chatbot (max 1000 per
        request)
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - users
              properties:
                users:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/ContactInput'
                  description: Array of contacts to create (1-1000)
      responses:
        '200':
          description: Contacts created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - External IDs or emails already exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: One or more external IDs or emails already exist.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /chatbots/{chatbotId}/contacts/{contactId}:
    get:
      tags:
        - Contacts
      summary: Get a specific contact
      description: Retrieves a single contact by ID
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: contactId
          in: path
          required: true
          schema:
            type: string
          description: External ID of the contact
          example: user_123
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Contacts
      summary: Update a contact
      description: Updates an existing contact's information
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: contactId
          in: path
          required: true
          schema:
            type: string
          description: External ID of the contact
          example: user_123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/ContactUpdateInput'
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - External ID or email already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Error saving chatbot contact. External ID or email already
                      exists.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Contacts
      summary: Delete a contact
      description: Permanently deletes a contact
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: contactId
          in: path
          required: true
          schema:
            type: string
          description: External ID of the contact
          example: user_123
      responses:
        '200':
          description: Contact deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /chatbots/{chatbotId}/custom-attributes:
    get:
      tags:
        - Contacts
      summary: Get custom attributes schema
      description: Retrieves the custom attributes schema for contacts
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
      responses:
        '200':
          description: Custom attributes schema retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    type: array
                    description: Array of custom attribute definitions
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Attribute name
                          example: department
                        label:
                          type: string
                          description: Display label for the attribute
                          example: Department
                        type:
                          type: string
                          enum:
                            - text
                            - number
                            - boolean
                            - date
                          description: Attribute data type
                          example: text
                        description:
                          type: string
                          description: Description of the attribute
                          example: Employee department
                        archived:
                          type: boolean
                          description: Whether the attribute is archived
                          example: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags:
        - Contacts
      summary: Create custom attribute
      description: Creates a new custom attribute for contacts
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAttributeInput'
      responses:
        '200':
          description: Custom attribute created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    description: Created custom attribute
                    properties:
                      name:
                        type: string
                        description: Attribute name
                        example: department
                      label:
                        type: string
                        description: Display label for the attribute
                        example: Department
                      type:
                        type: string
                        enum:
                          - text
                          - number
                          - boolean
                          - date
                        description: Attribute data type
                        example: text
                      description:
                        type: string
                        description: Description of the attribute
                        example: Employee department
                      archived:
                        type: boolean
                        description: Whether the attribute is archived
                        example: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /chatbots/{chatbotId}/custom-attributes/{name}:
    put:
      tags:
        - Contacts
      summary: Update custom attribute
      description: Updates an existing custom attribute
      parameters:
        - name: chatbotId
          in: path
          required: true
          schema:
            type: string
          description: ID of the chatbot
          example: ckl123abc456
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Name of the custom attribute
          example: department
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAttributeUpdateInput'
      responses:
        '200':
          description: Custom attribute updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    description: Updated custom attribute
                    properties:
                      name:
                        type: string
                        description: Attribute name
                        example: department
                      label:
                        type: string
                        description: Display label for the attribute
                        example: Department
                      type:
                        type: string
                        enum:
                          - text
                          - number
                          - boolean
                          - date
                        description: Attribute data type
                        example: text
                      description:
                        type: string
                        description: Description of the attribute
                        example: Employee department
                      archived:
                        type: boolean
                        description: Whether the attribute is archived
                        example: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key in Bearer token format
  responses:
    BadRequest:
      description: Bad Request - Invalid input parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Invalid request data
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: No API key provided.
    Forbidden:
      description: Forbidden - Access denied or quota exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Access denied or quota exceeded
    NotFound:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Resource not found
    RateLimited:
      description: Rate Limited - Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Rate limit exceeded. Please try again later.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal server error
  schemas:
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        id:
          type: string
          description: Unique message identifier
          example: msg_123
        role:
          type: string
          enum:
            - user
            - assistant
          description: Message sender role
          example: user
        content:
          type: string
          description: Message content
          example: Hello, I need help with my order
        type:
          type: string
          enum:
            - text
          description: Message type
          default: text
    Chatbot:
      type: object
      properties:
        id:
          type: string
          description: Unique chatbot identifier
          example: ckl123abc456
        name:
          type: string
          description: Chatbot name
          example: Customer Support Bot
        status:
          type: string
          enum:
            - training
            - ready
            - failed
          description: Current chatbot status
          example: ready
        model:
          type: string
          description: AI model being used
          example: gpt-4o-mini
        instructions:
          type: string
          description: System instructions for the chatbot
          example: You are a helpful customer service assistant
        visibility:
          type: string
          enum:
            - public
            - private
          description: Chatbot visibility setting
          example: public
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2024-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2024-01-02T12:00:00Z'
    ChatbotStyles:
      type: object
      properties:
        theme:
          type: string
          enum:
            - light
            - dark
          description: UI theme
          example: light
        buttonColor:
          type: string
          description: Color for buttons (hex code)
          example: '#007bff'
        displayName:
          type: string
          description: Display name for the chatbot
          example: Support Bot
        alignChatButton:
          type: string
          enum:
            - left
            - right
          description: Chat button alignment
          example: right
        userMessageColor:
          type: string
          description: Color for user messages (hex code)
          example: '#007bff'
        autoOpenChatWindowAfter:
          type: integer
          description: Auto-open delay in seconds (0 to disable)
          example: 5
    CollectLeadsSettings:
      type: object
      properties:
        title:
          type: string
          description: Form title
          example: Contact Information
        name:
          type: object
          properties:
            active:
              type: boolean
              description: Whether name field is enabled
              example: true
            label:
              type: string
              description: Label for name field
              example: Full Name
        email:
          type: object
          properties:
            active:
              type: boolean
              description: Whether email field is enabled
              example: true
            label:
              type: string
              description: Label for email field
              example: Email Address
        phone:
          type: object
          properties:
            active:
              type: boolean
              description: Whether phone field is enabled
              example: false
            label:
              type: string
              description: Label for phone field
              example: Phone Number
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: Unique conversation identifier
          example: conv_123
        chatbot_id:
          type: string
          description: Associated chatbot ID
          example: ckl123abc456
        created_at:
          type: string
          format: date-time
          description: Conversation start time
          example: '2024-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Last message time
          example: '2024-01-01T12:05:00Z'
        source:
          type: string
          enum:
            - api
            - website
            - whatsapp
            - slack
            - messenger
            - instagram
          description: Conversation source
          example: api
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
          description: Messages in the conversation
    Lead:
      type: object
      properties:
        id:
          type: string
          description: Unique lead identifier
          example: lead_123
        name:
          type: string
          description: Lead's name
          example: John Doe
        email:
          type: string
          format: email
          description: Lead's email address
          example: john@example.com
        phone:
          type: string
          description: Lead's phone number
          example: '+1234567890'
        created_at:
          type: string
          format: date-time
          description: Lead collection timestamp
          example: '2024-01-01T12:00:00Z'
        chatbot_id:
          type: string
          description: Associated chatbot ID
          example: ckl123abc456
        account_id:
          type: string
          description: Associated account ID
          example: acc_123abc456
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Internal contact ID
          example: contact_internal_123
        external_id:
          type: string
          description: External contact identifier
          example: user_123
        name:
          type: string
          description: Contact's name
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john@example.com
        phonenumber:
          type: string
          description: Contact's phone number
          example: '+1234567890'
        stripe_accounts:
          type: array
          description: Array of Stripe accounts associated with this contact
          items:
            $ref: '#/components/schemas/StripeAccount'
          example:
            - label: main
              stripe_id: cus_123abc456
              stripe_email: john@example.com
        custom_attributes:
          type: object
          description: Custom attributes for the contact
          additionalProperties: true
          example:
            department: Sales
            subscription_tier: Premium
        created_at:
          type: integer
          description: Contact creation timestamp (Unix timestamp)
          example: 1704067200
        updated_at:
          type: integer
          description: Last update timestamp (Unix timestamp)
          example: 1704153600
    ContactInput:
      type: object
      required:
        - external_id
      properties:
        external_id:
          type: string
          description: External contact identifier
          example: user_123
        name:
          type: string
          description: Contact's name
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john@example.com
        phonenumber:
          type: string
          description: Contact's phone number
          example: '+1234567890'
        stripe_accounts:
          type: array
          description: Array of Stripe accounts associated with this contact
          items:
            $ref: '#/components/schemas/StripeAccountInput'
          example:
            - label: main
              stripe_id: cus_123abc456
              stripe_email: john@example.com
        custom_attributes:
          type: object
          description: Custom attributes for the contact
          additionalProperties: true
          example:
            department: Sales
            subscription_tier: Premium
    ContactUpdateInput:
      type: object
      properties:
        external_id:
          type: string
          description: External contact identifier
          example: user_123
        name:
          type: string
          description: Contact's name
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john@example.com
        phonenumber:
          type: string
          description: Contact's phone number
          example: '+1234567890'
        stripe_accounts:
          type: array
          description: Array of Stripe accounts associated with this contact
          items:
            $ref: '#/components/schemas/StripeAccountInput'
          example:
            - label: main
              stripe_id: cus_123abc456
              stripe_email: john@example.com
        custom_attributes:
          type: object
          description: Custom attributes for the contact
          additionalProperties: true
          example:
            department: Engineering
            subscription_tier: Enterprise
    CustomAttributeInput:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z][a-zA-Z0-9_-]*$
          description: >-
            Attribute name (must start with a letter and can only contain
            letters, numbers, underscores, and hyphens)
          example: department
        label:
          type: string
          description: Display label for the attribute
          example: Department
        type:
          type: string
          enum:
            - text
            - number
            - boolean
            - date
          description: Attribute data type
          example: text
        description:
          type: string
          description: Description of the attribute
          example: Employee department
        archived:
          type: boolean
          description: Whether the attribute is archived
          default: false
          example: false
    CustomAttributeUpdateInput:
      type: object
      properties:
        label:
          type: string
          description: Display label for the attribute
          example: Department
        description:
          type: string
          description: Description of the attribute
          example: Updated employee department
        archived:
          type: boolean
          description: Whether the attribute is archived
          example: false
    StripeAccount:
      type: object
      required:
        - label
        - stripe_id
      properties:
        label:
          type: string
          description: Label identifier for the Stripe account
          example: main
        stripe_id:
          type: string
          description: Stripe customer ID
          example: cus_123abc456
        stripe_email:
          type: string
          format: email
          description: Email address associated with the Stripe account
          example: john@example.com
    AIModel:
      type: string
      description: AI model to use for the response
      enum:
        - gpt-4o
        - gpt-4o-mini
        - o4-mini
        - gpt-oss-120b
        - gpt-oss-20b
        - gpt-5
        - gpt-5.1
        - gpt-5.2
        - gpt-5.4
        - gpt-5.4-mini
        - gpt-5.4-nano
        - gpt-5-mini
        - gpt-5-nano
        - claude-opus-4-6
        - claude-sonnet-4-6
        - claude-opus-4-5
        - claude-haiku-4-5
        - claude-sonnet-4-5
        - gemini-2.5-flash
        - gemini-2.5-pro
        - gemini-3-flash
        - gemini-3.1-flash-lite
        - gemini-3.1-pro
        - grok-3
        - grok-3-mini
        - grok-4
        - DeepSeek-V3
        - DeepSeek-R1
        - Llama-4-Scout-17B-16E-Instruct
        - Llama-4-Maverick-17B-128E-Instruct-FP8
        - kimi-k2
      example: gpt-4o-mini
    StripeAccountInput:
      type: object
      required:
        - label
        - stripe_id
      properties:
        label:
          type: string
          description: Label identifier for the Stripe account
          example: main
        stripe_id:
          type: string
          description: Stripe customer ID
          example: cus_123abc456
        stripe_email:
          type: string
          format: email
          description: Email address associated with the Stripe account
          example: john@example.com