> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boostgpt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat with Agent

> Send a message to an agent and receive a response



## OpenAPI

````yaml /api-reference/openapi.json post /v1/bot/chat
openapi: 3.0.0
info:
  title: BoostGPT API
  version: 1.0.0
  description: API for managing AI agents with memory capabilities
servers:
  - url: https://api.boostgpt.co
    description: Production server
security:
  - BearerAuth: []
tags:
  - name: Agent
    description: Operations for managing AI agents
  - name: Memory
    description: Operations for managing agent memory sources
  - name: Chat
    description: Operations for chatting with agents and managing conversations
  - name: Subscribers
    description: Operations for managing subscribers and leads
  - name: Tools
    description: Operations for managing agent tools and MCP server integrations
  - name: Analytics
    description: Operations for retrieving agent statistics and analytics
  - name: Heartbeat
    description: Operations for managing autonomous agent scheduling and execution
  - name: User Memory
    description: Operations for managing per-user memory entries
  - name: Email
    description: Operations for managing agent email functionality
  - name: Triggers
    description: Operations for firing proactive agent trigger events
  - name: CRM
    description: >-
      Operations for managing agent CRM contacts, pipelines, deals, follow-ups,
      and reports
  - name: Workflows
    description: Operations for managing agent workflow automations
  - name: Calendar
    description: Operations for managing agent calendar settings, availability, and events
  - name: Workspace
    description: Operations for managing agent workspaces and files
paths:
  /v1/bot/chat:
    post:
      tags:
        - Chat
      summary: Chat with Agent
      description: Send a message to an agent and receive a response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Chat response received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
