> ## Documentation Index > Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create AI agent > Adds a configured AI agent to the workspace. Use `aiAgents.list` first to avoid duplicating an existing agent, then use `aiAgents.update` to refine its settings. ## OpenAPI ````yaml /api-reference/platform-api.json post /v1/ai-agents openapi: 3.1.1 info: title: ChatbotX version: 0.0.1 servers: - url: https://app.chatbotx.io/api security: - bearerAuth: [] - developerAccessToken: [] - tokenInSearchParams: [] paths: /v1/ai-agents: post: tags: - AI Agents summary: Create AI agent description: >- Adds a configured AI agent to the workspace. Use `aiAgents.list` first to avoid duplicating an existing agent, then use `aiAgents.update` to refine its settings. operationId: aiAgents.create requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: AI agent name. prompt: type: string minLength: 1 maxLength: 10000 description: System prompt that defines the agent's behavior. messages: type: array items: type: object properties: role: enum: - user - assistant - system - developer type: string content: type: string minLength: 1 maxLength: 255 required: - role - content description: >- Seed conversation history (role/content pairs) shown to the model before user input. models: type: array items: anyOf: - anyOf: - type: object properties: provider: const: gemini model: enum: - gemini-3.5-flash - gemini-3.1-flash-lite - gemini-3.1-pro-preview type: string required: - provider - model - type: object properties: provider: const: openai model: enum: - gpt-4-turbo - gpt-4.1-mini - gpt-4.1-nano - gpt-4.1 - gpt-4 - gpt-4o-mini - gpt-4o - gpt-5-mini - gpt-5-nano - gpt-5-pro - gpt-5.1 - gpt-5.2-pro - gpt-5.2 - gpt-5 - gpt-5.5 - gpt-5.4-pro - gpt-5.4 - gpt-5.4-mini - gpt-5.4-nano - o4-mini type: string required: - provider - model - type: object properties: provider: const: claude model: enum: - claude-fable-5 - claude-opus-4-8 - claude-opus-4-6 - claude-sonnet-4-6 - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-opus-4-5-20251101 type: string required: - provider - model - type: object properties: provider: const: deepseek model: enum: - deepseek-v4-flash - deepseek-v4-pro type: string required: - provider - model - type: object properties: provider: const: openrouter model: enum: - openai/gpt-5.5-pro - openai/gpt-5.5 - openai/gpt-5.4-pro - openai/gpt-5.4 - openai/gpt-5.4-mini - openai/gpt-5.4-nano - openai/gpt-5.2-pro - openai/gpt-5.2-chat - openai/gpt-5.2 - openai/gpt-5.1 - openai/gpt-5-pro - openai/gpt-5 - openai/gpt-5-mini - openai/gpt-5-nano - openai/gpt-4.1 - openai/gpt-4.1-mini - openai/gpt-4.1-nano - openai/gpt-4o - openai/gpt-4o-mini - anthropic/claude-fable-5 - anthropic/claude-opus-4.8 - anthropic/claude-opus-4.6 - anthropic/claude-sonnet-4.6 - anthropic/claude-opus-4.5 - anthropic/claude-sonnet-4.5 - anthropic/claude-haiku-4.5 - google/gemini-3.5-flash - google/gemini-3.1-pro-preview - google/gemini-3.1-flash-lite - google/gemini-3-flash-preview - google/gemini-2.5-flash-lite - google/gemini-2.5-flash - google/gemini-2.5-pro - meta-llama/llama-4-maverick - meta-llama/llama-4-scout - meta-llama/llama-3.3-70b-instruct - deepseek/deepseek-v4-pro - deepseek/deepseek-v4-flash - deepseek/deepseek-v3.2 - deepseek/deepseek-r1 - deepseek/deepseek-chat - qwen/qwen3-max - qwen/qwen3.7-max - qwen/qwen3.7-plus - qwen/qwen3-coder-plus - qwen/qwen3-vl-32b-instruct - qwen/qwen-2.5-72b-instruct - mistralai/mistral-large-2512 - mistralai/mistral-medium-3-5 - mistralai/mistral-large - x-ai/grok-4.20 - x-ai/grok-4.3 type: string required: - provider - model - type: object properties: kind: const: openaiCompatible integrationId: type: string minLength: 1 model: type: string minLength: 1 required: - kind - integrationId - model description: >- Ordered fallback list of provider/model pairs to try. The first entry is preferred; later ones are used if it fails. temperature: type: number minimum: 0 maximum: 2 description: Sampling temperature, 0-2. maxOutputTokens: type: number minimum: 1 maximum: 32768 description: Maximum tokens the model may generate in one reply. tools: type: array items: type: string description: Tool names this agent is allowed to call. webSearchAuthorizedDomains: type: array maxItems: 20 items: type: object properties: value: type: string required: - value default: [] description: >- Domains the agent's web-search tool is restricted to, up to 20. Empty means unrestricted. isDefault: type: boolean description: Whether this is the workspace's default AI agent. isRichResponse: type: boolean default: false description: >- Whether the agent may return rich (card/button) responses instead of plain text. required: - name - prompt - messages - models - temperature - maxOutputTokens - tools - isDefault responses: '201': description: OK content: application/json: schema: type: object properties: id: {} createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date workspaceId: {} name: type: string prompt: anyOf: - type: string - type: 'null' messages: type: array items: anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: {} - type: array items: anyOf: - {} - type: 'null' isDefault: type: boolean isRichResponse: type: boolean tools: type: array items: type: string webSearchAuthorizedDomains: type: array items: type: string models: type: array items: anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: {} - type: array items: anyOf: - {} - type: 'null' temperature: type: number minimum: -140737488355328 maximum: 140737488355327 maxOutputTokens: type: integer minimum: -2147483648 maximum: 2147483647 required: - createdAt - updatedAt - name - prompt - messages - isDefault - isRichResponse - tools - webSearchAuthorizedDomains - models - temperature - maxOutputTokens '400': description: '400' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: businessError status: const: 400 message: type: string default: An error occurred while processing your request data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '401': description: '401' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: UNAUTHORIZED status: const: 401 message: type: string default: Authentication required data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: INVALID_CHATBOT_TOKEN status: const: 401 message: type: string default: Invalid or missing workspace API token data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: You do not have permission to perform this action data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: trialExpired status: const: 403 message: type: string default: Trial expired data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: macLimitReached status: const: 403 message: type: string default: Monthly active contact limit reached data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '422': description: '422' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: invalidRequestData status: const: 422 message: type: string default: Input validation failed data: type: object properties: issues: type: array items: type: object properties: message: type: string path: type: array items: anyOf: - type: string - type: number - type: object properties: key: anyOf: - type: string - type: number required: - key additionalProperties: {} required: - message additionalProperties: {} required: - issues additionalProperties: {} required: - defined - code - status - message - data - type: object properties: defined: const: true code: const: validation status: const: 422 message: type: string default: Validation error data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '429': description: '429' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: tooManyRequests status: const: 429 message: type: string default: Too many requests data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '500': description: '500' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: INTERNAL_SERVER_ERROR status: const: 500 message: type: string default: An unexpected error occurred data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' components: schemas: UndefinedError: type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message securitySchemes: bearerAuth: type: http scheme: bearer developerAccessToken: type: http scheme: bearer tokenInSearchParams: type: apiKey in: query name: token ````