{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/docsbot-ai/json-schema/docsbot-ai-agent-ask-schema.json",
  "title": "AgentAsk",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/docsbot-ai-openapi.json#/components/schemas/AgentAsk",
  "properties": {
    "question": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "The question to ask the bot"
    },
    "history": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ],
      "title": "History",
      "description": "Ignore this field, not used in agent conversations"
    },
    "format": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "markdown",
            "text",
            "html"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Whether to return the answer as markdown, html or raw text",
      "default": "markdown"
    },
    "full_source": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Whether to return the full source text chunk or not",
      "default": false
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "An object with arbitrary metadata about the the user or chat call. Keys `referrer`, `email`, and `name` are shown in question history logs."
    },
    "testing": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Whether to ignore the question or not in logs",
      "default": false
    },
    "autocut": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "integer"
        }
      ],
      "title": "Autocut results to num groups",
      "default": false
    },
    "context_items": {
      "type": "integer",
      "maximum": 32.0,
      "exclusiveMinimum": 0.0,
      "title": "How many context sources to use",
      "default": 5
    },
    "evalContext": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000000
        },
        {
          "type": "null"
        }
      ],
      "title": "Evalcontext"
    },
    "promptTarget": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "agent",
            "helpscout"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Prompttarget"
    },
    "audio": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/$defs/AgentAudioInput"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audio",
      "description": "Audio user message as a data URL string or an object with base64 data and format."
    },
    "conversationId": {
      "type": "string",
      "minLength": 1,
      "title": "UUID of conversation",
      "description": "Unique identifier for the conversation, pass a new UUID to start a new conversation"
    },
    "channel": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "chat",
            "voice",
            "phone",
            "slack",
            "helpscout",
            "messenger",
            "whatsapp",
            "telegram"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Channel",
      "description": "Internal conversation channel persisted on the conversation object."
    },
    "stream": {
      "type": "boolean",
      "title": "Stream",
      "description": "Whether to stream the response with SSE or return it all at once",
      "default": false
    },
    "human_escalation": {
      "type": "boolean",
      "title": "Human Escalation",
      "description": "Whether to enable the human escalation detection tool",
      "default": false
    },
    "calendly": {
      "type": "boolean",
      "title": "Calendly",
      "description": "Whether to enable the Calendly booking tool",
      "default": false
    },
    "calcom": {
      "type": "boolean",
      "title": "Calcom",
      "description": "Whether to enable the Cal.com booking tool",
      "default": false
    },
    "tidycal": {
      "type": "boolean",
      "title": "Tidycal",
      "description": "Whether to enable the TidyCal booking tool",
      "default": false
    },
    "custom_buttons": {
      "type": "boolean",
      "title": "Custom Buttons",
      "description": "Whether to enable custom button tools built from bot.tools.customButtons",
      "default": false
    },
    "generative_ui": {
      "type": "boolean",
      "title": "Generative Ui",
      "description": "Whether this request may include a display-only OpenUI Lang response alongside its readable answer.",
      "default": false
    },
    "followup_rating": {
      "type": "boolean",
      "title": "Followup Rating",
      "description": "Whether to enable the follow-up rating tool",
      "default": false
    },
    "document_retriever": {
      "type": "boolean",
      "title": "Document Retriever",
      "description": "Whether to enable the document retrieval tool for factual answers",
      "default": true
    },
    "web_search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "const": "live"
        }
      ],
      "title": "Web Search",
      "description": "Web search mode: false disables, true enables cached mode (or bot default), and 'live' forces live search for this request.",
      "default": false
    },
    "openapi": {
      "type": "boolean",
      "title": "Openapi",
      "description": "Ignore this field, not yet implemented",
      "default": false
    },
    "image_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Image Urls",
      "description": "List of image URLs to include as context for this message"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model",
      "description": "Any valid OpenAI model string supported by DocsBot."
    },
    "default_language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Default Language",
      "description": "The default language to use, if the language of the conversation is unclear. Use the locale code like 'en' or 'en-US'. Defaults to bot language."
    },
    "reasoning_effort": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "none",
            "minimal",
            "low",
            "medium",
            "high",
            "xhigh",
            "max"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Reasoning Effort",
      "description": "Reasoning depth for the response. Requires authentication and the Personal plan or above to override default. 'none' (GPT-5.1) and 'minimal' (GPT-5) use the least reasoning, 'low' is light, 'medium' balanced, 'high' deeper, 'xhigh' deeper still (GPT-5.4/5.6/6), and 'max' deepest (GPT-5.6 Sol or GPT-6 Astra). Defaults: GPT-6 Luna → 'medium', GPT-6 Sol/Astra → 'low', GPT-5.6 Luna → 'low', other GPT-5.6 → 'none', GPT-5.4 nano → 'medium', GPT-5.4 mini → 'low', other versioned GPT-5.x → 'none', GPT-5 → 'minimal', other reasoning models → 'low', non-reasoning models → ignored."
    },
    "search_limit": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 4.0,
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Search Limit",
      "description": "Maximum number of times the search_documentation tool can be called. Requires authentication to override default. Minimum: 1, Maximum: 4. Defaults to bot's searchDocumentationLimit or 2 (default is 2 for latency and token cost reasons)."
    }
  },
  "type": "object",
  "required": [
    "conversationId"
  ],
  "$defs": {
    "AgentAudioInput": {
      "properties": {
        "data": {
          "type": "string",
          "minLength": 1,
          "title": "Data",
          "description": "Base64 encoded audio data"
        },
        "format": {
          "type": "string",
          "minLength": 1,
          "title": "Format",
          "description": "Audio format extension supported by OpenAI, such as webm, mp3, or wav"
        }
      },
      "type": "object",
      "required": [
        "data",
        "format"
      ],
      "title": "AgentAudioInput"
    }
  }
}