components:
  schemas:
    ChatRequest:
      type: object
      required:
        - project_id
        - bot_id
        - message
      properties:
        project_id:
          type: string
          description: Project ID
        bot_id:
          type: string
          description: Agent ID
        provider_key:
          type: string
          description: Optional API key for the AI provider
        provider_host:
          type: string
          description: Optional host URL for the AI provider
        model:
          type: string
          description: Override the default model for this request
        message:
          type: string
          description: The user's message
        source_ids:
          type: array
          items:
            type: string
          description: Specific memory sources to use
        tags:
          type: array
          items:
            type: string
          description: Filter memory by tags
        top:
          type: integer
          description: Number of memory results to include
          default: 5
        instruction:
          type: string
          description: Override system instructions for this request
        max_reply_tokens:
          type: integer
          description: Maximum tokens in the response
        stream:
          type: boolean
          description: Enable streaming response
          default: false
        chat_id:
          type: string
          description: Chat conversation ID (creates new if not provided)
        reasoning_mode:
          type: string
          enum:
            - auto
            - standard
            - agent
          description: >-
            Reasoning mode for the agent response. 'auto' selects the best
            approach automatically, 'standard' for quick single-pass answers (1x
            credit), 'agent' for autonomous multi-step reasoning with tool use
            (up to 10x credit)
          default: auto
        chat_mode:
          type: string
          enum:
            - ask
            - edit
            - plan
          description: >-
            Chat mode. 'ask' for normal chat, 'edit' for agent-powered code
            editing, 'plan' for conversational plan-then-execute workflow
          default: ask
    ChatResponse:
      type: object
      description: >-
        Response structure varies based on reasoning_mode. Contains 'chat'
        object with mode-specific fields.
      properties:
        chat:
          type: object
          description: Chat response data with mode-specific structure
          properties:
            reply:
              type: string
              description: Agent's text response (present in all modes)
            user:
              $ref: '#/components/schemas/MessageDetails'
              description: User message details
            agent:
              $ref: '#/components/schemas/MessageDetails'
              description: Agent message details
            preference:
              $ref: '#/components/schemas/PreferenceConfig'
              description: Preference configuration used
            meta:
              type: array
              description: Metadata and sources
              items:
                $ref: '#/components/schemas/SourceMeta'
            usage:
              type: object
              description: Token usage information
              properties:
                prompt_tokens:
                  type: integer
                  description: Number of prompt tokens
                completion_tokens:
                  type: integer
                  description: Number of completion tokens
                total_tokens:
                  type: integer
                  description: Total tokens used
                reasoning_type:
                  type: string
                  description: Reasoning type used (for non-standard modes)
                conversation_count:
                  type: integer
                  description: Number of conversation turns (for reasoning modes)
                prompt_tokens_details:
                  type: object
                  properties:
                    cached_tokens:
                      type: integer
                    audio_tokens:
                      type: integer
                completion_tokens_details:
                  type: object
                  properties:
                    reasoning_tokens:
                      type: integer
                    audio_tokens:
                      type: integer
                    accepted_prediction_tokens:
                      type: integer
                    rejected_prediction_tokens:
                      type: integer
            config_used:
              $ref: '#/components/schemas/PreferenceConfig'
              description: Configuration used for this response
            analytics_id:
              type: integer
              description: Analytics tracking ID
            actual_time_ms:
              type: integer
              description: Actual processing time in milliseconds
            type:
              type: string
              description: 'Response type (agent mode: ''tool_approval_required'')'
            tool:
              $ref: '#/components/schemas/ToolInfo'
              description: Tool information (agent mode only)
            requiresApproval:
              type: boolean
              description: Whether tool execution requires approval (agent mode)
            executionId:
              type: string
              description: Execution ID (agent mode)
            originalQuery:
              type: string
              description: Original user query (agent mode)
            context:
              type: string
              description: Conversation context (agent mode)
            executedTools:
              type: array
              description: List of executed tools (agent mode)
              items:
                type: object
            isComplete:
              type: boolean
              description: Whether reasoning is complete (agent mode)
            availableTools:
              type: integer
              description: Number of available tools (agent mode)
            stepInfo:
              type: string
              description: Step information (agent mode)
            hasMoreSteps:
              type: boolean
              description: Whether more steps remain (agent mode)
            finalAnswer:
              type: string
              description: Final answer (agent mode)
            reasoningSteps:
              type: array
              description: Reasoning steps (agent mode)
              items:
                $ref: '#/components/schemas/ReasoningStep'
            sources:
              type: array
              description: Sources used (agent mode)
              items:
                $ref: '#/components/schemas/SourceMeta'
            totalSteps:
              type: integer
              description: Total number of reasoning steps (agent mode)
            reasoning:
              type: array
              description: Detailed reasoning cycles (agent mode)
              items:
                $ref: '#/components/schemas/ReasoningStep'
            reasoningCycles:
              type: array
              description: Reasoning cycles (agent mode)
              items:
                $ref: '#/components/schemas/ReasoningStep'
            totalCycles:
              type: integer
              description: Total reasoning cycles (agent mode)
            converged:
              type: boolean
              description: Whether reasoning converged (agent mode)
    MessageDetails:
      type: object
      description: Detailed information about a chat message
      properties:
        uuid:
          type: string
          description: Message unique identifier
        chat_id:
          type: string
          description: Chat conversation ID
        content:
          type: string
          description: Message content
        role:
          type: string
          enum:
            - user
            - system
          description: Message role
        model:
          type: string
          description: AI model used
        complexity:
          type: string
          description: Complexity level
        reasoning_type:
          type: string
          description: Reasoning type
        estimated_time_ms:
          type: string
          description: Estimated time in milliseconds
        estimated_cost:
          type: string
          description: Estimated cost
        confidence:
          type: string
          description: Confidence level
        channel:
          type: string
          description: Communication channel
        credit_used:
          type: string
          description: Credits used
        confidence_score:
          type: string
          description: Confidence score
        tokens:
          type: integer
          description: Token count
        upvotes:
          type: integer
          description: Upvote count
        downvotes:
          type: integer
          description: Downvote count
        reasoning:
          type: object
          nullable: true
          description: Reasoning details
        preference:
          $ref: '#/components/schemas/PreferenceConfig'
          nullable: true
        sources:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SourceMeta'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        isToolExecuting:
          type: boolean
          description: Whether tool is executing
    PreferenceConfig:
      type: object
      description: User preference configuration
      properties:
        reasoningType:
          type: string
          description: Reasoning type preference
        model:
          type: string
          description: Model preference
        maxTokens:
          type: integer
          description: Maximum tokens
        complexity:
          type: string
          description: Complexity preference
    SourceMeta:
      type: object
      description: Source metadata information
      properties:
        citation_number:
          type: integer
          description: Citation number
        source_id:
          type: string
          description: Source identifier
        title:
          type: string
          description: Source title
        url:
          type: string
          description: Source URL
        favicon:
          type: string
          description: Favicon URL
        type:
          type: string
          description: Source type
        tags:
          type: array
          items:
            type: string
          description: Source tags
    ToolInfo:
      type: object
      description: Tool execution information
      properties:
        name:
          type: string
          description: Tool name
        description:
          type: string
          description: Tool description
        server_label:
          type: string
          description: Server label
        parameters:
          type: object
          description: Tool parameters
        reasoning:
          type: string
          description: Reasoning for tool use
    ReasoningStep:
      type: object
      description: A single reasoning step or cycle
      properties:
        cycle:
          type: integer
          description: Cycle number
        thought:
          type: string
          description: Thought process
        action:
          type: string
          description: Action taken
        actionInput:
          type: string
          description: Input for the action
        observation:
          type: string
          description: Observation from action
        actionSuccess:
          type: boolean
          description: Whether action succeeded
        timestamp:
          type: string
          description: Timestamp of step
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceMeta'
          description: Sources used in this step
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Enter your API key

````