> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/api-reference/ai-zhu-li.md). # AI Assistants ### Create a New AI Assistant POST `/api/v1/chatbots/` #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Yes | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. | | largeLanguageModel | string (uuid) | Yes | Large language model used by the chatbot to generate responses (including custom AI Gateway models configured by the organization); may be omitted during creation only if the organization has configured a default model in the AI assistant defaults | | condenseQuestionLlm | string (uuid) | No | Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode; null follows the system settings (if the selected model is later blocked or disabled by the organization, this field also reads back as null and follows the system settings) | | embeddingModel | string (uuid) | No | Optional embedding model used to vectorize text | | rerankerModel | string (uuid) | No | Optional model used for reranking | | instructions | string | No | Role instructions describing the chatbot's role and behavior. | | knowledgeBases | array\[IdName] | No | List of knowledge bases accessible to the chatbot | | databases | array\[IdName] | No | List of SQL databases accessible to the chatbot (for Text-to-SQL) | | organization | string (uuid) | No | Organization the chatbot belongs to; if empty, the chatbot is personal | | replyMode | object | No | Reply mode: normal or streaming replies `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent; | | template | string | No | Template used by Template and Hybrid modes. | | unanswerableTemplate | string | No | Template used by Template and Hybrid modes when the question cannot be answered. | | totalWordsCount | integer (int64) | No | Accumulated total word count used. | | outputMode | object | No | Output mode: text, table, or custom format `text`: Text ; `json_schema`: JSON Schema; | | rawOutputFormat | object | No | JSON structure definition for the custom output format | | groups | array\[IdName] | No | List of groups accessible to the chatbot | | tools | array\[ToolSummary] | No | List of tools available to the chatbot | | skills | array\[SkillSummary] | No | List of skills associated with the chatbot | | connectors | array\[IdName] | No | Connectors associated with this chatbot, gating per-contact OAuth authorization | | agentMode | object | No | Agent mode: normal, SQL, or workflow mode `normal`: Normal ; `canvas`: Canvas ; `team`: Team; | | numberOfRetrievedChunks | integer | No | Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 | | defaultLabelRelations | object | No | Default knowledge base label filters at the assistant level, using the same format as query\_metadata.label\_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller does not provide query\_metadata. | | useFullRetrievalRange | boolean | No | When enabled, ignores LLM top\_k truncation and returns the full reranker results | | enableEvaluation | boolean | No | | | enableInlineCitations | boolean | No | Enables inline citations, inserting citation markers such as \[1]\[2] into responses. | | enableCodeInterpreter | boolean | No | When enabled, provides the Code Interpreter tool to run code in an isolated container. | | enableBrowserTool | boolean | No | Enable browser automation tool for web tasks | | enableImageSearch | boolean | No | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. | | enableClaudeStreamRetry | boolean | No | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu... | | customMaxLlmOutputTokens | integer | No | Custom maximum number of LLM output tokens, with a minimum of 512 | | voiceConfig | object | No | | | voiceConfig.enabled | boolean | No | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. | | voiceConfig.voiceAgentType | string (uuid) | No | Voice agent mode type. | | voiceConfig.sttProvider | string (uuid) | No | Speech-to-Text service provider. | | voiceConfig.sttConfig | object | No | STT configuration parameters (JSON). | | voiceConfig.ttsProvider | string (uuid) | No | Text-to-Speech service provider. | | voiceConfig.ttsConfig | object | No | TTS configuration parameters (JSON). | | voiceConfig.realtimeProvider | string (uuid) | No | Realtime end-to-end voice model provider. | | voiceConfig.realtimeConfig | object | No | Realtime configuration parameters (JSON). | | voiceConfig.realtimeInstructions | string | No | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty | | voiceConfig.turnHandling | object | No | Turn-taking and interruption settings for the voice agent. | | voiceConfig.enableVoiceReply | boolean | No | When disabled, the voice agent replies in text only and does not speak | | thinkingConfig | object | No | Reasoning level: null (model default) or {"reasoning\_effort": "off | | enableToolSearching | boolean | No | Legacy field; use tool\_loading\_mode instead. Writing true is equivalent to tool\_loading\_mode=search, and false to all; when both are provided, tool\_loading\_mode takes precedence. On read, returns whether the tool loading mode is anything other than loading all tools. | | toolLoadingMode | object | No | Tool loading mode: auto (automatic, based on the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never set this field return a value derived from the legacy toggle (on → search, off → all). `auto`: Auto ; `all`: Load all ; `search`: Dynamic search; | | maxAgentIterations | integer | No | Maximum number of iterations for AgentWorkflow (1-100, default: 20) | | agentTimeoutSeconds | integer | No | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) | | agentTimeoutMessage | string | No | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. | | requireTextWithFlexCards | boolean | No | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se... | | enableSizeBasedToolResultTruncation | boolean | No | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati... | | toolResultMaxChars | integer | No | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True. | | enableVectorMemory | boolean | No | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist... | | longTermMemoryTopK | integer | No | Number of memory nodes returned per long-term memory retrieval (similarity\_top\_k for vector retrieval); defaults to 10, with a range of 1–50 | | enableCrossConversationSearch | boolean | No | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. | | crossConversationLookbackDays | integer | No | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... | | useGatewayFallback | boolean | No | When enabled, use the fallback group instead of the single LLM | | gatewayFallbackGroup | string (uuid) | No | | | enableSearchMessagesTool | boolean | No | Allow the AI to search past messages in the current conversation. | | enableGetMessageContextTool | boolean | No | Allow the AI to retrieve messages surrounding a specific message for context. | | enableReadAttachmentFullTextTool | boolean | No | Allow the AI to read the full text of plain-text attachments. AGENT mode only. | | enableParseAttachmentContentTool | boolean | No | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. | | enableListAvailableParsersTool | boolean | No | Allow the AI to list available parsers and their capabilities. AGENT mode only. | | enableGetDownloadLinkTool | boolean | No | Allow the AI to generate shareable download links for produced content. AGENT mode only. | | webChatIsActive | boolean | No | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor... | | apiIsActive | boolean | No | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u... | | fileWorkspaceMode | object | No | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount; | | fileWorkspaceFolder | string (uuid) | No | The bound workspace (folder id); required when the mode is bound, cleared otherwise. | **Example Request Schema** ```typescript { "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models configured by the organization); may be omitted during creation only if the organization has configured a default model in the AI assistant defaults "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode; null follows the system settings (if the selected model is later blocked or disabled by the organization, this field also reads back as null and follows the system settings) (Optional) "embeddingModel"?: string (uuid) // Optional embedding model used to vectorize text (Optional) "rerankerModel"?: string (uuid) // Optional model used for reranking (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases accessible to the chatbot (Optional) { "id": string (uuid) } ] "databases"?: [ // List of SQL databases accessible to the chatbot (for Text-to-SQL) (Optional) { "id": string (uuid) } ] "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, the chatbot is personal (Optional) "replyMode"?: // Reply mode: normal or streaming replies * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON structure definition for the custom output format (Optional) "groups"?: [ // List of groups accessible to the chatbot (Optional) { "id": string (uuid) } ] "tools"?: [ // List of tools available to the chatbot (Optional) { "id": string (uuid) } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional) "defaultLabelRelations"?: object // Default knowledge base label filters at the assistant level, using the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller does not provide query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores LLM top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens, with a minimum of 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; when both are provided, tool_loading_mode takes precedence. On read, returns whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (automatic, based on the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never set this field return a value derived from the legacy toggle (on → search, off → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of memory nodes returned per long-term memory retrieval (similarity_top_k for vector retrieval); defaults to 10, with a range of 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) } ``` **Example Request Values** ```json { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X POST "https://api.maiagent.ai/api/v1/chatbots/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }; axios.post("https://api.maiagent.ai/api/v1/chatbots/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": None, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": None, "useFullRetrievalRange": True, "enableEvaluation": True, "enableInlineCitations": True, "enableCodeInterpreter": True, "enableBrowserTool": True, "enableImageSearch": True, "enableClaudeStreamRetry": True, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": True, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": None, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": None, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": None, "realtimeInstructions": "Example string", "turnHandling": None, "enableVoiceReply": True }, "thinkingConfig": None, "enableToolSearching": True, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": True, "enableSizeBasedToolResultTruncation": True, "toolResultMaxChars": 123, "enableVectorMemory": True, "longTermMemoryTopK": 123, "enableCrossConversationSearch": True, "crossConversationLookbackDays": 123, "useGatewayFallback": True, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": True, "enableGetMessageContextTool": True, "enableReadAttachmentFullTextTool": True, "enableParseAttachmentContentTool": True, "enableListAvailableParsersTool": True, "enableGetDownloadLinkTool": True, "webChatIsActive": True, "apiIsActive": True, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/chatbots/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name', 'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000', 'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000', 'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000', 'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000', 'instructions' => 'Example string', 'knowledgeBases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'databases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'organization' => '550e8400-e29b-41d4-a716-446655440000', 'replyMode' => new \stdClass(), 'template' => 'Example string', 'unanswerableTemplate' => 'Example string', 'totalWordsCount' => 123, 'outputMode' => new \stdClass(), 'rawOutputFormat' => null, 'groups' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'tools' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'skills' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'connectors' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'agentMode' => new \stdClass(), 'numberOfRetrievedChunks' => 123, 'defaultLabelRelations' => null, 'useFullRetrievalRange' => true, 'enableEvaluation' => true, 'enableInlineCitations' => true, 'enableCodeInterpreter' => true, 'enableBrowserTool' => true, 'enableImageSearch' => true, 'enableClaudeStreamRetry' => true, 'customMaxLlmOutputTokens' => 123, 'voiceConfig' => [ 'enabled' => true, 'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000', 'sttProvider' => '550e8400-e29b-41d4-a716-446655440000', 'sttConfig' => null, 'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000', 'ttsConfig' => null, 'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000', 'realtimeConfig' => null, 'realtimeInstructions' => 'Example string', 'turnHandling' => null, 'enableVoiceReply' => true ], 'thinkingConfig' => null, 'enableToolSearching' => true, 'toolLoadingMode' => new \stdClass(), 'maxAgentIterations' => 123, 'agentTimeoutSeconds' => 123, 'agentTimeoutMessage' => 'Example string', 'requireTextWithFlexCards' => true, 'enableSizeBasedToolResultTruncation' => true, 'toolResultMaxChars' => 123, 'enableVectorMemory' => true, 'longTermMemoryTopK' => 123, 'enableCrossConversationSearch' => true, 'crossConversationLookbackDays' => 123, 'useGatewayFallback' => true, 'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000', 'enableSearchMessagesTool' => true, 'enableGetMessageContextTool' => true, 'enableReadAttachmentFullTextTool' => true, 'enableParseAttachmentContentTool' => true, 'enableListAvailableParsersTool' => true, 'enableGetDownloadLinkTool' => true, 'webChatIsActive' => true, 'apiIsActive' => true, 'fileWorkspaceMode' => new \stdClass(), 'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization); can be omitted on creation only if the organization has set a default model in its AI assistant defaults "llm": // The bound model's id, name, and retirement information, read directly from the FK; returned even if the organization has disabled the model { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; once reached, the daily scheduled job switches assistants to the replacement and disables this model. null means no retirement is scheduled "replacement": // Replacement model after retirement (id and name); null means none is specified, so no automatic migration occurs on the retirement date { "id": string (uuid) "name": string } } "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions as standalone questions before retrieval in RAG reply mode; null means follow system settings (if the selected model is later blocked or disabled by the organization, null is also returned and system settings apply) (optional) "defaultCondenseQuestionLlm": // Question rewriting model actually used when following system settings (id and name); null means the assistant's main model handles rewriting (read-only) { "id": string (uuid) "name": string } "organizationEnforcedSettings": [ // Codes of settings enforced on this assistant by the organization's AI assistant defaults (matching the keys in the AI assistant defaults API); these fields return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT) string ] "embeddingModel"?: string (uuid) // Embedding model for vectorizing text; optional (optional) "rerankerModel"?: string (uuid) // Model for reranking; optional (optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (optional) "knowledgeBases"?: [ // List of knowledge bases accessible to the chatbot (optional) { "id": string (uuid) "name": string } ] "databases"?: [ // List of SQL databases accessible to the chatbot (for Text-to-SQL) (optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, this is a personal chatbot (optional) "replyMode"?: // Reply mode: normal or streaming replies * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (optional) { } "template"?: string // Template used by Template and Hybrid modes. (optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (optional) { } "rawOutputFormat"?: object // JSON schema definition for the custom output format (optional) "groups"?: [ // List of groups accessible to the chatbot (optional) { "id": string (uuid) "name": string } ] "tools"?: [ // List of tools available to the chatbot (optional) { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills"?: [ // List of skills associated with the chatbot (optional) { "id": string (uuid) "name": string "description": string } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (optional) { "id": string (uuid) "name": string } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks retrieved; default: 12, minimum: 1 (optional) "defaultLabelRelations"?: object // Assistant-level default knowledge base label filters, in the same format as query_metadata.label_relations; null means no filtering. Applied only as the lowest-priority fallback when the caller does not provide query_metadata. (optional) "useFullRetrievalRange"?: boolean // When enabled, ignores LLM top_k truncation and returns the full reranker results (optional) "enableEvaluation"?: boolean // optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens; minimum: 512 (optional) "voiceConfig"?: { // optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (optional) "sttConfig"?: object // STT configuration parameters (JSON). (optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (optional) } } "thinkingConfig"?: object // Reasoning effort: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; if both are provided, tool_loading_mode takes precedence. On reads, returns whether the tool loading mode is anything other than loading all tools. (optional) "toolLoadingMode"?: // Tool loading mode: auto (automatically determined by the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants without an explicit setting return a value derived from the legacy toggle (on→search, off→all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of memory nodes retrieved per long-term memory search (similarity_top_k for vector retrieval). Default: 10; range: 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null} "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace. } ``` **Example Response Value** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } }, "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "defaultCondenseQuestionLlm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "organizationEnforcedSettings": [ "Response string" ], "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Response string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "updatedAt": "Response string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Response string", "unanswerableTemplate": "Response string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string", "displayName": "Response string", "toolType": "Response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "agentMode": {}, "numberOfRetrievedChunks": 456, "defaultLabelRelations": null, "useFullRetrievalRange": false, "enableEvaluation": false, "enableInlineCitations": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "enableClaudeStreamRetry": false, "customMaxLlmOutputTokens": 456, "voiceConfig": { "enabled": false, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Response string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "toolLoadingMode": {}, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "Response string", "requireTextWithFlexCards": false, "isMultimodalLlm": false, "enableSizeBasedToolResultTruncation": false, "toolResultMaxChars": 456, "enableVectorMemory": false, "longTermMemoryTopK": 456, "enableCrossConversationSearch": false, "crossConversationLookbackDays": 456, "useGatewayFallback": false, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": false, "enableGetMessageContextTool": false, "enableReadAttachmentFullTextTool": false, "enableParseAttachmentContentTool": false, "enableListAvailableParsersTool": false, "enableGetDownloadLinkTool": false, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "webChatIsActive": false, "apiIsActive": false, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000", "fileWorkspaceStatus": { "name": "example.pdf", "content": "base64encoded_content", "contentType": "application/pdf" }, "fileWorkspaceAvailable": false } ``` *** ### List Embedding Models GET `/api/v1/embedding-models/` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/embedding-models/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/embedding-models/", config) .then(response => { console.log('Response retrieved successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/embedding-models/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response retrieved successfully:") print(response.json()) except Exception as e: print("Request failed:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/embedding-models/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response retrieved successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Structure** ```typescript [ { "id": string (uuid) "name": string "isDefault"?: boolean // Optional "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (Optional) "icon": { "id": string (uuid) "name": string "image": string (uri) } } ] ``` **Example Response Values** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "isDefault": false, "isMultimodal": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "image": "https://example.com/file.jpg" } } ] ``` *** ### List Reranker Models GET `/api/v1/reranker-models/` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/reranker-models/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/reranker-models/", config) .then(response => { console.log('Response retrieved successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/reranker-models/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response retrieved successfully:") print(response.json()) except Exception as e: print("Request failed:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/reranker-models/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response retrieved successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Structure** ```typescript [ { "id": string (uuid) "name": string "isDefault"?: boolean // Optional "icon": { "id": string (uuid) "name": string "image": string (uri) } } ] ``` **Example Response Values** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "isDefault": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "image": "https://example.com/file.jpg" } } ] ``` *** ### List Large Language Models GET `/api/v1/large-language-models/` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/large-language-models/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/large-language-models/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/large-language-models/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request failed:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/large-language-models/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response **Status Code: 200** **Example Response Schema** ```typescript [ { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date. Once reached, a daily scheduled task switches assistants to replacement and disables this model. null means no retirement is scheduled. "replacement": // The replacement model (id and name) after retirement. null means none is specified, so no automatic migration occurs on retirement. { "id": string (uuid) "name": string } "contextWindow"?: integer // Used only by OpenAILike or Ollama models; other models ignore this value. (Optional) "isDefault"?: boolean // Optional "provider": string "servedBy": string // Who runs inference, which is where prompts are sent (for example OpenRouter, AWS Bedrock); models on a customer credential show Customer credential. "icon": { "id": string (uuid) "name": string "image": string (uri) } "isMultiModalSupport"?: boolean // Optional "isFunctionalCallingAvailable": boolean // Deprecated: same value as isToolCallingAvailable; use isToolCallingAvailable. "isToolCallingAvailable"?: boolean // Optional "isTemplateAvailable": boolean "isOutputFormatAvailable": boolean "isThinkingAvailable"?: boolean // When checked, this model shows the thinking depth setting and requests carry thinking parameters (thinking_budget for Gemini, reasoning_effort for OpenAI-compatible hosts). Unchecking stops sending them; saved thinking settings are kept but have no effect. Check only for models known to support thinking parameters, otherwise the provider returns 4xx. (Optional) "defaultThinkingLevel"?: // May have different types (Optional) string (enum: off, minimal, low, medium, high, xhigh, max) // The thinking level sent when neither the conversation nor the assistant sets one. Empty sends no thinking parameter, so the provider default applies. A level the model does not accept is lowered to the nearest one it does. Takes effect only when Supports Thinking is checked. * `off` - off * `minimal` - minimal * `low` - low * `medium` - medium * `high` - high * `xhigh` - xhigh * `max` - max (Optional) "thinkingConfigSchema": { // Thinking configuration form for this model; null means this model has no thinking settings. { "type"?: string // Form type; always reasoning_effort. (Optional) "fields"?: object // reasoning_effort field: options lists the thinking levels this model accepts, from lowest to highest; default is always null. (Optional) "canDisable"?: boolean // Whether thinking can be disabled for this model; when true, options includes off. (Optional) "unsetBehavior"?: string (enum: off, model_default) // Actual behavior when neither the conversation nor the assistant sets a thinking level: off = no thinking (fastest); model_default = the model controls thinking, or the platform default level enables thinking. (Optional) "unsetLevel"?: string // The level the platform actually sends when no level is set; null means no thinking parameter is sent, leaving the model default in effect. (Optional) } } "replyMode": [ string ] "outputMode": [ string ] "agentMode": [ string ] "maxTokens"?: integer // Optional "minTokens": integer "isCustomModel": boolean // Whether the row is organization-owned (materialized from an AI Gateway custom model). "originCountry": string // ISO 3166-1 alpha-2 code of the country the model developer is based in (e.g. US, CN, FR); null when unknown. Follows the model, not who runs inference. "originRegion": // May have different types string (enum: cn, us, other) // Origin group for labels and filters: cn / us / other; null when unknown (no label). * `cn` - China * `us` - United States * `other` - Other countries "originRegionDisplay": string // Translated origin group name (e.g. China / United States / Other countries); null when unknown. "isCondenseQuestionAvailable": boolean // Whether an assistant can pick this model as its question-rewrite (condense question) model; false for image-generation models, which the chatbot condense_question_llm field rejects. } ] ``` **Example Response Values** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "contextWindow": 456, "isDefault": false, "provider": "Response string", "servedBy": "Response string", "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "image": "https://example.com/file.jpg" }, "isMultiModalSupport": false, "isFunctionalCallingAvailable": false, "isToolCallingAvailable": false, "isTemplateAvailable": false, "isOutputFormatAvailable": false, "isThinkingAvailable": false, "defaultThinkingLevel": "off", "thinkingConfigSchema": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" }, "replyMode": [ "Response string" ], "outputMode": [ "Response string" ], "agentMode": [ "Response string" ], "maxTokens": 456, "minTokens": 456, "isCustomModel": false, "originCountry": "Response string", "originRegion": "cn", "originRegionDisplay": "Response string", "isCondenseQuestionAvailable": false } ] ``` *** ### List AI Assistants GET `/api/v1/chatbots/` #### Parameters | Parameter Name | Required | Type | Description | | -------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createdByMember` | ❌ | string | Creator filter: the ID of a member in this organization (the ID returned by the member directory, including disabled members). Returns only AI assistants created by that member. | | `largeLanguageModel` | ❌ | string | | | `page` | ❌ | integer | A page number within the paginated result set. | | `pageSize` | ❌ | integer | Number of results to return per page. | | `pagination` | ❌ | string | Whether to paginate (true/false) | | `query` | ❌ | string | | | `replyMode` | ❌ | string | | | `source` | ❌ | string | \`self\_built\`: self\_built ; \`built\_in\`: built\_in ; \`all\`: all; | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request failed:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/?createdByMember=550e8400-e29b-41d4-a716-446655440000&largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example&source=all", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response **Status Code: 200** **Example Response Schema** ```typescript { "count": integer "next"?: string (uri) // Optional "previous"?: string (uri) // Optional "results": [ { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "groups": [ { "id": string (uuid) "name": string } ] "largeLanguageModel": { // Base LLM serializer: identification fields plus retirement information, so the frontend can warn when the model is nearing retirement. { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date. Once reached, a daily scheduled task switches assistants to replacement and disables this model. null means no retirement is scheduled. "replacement": // The replacement model (id and name) after retirement. null means none is specified, so no automatic migration occurs on retirement. { "id": string (uuid) "name": string } } } "embeddingModel": { { "id": string (uuid) "name": string "isDefault"?: boolean // Optional "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (Optional) "icon": { "id": string (uuid) "name": string "image": string (uri) } } } "rerankerModel": { { "id": string (uuid) "name": string "isDefault"?: boolean // Optional "icon": { "id": string (uuid) "name": string "image": string (uri) } } } "knowledgeBases": [ { "id": string (uuid) "name": string } ] "tools": [ { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills": [ { "id": string (uuid) "name": string "description": string } ] "agentMode"?: // Agent mode: Canvas or Normal. Canvas mode generates answers on a canvas; Normal mode generates regular answers. * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "replyMode"?: // Reply mode: Normal, Template, Hybrid, or Agent. * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "updatedAt": string (timestamp) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableToolSearching": boolean "toolLoadingMode": string "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "numberOfRetrievedChunks"?: integer // Optional "useFullRetrievalRange"?: boolean // When enabled, the retrieval tool ignores the top_k set by the LLM and returns the full reranker result up to the maximum number of retrieved chunks. Useful for knowledge bases with long tables that need a wider retrieval range. (Optional) "isMultimodalLlm": boolean // Return whether the chatbot's LLM supports multimodal. "voiceConfig": { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) } "createdBy": { "id": string (uuid) "name": string } "isLocked"?: boolean // Locked instance: config follows the official version; only the dedicated KB can be modified (Optional) "sourceBuildInAgent"?: string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental (Optional) "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } } ] } ``` **Example Response Values** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "largeLanguageModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } }, "embeddingModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "isDefault": false, "isMultimodal": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "image": "https://example.com/file.jpg" } }, "rerankerModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "isDefault": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "image": "https://example.com/file.jpg" } }, "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string", "displayName": "Response string", "toolType": "Response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string" } ], "agentMode": {}, "replyMode": {}, "updatedAt": "Response string", "enableEvaluation": false, "enableInlineCitations": false, "enableToolSearching": false, "toolLoadingMode": "Response string", "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "numberOfRetrievedChunks": 456, "useFullRetrievalRange": false, "isMultimodalLlm": false, "voiceConfig": { "enabled": false }, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } } ] } ``` *** ### Retrieve an AI Assistant GET `/api/v1/chatbots/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request failed:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request failed:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request failed: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response **Status Code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization); it can be omitted on creation only if the organization has configured a default model in its AI assistant defaults "llm": // The bound model’s id, name, and retirement information, read directly from the foreign key; returned even if the organization has disabled the model { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; once reached, a daily scheduled job switches assistants to replacement and disables this model. null means no retirement is scheduled "replacement": // Replacement model after retirement (id and name); null means none is specified, so no automatic migration occurs on the retirement date { "id": string (uuid) "name": string } } "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions as standalone questions before retrieval in RAG response mode; null follows system settings (if the selected model is later blocked or disabled by the organization, this also returns null and follows system settings) (Optional) "defaultCondenseQuestionLlm": // The question rewriting model actually used when following system settings (id and name); null means the assistant’s primary model rewrites questions (read-only) { "id": string (uuid) "name": string } "organizationEnforcedSettings": [ // Setting codes enforced for this assistant by the organization’s AI assistant defaults (matching the keys in the AI assistant defaults API); these fields return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT) string ] "embeddingModel"?: string (uuid) // Embedding model used to vectorize text; optional (Optional) "rerankerModel"?: string (uuid) // Model used for reranking; optional (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // Knowledge bases the chatbot can access (Optional) { "id": string (uuid) "name": string } ] "databases"?: [ // SQL databases the chatbot can access (for Text-to-SQL) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, this is a personal chatbot (Optional) "replyMode"?: // Response mode: normal or streaming responses * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON schema definition for a custom output format (Optional) "groups"?: [ // Groups the chatbot can access (Optional) { "id": string (uuid) "name": string } ] "tools"?: [ // Tools the chatbot can use (Optional) { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills"?: [ // Skills associated with the chatbot (Optional) { "id": string (uuid) "name": string "description": string } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) "name": string } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks retrieved; default: 12, minimum: 1 (Optional) "defaultLabelRelations"?: object // Assistant-level default knowledge base label filters, in the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller omits query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores the LLM’s top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens; minimum: 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; if both are provided, tool_loading_mode takes precedence. On read, returns whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (selected automatically based on the number of tools available for the current turn and the model), all (load all), or search (dynamic search). New assistants default to auto; existing assistants without an explicit setting return the value derived from the legacy toggle (on → search, off → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of long-term memory nodes returned per retrieval (similarity_top_k for vector retrieval); default: 10, range: 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null} "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace. } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } }, "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "defaultCondenseQuestionLlm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "organizationEnforcedSettings": [ "Response string" ], "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Response string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "updatedAt": "Response string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Response string", "unanswerableTemplate": "Response string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string", "displayName": "Response string", "toolType": "Response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "agentMode": {}, "numberOfRetrievedChunks": 456, "defaultLabelRelations": null, "useFullRetrievalRange": false, "enableEvaluation": false, "enableInlineCitations": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "enableClaudeStreamRetry": false, "customMaxLlmOutputTokens": 456, "voiceConfig": { "enabled": false, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Response string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "toolLoadingMode": {}, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "Response string", "requireTextWithFlexCards": false, "isMultimodalLlm": false, "enableSizeBasedToolResultTruncation": false, "toolResultMaxChars": 456, "enableVectorMemory": false, "longTermMemoryTopK": 456, "enableCrossConversationSearch": false, "crossConversationLookbackDays": 456, "useGatewayFallback": false, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": false, "enableGetMessageContextTool": false, "enableReadAttachmentFullTextTool": false, "enableParseAttachmentContentTool": false, "enableListAvailableParsersTool": false, "enableGetDownloadLinkTool": false, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "webChatIsActive": false, "apiIsActive": false, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000", "fileWorkspaceStatus": { "name": "example.pdf", "content": "base64encoded_content", "contentType": "application/pdf" }, "fileWorkspaceAvailable": false } ``` *** ### Update AI Assistant PUT `/api/v1/chatbots/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Yes | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. | | largeLanguageModel | string (uuid) | Yes | The large language model the chatbot uses to generate responses (including custom AI Gateway models created by the organization); may be omitted on creation only if the organization has set a default model in its AI assistant defaults | | condenseQuestionLlm | string (uuid) | No | Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG response mode; null uses the system settings (if the selected model is later blocked or disabled by the organization, reads also return null and use the system settings) | | embeddingModel | string (uuid) | No | Optional embedding model for vectorizing text | | rerankerModel | string (uuid) | No | Optional model for reranking | | instructions | string | No | Role instructions describing the chatbot's role and behavior. | | knowledgeBases | array\[IdName] | No | List of knowledge bases accessible to the chatbot | | databases | array\[IdName] | No | List of SQL databases accessible to the chatbot (for Text-to-SQL) | | organization | string (uuid) | No | The organization the chatbot belongs to; if empty, this is a personal chatbot | | replyMode | object | No | Response mode: normal or streaming responses `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent; | | template | string | No | Template used by Template and Hybrid modes. | | unanswerableTemplate | string | No | Template used by Template and Hybrid modes when the question cannot be answered. | | totalWordsCount | integer (int64) | No | Accumulated total word count used. | | outputMode | object | No | Output mode: text, table, or custom format `text`: Text ; `json_schema`: JSON Schema; | | rawOutputFormat | object | No | JSON structure definition for the custom output format | | groups | array\[IdName] | No | List of groups accessible to the chatbot | | tools | array\[ToolSummary] | No | List of tools available to the chatbot | | skills | array\[SkillSummary] | No | List of skills associated with the chatbot | | connectors | array\[IdName] | No | Connectors associated with this chatbot, gating per-contact OAuth authorization | | agentMode | object | No | Agent mode: normal, SQL, or workflow mode `normal`: Normal ; `canvas`: Canvas ; `team`: Team; | | numberOfRetrievedChunks | integer | No | Number of retrieved reference chunks; defaults to 12, minimum 1 | | defaultLabelRelations | object | No | Assistant-level default knowledge base label filters, in the same format as query\_metadata.label\_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller omits query\_metadata. | | useFullRetrievalRange | boolean | No | When enabled, ignores the LLM top\_k truncation and returns the full reranker results | | enableEvaluation | boolean | No | | | enableInlineCitations | boolean | No | Enables inline citations, inserting citation markers such as \[1]\[2] into responses. | | enableCodeInterpreter | boolean | No | When enabled, provides the Code Interpreter tool to run code in an isolated container. | | enableBrowserTool | boolean | No | Enable browser automation tool for web tasks | | enableImageSearch | boolean | No | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. | | enableClaudeStreamRetry | boolean | No | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu... | | customMaxLlmOutputTokens | integer | No | Custom maximum number of LLM output tokens; minimum 512 | | voiceConfig | object | No | | | voiceConfig.enabled | boolean | No | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. | | voiceConfig.voiceAgentType | string (uuid) | No | Voice agent mode type. | | voiceConfig.sttProvider | string (uuid) | No | Speech-to-Text service provider. | | voiceConfig.sttConfig | object | No | STT configuration parameters (JSON). | | voiceConfig.ttsProvider | string (uuid) | No | Text-to-Speech service provider. | | voiceConfig.ttsConfig | object | No | TTS configuration parameters (JSON). | | voiceConfig.realtimeProvider | string (uuid) | No | Realtime end-to-end voice model provider. | | voiceConfig.realtimeConfig | object | No | Realtime configuration parameters (JSON). | | voiceConfig.realtimeInstructions | string | No | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty | | voiceConfig.turnHandling | object | No | Turn-taking and interruption settings for the voice agent. | | voiceConfig.enableVoiceReply | boolean | No | When disabled, the voice agent replies in text only and does not speak | | thinkingConfig | object | No | Reasoning level: null (model default) or {"reasoning\_effort": "off | | enableToolSearching | boolean | No | Legacy field; use tool\_loading\_mode instead. Writing true is equivalent to tool\_loading\_mode=search, and false to all; when both are provided, tool\_loading\_mode takes precedence. On read, returns whether the tool loading mode is anything other than loading all tools. | | toolLoadingMode | object | No | Tool loading mode: auto (determined automatically by the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never configured this return a value derived from the legacy toggle (on→search, off→all). `auto`: Auto ; `all`: Load all ; `search`: Dynamic search; | | maxAgentIterations | integer | No | Maximum number of iterations for AgentWorkflow (1-100, default: 20) | | agentTimeoutSeconds | integer | No | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) | | agentTimeoutMessage | string | No | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. | | requireTextWithFlexCards | boolean | No | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se... | | enableSizeBasedToolResultTruncation | boolean | No | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati... | | toolResultMaxChars | integer | No | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True. | | enableVectorMemory | boolean | No | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist... | | longTermMemoryTopK | integer | No | Number of memory nodes returned per long-term memory retrieval (similarity\_top\_k for vector retrieval); defaults to 10, range 1–50 | | enableCrossConversationSearch | boolean | No | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. | | crossConversationLookbackDays | integer | No | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... | | useGatewayFallback | boolean | No | When enabled, use the fallback group instead of the single LLM | | gatewayFallbackGroup | string (uuid) | No | | | enableSearchMessagesTool | boolean | No | Allow the AI to search past messages in the current conversation. | | enableGetMessageContextTool | boolean | No | Allow the AI to retrieve messages surrounding a specific message for context. | | enableReadAttachmentFullTextTool | boolean | No | Allow the AI to read the full text of plain-text attachments. AGENT mode only. | | enableParseAttachmentContentTool | boolean | No | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. | | enableListAvailableParsersTool | boolean | No | Allow the AI to list available parsers and their capabilities. AGENT mode only. | | enableGetDownloadLinkTool | boolean | No | Allow the AI to generate shareable download links for produced content. AGENT mode only. | | webChatIsActive | boolean | No | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor... | | apiIsActive | boolean | No | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u... | | fileWorkspaceMode | object | No | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount; | | fileWorkspaceFolder | string (uuid) | No | The bound workspace (folder id); required when the mode is bound, cleared otherwise. | **Request Schema Example** ```typescript { "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // The large language model the chatbot uses to generate responses (including custom AI Gateway models created by the organization); may be omitted on creation only if the organization has set a default model in its AI assistant defaults "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG response mode; null uses the system settings (if the selected model is later blocked or disabled by the organization, reads also return null and use the system settings) (Optional) "embeddingModel"?: string (uuid) // Optional embedding model for vectorizing text (Optional) "rerankerModel"?: string (uuid) // Optional model for reranking (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases accessible to the chatbot (Optional) { "id": string (uuid) } ] "databases"?: [ // List of SQL databases accessible to the chatbot (for Text-to-SQL) (Optional) { "id": string (uuid) } ] "organization"?: string (uuid) // The organization the chatbot belongs to; if empty, this is a personal chatbot (Optional) "replyMode"?: // Response mode: normal or streaming responses * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON structure definition for the custom output format (Optional) "groups"?: [ // List of groups accessible to the chatbot (Optional) { "id": string (uuid) } ] "tools"?: [ // List of tools available to the chatbot (Optional) { "id": string (uuid) } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks; defaults to 12, minimum 1 (Optional) "defaultLabelRelations"?: object // Assistant-level default knowledge base label filters, in the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller omits query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores the LLM top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens; minimum 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; when both are provided, tool_loading_mode takes precedence. On read, returns whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (determined automatically by the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never configured this return a value derived from the legacy toggle (on→search, off→all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of memory nodes returned per long-term memory retrieval (similarity_top_k for vector retrieval); defaults to 10, range 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) } ``` **Example Request Values** ```json { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X PUT "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }; axios.put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": None, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": None, "useFullRetrievalRange": True, "enableEvaluation": True, "enableInlineCitations": True, "enableCodeInterpreter": True, "enableBrowserTool": True, "enableImageSearch": True, "enableClaudeStreamRetry": True, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": True, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": None, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": None, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": None, "realtimeInstructions": "Example string", "turnHandling": None, "enableVoiceReply": True }, "thinkingConfig": None, "enableToolSearching": True, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": True, "enableSizeBasedToolResultTruncation": True, "toolResultMaxChars": 123, "enableVectorMemory": True, "longTermMemoryTopK": 123, "enableCrossConversationSearch": True, "crossConversationLookbackDays": 123, "useGatewayFallback": True, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": True, "enableGetMessageContextTool": True, "enableReadAttachmentFullTextTool": True, "enableParseAttachmentContentTool": True, "enableListAvailableParsersTool": True, "enableGetDownloadLinkTool": True, "webChatIsActive": True, "apiIsActive": True, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } response = requests.put(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name', 'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000', 'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000', 'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000', 'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000', 'instructions' => 'Example string', 'knowledgeBases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'databases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'organization' => '550e8400-e29b-41d4-a716-446655440000', 'replyMode' => new \stdClass(), 'template' => 'Example string', 'unanswerableTemplate' => 'Example string', 'totalWordsCount' => 123, 'outputMode' => new \stdClass(), 'rawOutputFormat' => null, 'groups' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'tools' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'skills' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'connectors' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'agentMode' => new \stdClass(), 'numberOfRetrievedChunks' => 123, 'defaultLabelRelations' => null, 'useFullRetrievalRange' => true, 'enableEvaluation' => true, 'enableInlineCitations' => true, 'enableCodeInterpreter' => true, 'enableBrowserTool' => true, 'enableImageSearch' => true, 'enableClaudeStreamRetry' => true, 'customMaxLlmOutputTokens' => 123, 'voiceConfig' => [ 'enabled' => true, 'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000', 'sttProvider' => '550e8400-e29b-41d4-a716-446655440000', 'sttConfig' => null, 'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000', 'ttsConfig' => null, 'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000', 'realtimeConfig' => null, 'realtimeInstructions' => 'Example string', 'turnHandling' => null, 'enableVoiceReply' => true ], 'thinkingConfig' => null, 'enableToolSearching' => true, 'toolLoadingMode' => new \stdClass(), 'maxAgentIterations' => 123, 'agentTimeoutSeconds' => 123, 'agentTimeoutMessage' => 'Example string', 'requireTextWithFlexCards' => true, 'enableSizeBasedToolResultTruncation' => true, 'toolResultMaxChars' => 123, 'enableVectorMemory' => true, 'longTermMemoryTopK' => 123, 'enableCrossConversationSearch' => true, 'crossConversationLookbackDays' => 123, 'useGatewayFallback' => true, 'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000', 'enableSearchMessagesTool' => true, 'enableGetMessageContextTool' => true, 'enableReadAttachmentFullTextTool' => true, 'enableParseAttachmentContentTool' => true, 'enableListAvailableParsersTool' => true, 'enableGetDownloadLinkTool' => true, 'webChatIsActive' => true, 'apiIsActive' => true, 'fileWorkspaceMode' => new \stdClass(), 'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response body **Status code: 200** **Example response structure** ```typescript { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization); it can be omitted at creation only if the organization has configured a default model in its AI assistant defaults "llm": // The bound model’s id, name, and retirement information, read directly from the FK; returned even if the organization has disabled the model { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; once reached, the daily scheduled job switches the assistant to the replacement and disables this model. null indicates that no retirement is scheduled "replacement": // The replacement model after retirement (id and name); null indicates that none is specified and no automatic migration occurs on the retirement date { "id": string (uuid) "name": string } } "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions as standalone questions before retrieval in RAG reply mode; null uses the system setting (if the organization later blocks or disables the selected model, reads also return null and use the system setting) (Optional) "defaultCondenseQuestionLlm": // The question rewriting model actually used when following the system setting (id and name); null indicates that the assistant’s primary model performs rewriting (read-only) { "id": string (uuid) "name": string } "organizationEnforcedSettings": [ // Codes for the settings enforced on this assistant by the organization’s AI assistant defaults (matching the keys in the AI assistant defaults API); reads return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT) string ] "embeddingModel"?: string (uuid) // Optional embedding model for vectorizing text (Optional) "rerankerModel"?: string (uuid) // Optional model for reranking (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases accessible to the chatbot (Optional) { "id": string (uuid) "name": string } ] "databases"?: [ // List of SQL databases accessible to the chatbot (for Text-to-SQL) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // The organization the chatbot belongs to; if empty, it is a personal chatbot (Optional) "replyMode"?: // Reply mode: normal or streaming replies * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional) "groups"?: [ // List of groups accessible to the chatbot (Optional) { "id": string (uuid) "name": string } ] "tools"?: [ // List of tools available to the chatbot (Optional) { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) "name": string "description": string } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) "name": string } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; default: 12, minimum: 1 (Optional) "defaultLabelRelations"?: object // Default assistant-level knowledge base label filters, using the same format as query_metadata.label_relations; null means no filtering. Applied only as the lowest-priority fallback when the caller does not supply query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores LLM top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens; minimum: 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; if both are supplied, tool_loading_mode takes precedence. Reads return whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (automatically determined by the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants without an explicit setting return the value derived from the legacy toggle (on → search, off → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of long-term memory nodes retrieved per search (similarity_top_k for vector retrieval). Defaults to 10; range: 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null} "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace. } ``` **Example Response Value** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string", "retiresAt": "response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" } }, "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "defaultCondenseQuestionLlm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" }, "organizationEnforcedSettings": [ "response string" ], "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "response string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" } ], "updatedAt": "response string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "response string", "unanswerableTemplate": "response string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string", "description": "response string", "displayName": "response string", "toolType": "response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string", "description": "response string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" } ], "agentMode": {}, "numberOfRetrievedChunks": 456, "defaultLabelRelations": null, "useFullRetrievalRange": false, "enableEvaluation": false, "enableInlineCitations": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "enableClaudeStreamRetry": false, "customMaxLlmOutputTokens": 456, "voiceConfig": { "enabled": false, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "response string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "toolLoadingMode": {}, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "response string", "requireTextWithFlexCards": false, "isMultimodalLlm": false, "enableSizeBasedToolResultTruncation": false, "toolResultMaxChars": 456, "enableVectorMemory": false, "longTermMemoryTopK": 456, "enableCrossConversationSearch": false, "crossConversationLookbackDays": 456, "useGatewayFallback": false, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": false, "enableGetMessageContextTool": false, "enableReadAttachmentFullTextTool": false, "enableParseAttachmentContentTool": false, "enableListAvailableParsersTool": false, "enableGetDownloadLinkTool": false, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "response string" }, "webChatIsActive": false, "apiIsActive": false, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000", "fileWorkspaceStatus": { "name": "example.pdf", "content": "base64encoded_content", "contentType": "application/pdf" }, "fileWorkspaceAvailable": false } ``` *** ### Partially Update an AI Assistant PATCH `/api/v1/chatbots/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | No | Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. | | largeLanguageModel | string (uuid) | No | Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization). Can be omitted on creation only if the organization has configured a default model in its AI assistant defaults | | condenseQuestionLlm | string (uuid) | No | Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode. null follows the system settings (if the selected model is later blocked or disabled by the organization, this also reads back as null and follows the system settings) | | embeddingModel | string (uuid) | No | Optional embedding model used to vectorize text | | rerankerModel | string (uuid) | No | Optional model used for reranking | | instructions | string | No | Role instructions describing the chatbot's role and behavior. | | knowledgeBases | array\[IdName] | No | List of knowledge bases the chatbot can access | | databases | array\[IdName] | No | List of SQL databases the chatbot can access (for the Text-to-SQL feature) | | organization | string (uuid) | No | Organization the chatbot belongs to; if empty, this is a personal chatbot | | replyMode | object | No | Reply mode: normal or streaming responses `normal`: Normal ; `template`: Template ; `hybrid`: Hybrid ; `agent`: Agent; | | template | string | No | Template used by Template and Hybrid modes. | | unanswerableTemplate | string | No | Template used by Template and Hybrid modes when the question cannot be answered. | | totalWordsCount | integer (int64) | No | Accumulated total word count used. | | outputMode | object | No | Output mode: text, table, or custom format `text`: Text ; `json_schema`: JSON Schema; | | rawOutputFormat | object | No | JSON schema definition for the custom output format | | groups | array\[IdName] | No | List of groups the chatbot can access | | tools | array\[ToolSummary] | No | List of tools the chatbot can use | | skills | array\[SkillSummary] | No | List of skills associated with the chatbot | | connectors | array\[IdName] | No | Connectors associated with this chatbot, gating per-contact OAuth authorization | | agentMode | object | No | Agent mode: normal, SQL, or workflow mode `normal`: Normal ; `canvas`: Canvas ; `team`: Team; | | numberOfRetrievedChunks | integer | No | Number of reference chunks to retrieve. Defaults to 12; minimum: 1 | | defaultLabelRelations | object | No | Default assistant-level knowledge base label filters, using the same format as query\_metadata.label\_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller does not provide query\_metadata. | | useFullRetrievalRange | boolean | No | When enabled, ignores LLM top\_k truncation and returns the full reranker results | | enableEvaluation | boolean | No | | | enableInlineCitations | boolean | No | Enables inline citations, inserting citation markers such as \[1]\[2] into responses. | | enableCodeInterpreter | boolean | No | When enabled, provides the Code Interpreter tool to run code in an isolated container. | | enableBrowserTool | boolean | No | Enable browser automation tool for web tasks | | enableImageSearch | boolean | No | Provide the image\_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. | | enableClaudeStreamRetry | boolean | No | When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial outpu... | | customMaxLlmOutputTokens | integer | No | Custom maximum number of LLM output tokens; minimum: 512 | | voiceConfig | object | No | | | voiceConfig.enabled | boolean | No | Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. | | voiceConfig.voiceAgentType | string (uuid) | No | Voice agent mode type. | | voiceConfig.sttProvider | string (uuid) | No | Speech-to-Text service provider. | | voiceConfig.sttConfig | object | No | STT configuration parameters (JSON). | | voiceConfig.ttsProvider | string (uuid) | No | Text-to-Speech service provider. | | voiceConfig.ttsConfig | object | No | TTS configuration parameters (JSON). | | voiceConfig.realtimeProvider | string (uuid) | No | Realtime end-to-end voice model provider. | | voiceConfig.realtimeConfig | object | No | Realtime configuration parameters (JSON). | | voiceConfig.realtimeInstructions | string | No | Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty | | voiceConfig.turnHandling | object | No | Turn-taking and interruption settings for the voice agent. | | voiceConfig.enableVoiceReply | boolean | No | When disabled, the voice agent replies in text only and does not speak | | thinkingConfig | object | No | Reasoning level: null (model default) or {"reasoning\_effort": "off | | enableToolSearching | boolean | No | Legacy field; use tool\_loading\_mode instead. Writing true is equivalent to tool\_loading\_mode=search, and false to all; if both are provided, tool\_loading\_mode takes precedence. On read, returns whether the tool loading mode is anything other than all. | | toolLoadingMode | object | No | Tool loading mode: auto (automatically determined by the number of tools available in the current turn and the model), all (load all), or search (dynamic search). New assistants default to auto; existing assistants with no explicit setting return the value mapped from the legacy toggle (on→search, off→all). `auto`: Auto ; `all`: Load all ; `search`: Dynamic search; | | maxAgentIterations | integer | No | Maximum number of iterations for AgentWorkflow (1-100, default: 20) | | agentTimeoutSeconds | integer | No | Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) | | agentTimeoutMessage | string | No | Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. | | requireTextWithFlexCards | boolean | No | When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a se... | | enableSizeBasedToolResultTruncation | boolean | No | When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversati... | | toolResultMaxChars | integer | No | Character threshold for size-based tool result truncation (500-50000). Only effective when enable\_size\_based\_tool\_result\_truncation is True. | | enableVectorMemory | boolean | No | When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat hist... | | longTermMemoryTopK | integer | No | Number of long-term memory nodes retrieved per search (similarity\_top\_k for vector retrieval). Defaults to 10; range: 1–50 | | enableCrossConversationSearch | boolean | No | When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. | | crossConversationLookbackDays | integer | No | How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable\_cross\_conversation\_search... | | useGatewayFallback | boolean | No | When enabled, use the fallback group instead of the single LLM | | gatewayFallbackGroup | string (uuid) | No | | | enableSearchMessagesTool | boolean | No | Allow the AI to search past messages in the current conversation. | | enableGetMessageContextTool | boolean | No | Allow the AI to retrieve messages surrounding a specific message for context. | | enableReadAttachmentFullTextTool | boolean | No | Allow the AI to read the full text of plain-text attachments. AGENT mode only. | | enableParseAttachmentContentTool | boolean | No | Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. | | enableListAvailableParsersTool | boolean | No | Allow the AI to list available parsers and their capabilities. AGENT mode only. | | enableGetDownloadLinkTool | boolean | No | Allow the AI to generate shareable download links for produced content. AGENT mode only. | | webChatIsActive | boolean | No | Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignor... | | apiIsActive | boolean | No | Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on u... | | fileWorkspaceMode | object | No | File workspace mode in Work internal conversations: none, bound or user\_mount. `none`: None ; `bound`: Bound workspace ; `user_mount`: User mount; | | fileWorkspaceFolder | string (uuid) | No | The bound workspace (folder id); required when the mode is bound, cleared otherwise. | **Example Request Schema** ```typescript { "name"?: string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. (Optional) "largeLanguageModel"?: string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization). Can be omitted on creation only if the organization has configured a default model in its AI assistant defaults (Optional) "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode. null follows the system settings (if the selected model is later blocked or disabled by the organization, this also reads back as null and follows the system settings) (Optional) "embeddingModel"?: string (uuid) // Optional embedding model used to vectorize text (Optional) "rerankerModel"?: string (uuid) // Optional model used for reranking (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases the chatbot can access (Optional) { "id": string (uuid) } ] "databases"?: [ // List of SQL databases the chatbot can access (for the Text-to-SQL feature) (Optional) { "id": string (uuid) } ] "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, this is a personal chatbot (Optional) "replyMode"?: // Reply mode: normal or streaming responses * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional) "groups"?: [ // List of groups the chatbot can access (Optional) { "id": string (uuid) } ] "tools"?: [ // List of tools the chatbot can use (Optional) { "id": string (uuid) } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, with a minimum of 1 (Optional) "defaultLabelRelations"?: object // Default knowledge base label filters at the assistant level, using the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller does not provide query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores the LLM top_k truncation and returns the complete reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens, with a minimum of 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning effort: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false is equivalent to all; if both fields are provided, tool_loading_mode takes precedence. When read, returns whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (automatically determined by the number of tools available for the current turn and the model), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never set this field return a value derived from the legacy toggle (enabled → search, disabled → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of long-term memory nodes returned per retrieval (similarity_top_k for vector retrieval); defaults to 10, with a range of 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) } ``` **Example Request Values** ```json { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API call (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": null, "useFullRetrievalRange": true, "enableEvaluation": true, "enableInlineCitations": true, "enableCodeInterpreter": true, "enableBrowserTool": true, "enableImageSearch": true, "enableClaudeStreamRetry": true, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": true, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Example string", "turnHandling": null, "enableVoiceReply": true }, "thinkingConfig": null, "enableToolSearching": true, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": true, "enableSizeBasedToolResultTruncation": true, "toolResultMaxChars": 123, "enableVectorMemory": true, "longTermMemoryTopK": 123, "enableCrossConversationSearch": true, "crossConversationLookbackDays": 123, "useGatewayFallback": true, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": true, "enableGetMessageContextTool": true, "enableReadAttachmentFullTextTool": true, "enableParseAttachmentContentTool": true, "enableListAvailableParsersTool": true, "enableGetDownloadLinkTool": true, "webChatIsActive": true, "apiIsActive": true, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" }; axios.patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "name": "Example name", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 123, "outputMode": {}, "rawOutputFormat": None, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ], "agentMode": {}, "numberOfRetrievedChunks": 123, "defaultLabelRelations": None, "useFullRetrievalRange": True, "enableEvaluation": True, "enableInlineCitations": True, "enableCodeInterpreter": True, "enableBrowserTool": True, "enableImageSearch": True, "enableClaudeStreamRetry": True, "customMaxLlmOutputTokens": 123, "voiceConfig": { "enabled": True, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": None, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": None, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": None, "realtimeInstructions": "Example string", "turnHandling": None, "enableVoiceReply": True }, "thinkingConfig": None, "enableToolSearching": True, "toolLoadingMode": {}, "maxAgentIterations": 123, "agentTimeoutSeconds": 123, "agentTimeoutMessage": "Example string", "requireTextWithFlexCards": True, "enableSizeBasedToolResultTruncation": True, "toolResultMaxChars": 123, "enableVectorMemory": True, "longTermMemoryTopK": 123, "enableCrossConversationSearch": True, "crossConversationLookbackDays": 123, "useGatewayFallback": True, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": True, "enableGetMessageContextTool": True, "enableReadAttachmentFullTextTool": True, "enableParseAttachmentContentTool": True, "enableListAvailableParsersTool": True, "enableGetDownloadLinkTool": True, "webChatIsActive": True, "apiIsActive": True, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000" } response = requests.patch(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name', 'largeLanguageModel' => '550e8400-e29b-41d4-a716-446655440000', 'condenseQuestionLlm' => '550e8400-e29b-41d4-a716-446655440000', 'embeddingModel' => '550e8400-e29b-41d4-a716-446655440000', 'rerankerModel' => '550e8400-e29b-41d4-a716-446655440000', 'instructions' => 'Example string', 'knowledgeBases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'databases' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'organization' => '550e8400-e29b-41d4-a716-446655440000', 'replyMode' => new \stdClass(), 'template' => 'Example string', 'unanswerableTemplate' => 'Example string', 'totalWordsCount' => 123, 'outputMode' => new \stdClass(), 'rawOutputFormat' => null, 'groups' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'tools' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'skills' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'connectors' => [ [ 'id' => '550e8400-e29b-41d4-a716-446655440000' ] ], 'agentMode' => new \stdClass(), 'numberOfRetrievedChunks' => 123, 'defaultLabelRelations' => null, 'useFullRetrievalRange' => true, 'enableEvaluation' => true, 'enableInlineCitations' => true, 'enableCodeInterpreter' => true, 'enableBrowserTool' => true, 'enableImageSearch' => true, 'enableClaudeStreamRetry' => true, 'customMaxLlmOutputTokens' => 123, 'voiceConfig' => [ 'enabled' => true, 'voiceAgentType' => '550e8400-e29b-41d4-a716-446655440000', 'sttProvider' => '550e8400-e29b-41d4-a716-446655440000', 'sttConfig' => null, 'ttsProvider' => '550e8400-e29b-41d4-a716-446655440000', 'ttsConfig' => null, 'realtimeProvider' => '550e8400-e29b-41d4-a716-446655440000', 'realtimeConfig' => null, 'realtimeInstructions' => 'Example string', 'turnHandling' => null, 'enableVoiceReply' => true ], 'thinkingConfig' => null, 'enableToolSearching' => true, 'toolLoadingMode' => new \stdClass(), 'maxAgentIterations' => 123, 'agentTimeoutSeconds' => 123, 'agentTimeoutMessage' => 'Example string', 'requireTextWithFlexCards' => true, 'enableSizeBasedToolResultTruncation' => true, 'toolResultMaxChars' => 123, 'enableVectorMemory' => true, 'longTermMemoryTopK' => 123, 'enableCrossConversationSearch' => true, 'crossConversationLookbackDays' => 123, 'useGatewayFallback' => true, 'gatewayFallbackGroup' => '550e8400-e29b-41d4-a716-446655440000', 'enableSearchMessagesTool' => true, 'enableGetMessageContextTool' => true, 'enableReadAttachmentFullTextTool' => true, 'enableParseAttachmentContentTool' => true, 'enableListAvailableParsersTool' => true, 'enableGetDownloadLinkTool' => true, 'webChatIsActive' => true, 'apiIsActive' => true, 'fileWorkspaceMode' => new \stdClass(), 'fileWorkspaceFolder' => '550e8400-e29b-41d4-a716-446655440000' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response **Status code: 200** **Example response schema** ```typescript { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate answers (including organization-defined AI Gateway models); on creation, this can be omitted only if the organization has set a default model in AI assistant defaults "llm": // The bound model’s id, name, and retirement information, read directly from the FK and returned even if the organization has disabled the model { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; once reached, a daily scheduled task switches the assistant to the replacement and disables this model. null means no retirement is scheduled "replacement": // The model taking over after retirement (id and name); null means none is specified, so no automatic migration occurs on retirement { "id": string (uuid) "name": string } } "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode; null follows system settings (if the selected model is later blocked or disabled by the organization, this also returns null and follows system settings) (Optional) "defaultCondenseQuestionLlm": // The question rewriting model actually used when following system settings (id and name); null means the assistant’s primary model handles rewriting (read-only) { "id": string (uuid) "name": string } "organizationEnforcedSettings": [ // Setting codes enforced for this assistant by the organization’s AI assistant defaults (matching the keys in the AI assistant defaults API); these fields return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT) string ] "embeddingModel"?: string (uuid) // Embedding model used to vectorize text, optional (Optional) "rerankerModel"?: string (uuid) // Model used for reranking, optional (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases the chatbot can access (Optional) { "id": string (uuid) "name": string } ] "databases"?: [ // List of SQL databases the chatbot can access (for Text-to-SQL) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, this is a personal chatbot (Optional) "replyMode"?: // Reply mode: normal or streaming replies * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional) "groups"?: [ // List of groups the chatbot can access (Optional) { "id": string (uuid) "name": string } ] "tools"?: [ // List of tools the chatbot can use (Optional) { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) "name": string "description": string } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) "name": string } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks retrieved; defaults to 12, minimum 1 (Optional) "defaultLabelRelations"?: object // Default knowledge base label filters at the assistant level, in the same format as query_metadata.label_relations; null means no filtering. Applied only as the lowest-priority fallback when the caller omits query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores the LLM’s top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum LLM output tokens, minimum 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Thinking level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; tool_loading_mode takes precedence when both are provided. On read, returns whether the tool loading mode is not load all. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (automatic, based on the tools available for the current turn and the model), all (load all), or search (dynamic search). New assistants default to auto; existing assistants that have never configured this return a value derived from the old toggle (on → search, off → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of memory nodes retrieved from long-term memory per query (similarity_top_k for vector retrieval); defaults to 10, range 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null} "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace. } ``` **Example response values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } }, "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "defaultCondenseQuestionLlm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "organizationEnforcedSettings": [ "Response string" ], "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Response string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "updatedAt": "Response string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Response string", "unanswerableTemplate": "Response string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string", "displayName": "Response string", "toolType": "Response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "agentMode": {}, "numberOfRetrievedChunks": 456, "defaultLabelRelations": null, "useFullRetrievalRange": false, "enableEvaluation": false, "enableInlineCitations": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "enableClaudeStreamRetry": false, "customMaxLlmOutputTokens": 456, "voiceConfig": { "enabled": false, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Response string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "toolLoadingMode": {}, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "Response string", "requireTextWithFlexCards": false, "isMultimodalLlm": false, "enableSizeBasedToolResultTruncation": false, "toolResultMaxChars": 456, "enableVectorMemory": false, "longTermMemoryTopK": 456, "enableCrossConversationSearch": false, "crossConversationLookbackDays": 456, "useGatewayFallback": false, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": false, "enableGetMessageContextTool": false, "enableReadAttachmentFullTextTool": false, "enableParseAttachmentContentTool": false, "enableListAvailableParsersTool": false, "enableGetDownloadLinkTool": false, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "webChatIsActive": false, "apiIsActive": false, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000", "fileWorkspaceStatus": { "name": "example.pdf", "content": "base64encoded_content", "contentType": "application/pdf" }, "fileWorkspaceAvailable": false } ``` *** ### Delete AI Assistant DELETE `/api/v1/chatbots/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X DELETE "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; // Request body (payload) const data = null; axios.delete("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.delete(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php delete("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body | Status Code | Description | | ----------- | ---------------- | | 204 | No response body | *** ### Duplicate AI Assistant POST `/api/v1/chatbots/{id}/duplicate/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----- | ------ | -------- | ----------- | | name | string | Yes | | **Example Request Schema** ```typescript { "name": string } ``` **Example Request Values** ```json { "name": "Example name" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "name": "Example name" }; axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "name": "Example name" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots. "largeLanguageModel": string (uuid) // The large language model used by the chatbot to generate responses (including organization-defined AI Gateway models); may be omitted on creation only if the organization has configured a default model in its AI assistant defaults "llm": // The bound model's id, name, and retirement information, read directly from the FK and returned even if the organization has disabled the model { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; once reached, the daily scheduled job switches assistants to the replacement and disables this model. null means no retirement is scheduled "replacement": // The replacement model after retirement (id and name); null means none is specified, so no automatic migration occurs on retirement { "id": string (uuid) "name": string } } "condenseQuestionLlm"?: string (uuid) // Question rewriting model: rewrites follow-up questions into standalone questions before retrieval in RAG reply mode; null follows system settings (if the selected model is later blocked or disabled by the organization, reads also return null and follow system settings) (Optional) "defaultCondenseQuestionLlm": // The question rewriting model actually used when following system settings (id and name); null means the assistant's primary model handles rewriting (read-only) { "id": string (uuid) "name": string } "organizationEnforcedSettings": [ // Setting codes enforced for this assistant by the organization's AI assistant defaults (matching the keys in the AI assistant defaults API); these fields return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT) string ] "embeddingModel"?: string (uuid) // Embedding model used to vectorize text; optional (Optional) "rerankerModel"?: string (uuid) // Model used for reranking; optional (Optional) "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional) "knowledgeBases"?: [ // List of knowledge bases accessible to the chatbot (Optional) { "id": string (uuid) "name": string } ] "databases"?: [ // List of SQL databases accessible to the chatbot (for Text-to-SQL) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // The organization the chatbot belongs to; empty for a personal chatbot (Optional) "replyMode"?: // Reply mode: normal or streaming responses * `normal` - Normal * `template` - Template * `hybrid` - Hybrid * `agent` - Agent (Optional) { } "template"?: string // Template used by Template and Hybrid modes. (Optional) "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional) "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional) "outputMode"?: // Output mode: text, table, or custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional) "groups"?: [ // List of groups accessible to the chatbot (Optional) { "id": string (uuid) "name": string } ] "tools"?: [ // List of tools available to the chatbot (Optional) { "id": string (uuid) "name": string "description": string "displayName": string "toolType": string } ] "skills"?: [ // List of skills associated with the chatbot (Optional) { "id": string (uuid) "name": string "description": string } ] "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional) { "id": string (uuid) "name": string } ] "agentMode"?: // Agent mode: normal, SQL, or workflow mode * `normal` - Normal * `canvas` - Canvas * `team` - Team (Optional) { } "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, minimum 1 (Optional) "defaultLabelRelations"?: object // Assistant-level default knowledge base label filter, using the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller omits query_metadata. (Optional) "useFullRetrievalRange"?: boolean // When enabled, ignores LLM top_k truncation and returns the full reranker results (Optional) "enableEvaluation"?: boolean // Optional "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional) "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional) "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional) "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional) "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (Optional) "customMaxLlmOutputTokens"?: integer // Custom maximum LLM output token count; minimum 512 (Optional) "voiceConfig"?: { // Optional { "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (Optional) "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional) "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional) "sttConfig"?: object // STT configuration parameters (JSON). (Optional) "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional) "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional) "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional) "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional) "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional) "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional) "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional) } } "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; if both are provided, tool_loading_mode takes precedence. Reads return whether the tool loading mode is anything other than loading all tools. (Optional) "toolLoadingMode"?: // Tool loading mode: auto (automatic, based on the tools available in the current turn and the model), all (load all), or search (dynamic search). New assistants default to auto; existing assistants without this setting return a value derived from the legacy toggle (on → search, off → all). * `auto` - Auto * `all` - Load all * `search` - Dynamic search (Optional) { } "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional) "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional) "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional) "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (Optional) "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only) "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (Optional) "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional) "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (Optional) "longTermMemoryTopK"?: integer // Number of long-term memory nodes returned per retrieval (similarity_top_k for vector retrieval); defaults to 10, range 1–50 (Optional) "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (Optional) "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (Optional) "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional) "gatewayFallbackGroup"?: string (uuid) // Optional "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional) "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional) "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional) "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional) "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional) "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional) "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "team": { "id": string (uuid) "name": string } "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (Optional) "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (Optional) "fileWorkspaceMode"?: // File workspace mode in Work internal conversations: none, bound or user_mount. * `none` - None * `bound` - Bound workspace * `user_mount` - User mount (Optional) { } "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional) "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null} "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace. } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "retiresAt": "Response string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } }, "condenseQuestionLlm": "550e8400-e29b-41d4-a716-446655440000", "defaultCondenseQuestionLlm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "organizationEnforcedSettings": [ "Response string" ], "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Response string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "updatedAt": "Response string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Response string", "unanswerableTemplate": "Response string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string", "displayName": "Response string", "toolType": "Response string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "description": "Response string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" } ], "agentMode": {}, "numberOfRetrievedChunks": 456, "defaultLabelRelations": null, "useFullRetrievalRange": false, "enableEvaluation": false, "enableInlineCitations": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "enableClaudeStreamRetry": false, "customMaxLlmOutputTokens": 456, "voiceConfig": { "enabled": false, "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000", "sttProvider": "550e8400-e29b-41d4-a716-446655440000", "sttConfig": null, "ttsProvider": "550e8400-e29b-41d4-a716-446655440000", "ttsConfig": null, "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000", "realtimeConfig": null, "realtimeInstructions": "Response string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "toolLoadingMode": {}, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "Response string", "requireTextWithFlexCards": false, "isMultimodalLlm": false, "enableSizeBasedToolResultTruncation": false, "toolResultMaxChars": 456, "enableVectorMemory": false, "longTermMemoryTopK": 456, "enableCrossConversationSearch": false, "crossConversationLookbackDays": 456, "useGatewayFallback": false, "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000", "enableSearchMessagesTool": false, "enableGetMessageContextTool": false, "enableReadAttachmentFullTextTool": false, "enableParseAttachmentContentTool": false, "enableListAvailableParsersTool": false, "enableGetDownloadLinkTool": false, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string" }, "webChatIsActive": false, "apiIsActive": false, "fileWorkspaceMode": {}, "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000", "fileWorkspaceStatus": { "name": "example.pdf", "content": "base64encoded_content", "contentType": "application/pdf" }, "fileWorkspaceAvailable": false } ``` *** ### Enable or Disable Evaluation PATCH `/api/v1/chatbots/{id}/enable-evaluation/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ---------------- | ------- | -------- | ----------- | | enableEvaluation | boolean | No | | **Example Request Schema** ```typescript { "enableEvaluation"?: boolean // Optional } ``` **Example Request Values** ```json { "enableEvaluation": true } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enableEvaluation": true }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "enableEvaluation": true }; axios.patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "enableEvaluation": True } response = requests.patch(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'enableEvaluation' => true ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "enableEvaluation"?: boolean // Optional } ``` **Example Response Values** ```json { "enableEvaluation": false } ``` *** ### List Hooks in the Organization GET `/api/v1/hooks/` {% hint style="info" %} Hooks are created from Hook templates. The template determines the trigger point and processing behavior; these cannot be specified independently when creating a Hook. Once attached to an AI assistant, a Hook runs on incoming and outgoing messages. For details, see [Hook Message Interception](https://docs.maiagent.ai/build/hook) in the user manual. {% endhint %} #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------- | ---------------------------------------------- | | `page` | ❌ | integer | A page number within the paginated result set. | | `pageSize` | ❌ | integer | Number of results to return per page. | | `search` | ❌ | string | A search term. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/hooks/?page=1&pageSize=1&search=example" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/hooks/?page=1&pageSize=1&search=example", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/hooks/?page=1&pageSize=1&search=example" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/hooks/?page=1&pageSize=1&search=example", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "count": integer "next"?: string (uri) // Optional "previous"?: string (uri) // Optional "results": [ { "id": string (uuid) "organization": string (uuid) "templateId": string (uuid) "templateName": string "templateTypeLabel": string "scope": string "name": string "description": string "triggerPoint": string "action": string "handlerType": string "config": object "blockMessage": string "enabled": boolean "createdBy": object "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched ``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1. object ] "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "createdAt": string (timestamp) "updatedAt": string (timestamp) } ] } ``` **Example Response Values** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "templateId": "550e8400-e29b-41d4-a716-446655440000", "templateName": "Response string", "templateTypeLabel": "Response string", "scope": "Response string", "name": "Response string", "description": "Response string", "triggerPoint": "Response string", "action": "Response string", "handlerType": "Response string", "config": null, "blockMessage": "Response string", "enabled": false, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" }, "chatbots": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } ], "canUpdate": false, "canDelete": false, "createdAt": "Response string", "updatedAt": "Response string" } ] } ``` *** ### Create a Hook from a Template POST `/api/v1/hooks/` #### Request Body **Request Parameters** | Field | Type | Required | Description | | ------------ | ------------- | -------- | ----------- | | templateId | string (uuid) | Yes | | | name | string | Yes | | | description | string | No | | | config | object | No | | | blockMessage | string | No | | | enabled | boolean | No | | **Example Request Schema** ```typescript { "templateId": string (uuid) "name": string "description"?: string // Optional "config"?: object // Optional "blockMessage"?: string // Optional "enabled"?: boolean // Optional } ``` **Example Request Values** ```json { "template_id": "00000000-0000-0000-0000-000000000001", "name": "Customer PII Redaction", "description": "Mask phone numbers and emails in inbound messages.", "config": { "data": { "patterns": [ "phone", "email" ], "mode": "mask" } }, "block_message": "", "enabled": true } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X POST "https://api.maiagent.ai/api/v1/hooks/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "template_id": "00000000-0000-0000-0000-000000000001", "name": "Customer PII Redaction", "description": "Mask phone numbers and emails in inbound messages.", "config": { "data": { "patterns": [ "phone", "email" ], "mode": "mask" } }, "block_message": "", "enabled": true }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (payload) const data = { "template_id": "00000000-0000-0000-0000-000000000001", "name": "Customer PII Redaction", "description": "Mask phone numbers and emails in inbound messages.", "config": { "data": { "patterns": [ "phone", "email" ], "mode": "mask" } }, "block_message": "", "enabled": true }; axios.post("https://api.maiagent.ai/api/v1/hooks/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/hooks/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request Body (payload) data = { "template_id": "00000000-0000-0000-0000-000000000001", "name": "Customer PII Redaction", "description": "Mask phone numbers and emails in inbound messages.", "config": { "data": { "patterns": [ "phone", "email" ], "mode": "mask" } }, "block_message": "", "enabled": True } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/hooks/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'template_id' => '00000000-0000-0000-0000-000000000001', 'name' => 'Customer PII Redaction', 'description' => 'Mask phone numbers and emails in inbound messages.', 'config' => [ 'data' => [ 'patterns' => [ 'phone', 'email' ], 'mode' => 'mask' ] ], 'block_message' => '', 'enabled' => true ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "organization": string (uuid) "templateId": string (uuid) "templateName": string "templateTypeLabel": string "scope": string "name": string "description": string "triggerPoint": string "action": string "handlerType": string "config": object "blockMessage": string "enabled": boolean "createdBy": object "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched ``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1. object ] "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "templateId": "550e8400-e29b-41d4-a716-446655440000", "templateName": "Response string", "templateTypeLabel": "Response string", "scope": "Response string", "name": "Response string", "description": "Response string", "triggerPoint": "Response string", "action": "Response string", "handlerType": "Response string", "config": null, "blockMessage": "Response string", "enabled": false, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" }, "chatbots": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } ], "canUpdate": false, "canDelete": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Retrieve a Specific Hook GET `/api/v1/hooks/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "organization": string (uuid) "templateId": string (uuid) "templateName": string "templateTypeLabel": string "scope": string "name": string "description": string "triggerPoint": string "action": string "handlerType": string "config": object "blockMessage": string "enabled": boolean "createdBy": object "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched ``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1. object ] "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "templateId": "550e8400-e29b-41d4-a716-446655440000", "templateName": "Response string", "templateTypeLabel": "Response string", "scope": "Response string", "name": "Response string", "description": "Response string", "triggerPoint": "Response string", "action": "Response string", "handlerType": "Response string", "config": null, "blockMessage": "Response string", "enabled": false, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" }, "chatbots": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } ], "canUpdate": false, "canDelete": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Partially Update a Hook PATCH `/api/v1/hooks/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ------------ | ------- | -------- | ----------- | | name | string | No | | | description | string | No | | | config | object | No | | | blockMessage | string | No | | | enabled | boolean | No | | **Example Request Schema** ```typescript { "name"?: string // Optional "description"?: string // Optional "config"?: object // Optional "blockMessage"?: string // Optional "enabled"?: boolean // Optional } ``` **Example Request Values** ```json { "name": "Example name", "description": "Example string", "config": null, "blockMessage": "Example string", "enabled": true } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name", "description": "Example string", "config": null, "blockMessage": "Example string", "enabled": true }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (payload) const data = { "name": "Example name", "description": "Example string", "config": null, "blockMessage": "Example string", "enabled": true }; axios.patch("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request Body (payload) data = { "name": "Example name", "description": "Example string", "config": None, "blockMessage": "Example string", "enabled": True } response = requests.patch(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name', 'description' => 'Example string', 'config' => null, 'blockMessage' => 'Example string', 'enabled' => true ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "organization": string (uuid) "templateId": string (uuid) "templateName": string "templateTypeLabel": string "scope": string "name": string "description": string "triggerPoint": string "action": string "handlerType": string "config": object "blockMessage": string "enabled": boolean "createdBy": object "chatbots": [ // Attached AI assistants for the list column. Uses the prefetched ``chatbot_attachments`` (see ``HookViewSet.get_queryset``) to avoid N+1. object ] "canUpdate": boolean // Return whether the current user can update this resource. "canDelete": boolean // Return whether the current user can delete this resource. "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "templateId": "550e8400-e29b-41d4-a716-446655440000", "templateName": "Response string", "templateTypeLabel": "Response string", "scope": "Response string", "name": "Response string", "description": "Response string", "triggerPoint": "Response string", "action": "Response string", "handlerType": "Response string", "config": null, "blockMessage": "Response string", "enabled": false, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" }, "chatbots": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example response name", "description": "Example response description" } ], "canUpdate": false, "canDelete": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Delete Hook DELETE `/api/v1/hooks/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `id` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (Shell) curl -X DELETE "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; // Request Body (payload) const data = null; axios.delete("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.delete(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php delete("https://api.maiagent.ai/api/v1/hooks/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body | Status Code | Description | | ----------- | ---------------- | | 204 | No response body | *** ### List Hooks Attached to an AI Assistant GET `/api/v1/chatbots/{chatbotId}/hooks/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `chatbotId` | ✅ | string | | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (Shell) curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "results": [ { "id": string (uuid) "name": string "scope": string "templateName": string "templateTypeLabel": string "triggerPoint": string "action": string "enabled": boolean "order": integer } ] } ``` **Example Response Values** ```json { "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "scope": "Response string", "templateName": "Response string", "templateTypeLabel": "Response string", "triggerPoint": "Response string", "action": "Response string", "enabled": false, "order": 456 } ] } ``` *** ### Replace All Hooks Attached to an AI Assistant PUT `/api/v1/chatbots/{chatbotId}/hooks/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ----------- | | `chatbotId` | ✅ | string | | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ------- | -------------- | -------- | ----------- | | hookIds | array\[string] | Yes | | **Example Request Schema** ```typescript { "hookIds": [ string (uuid) ] } ``` **Example Request Values** ```json { "hookIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (Shell) curl -X PUT "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "hookIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (payload) const data = { "hookIds": [ "550e8400-e29b-41d4-a716-446655440000" ] }; axios.put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request Body (payload) data = { "hookIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } response = requests.put(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/hooks/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'hookIds' => [ '550e8400-e29b-41d4-a716-446655440000' ] ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "results": [ { "id": string (uuid) "name": string "scope": string "templateName": string "templateTypeLabel": string "triggerPoint": string "action": string "enabled": boolean "order": integer } ] } ``` **Example Response Values** ```json { "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "scope": "Response string", "templateName": "Response string", "templateTypeLabel": "Response string", "triggerPoint": "Response string", "action": "Response string", "enabled": false, "order": 456 } ] } ``` *** ### List Schedules GET `/api/v1/schedules/` {% hint style="info" %} A schedule runs an instruction through an AI assistant at the specified time; the system automatically provisions a dedicated contact and conversation when the schedule is created. {% endhint %} #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------- | ---------------------------------------------- | | `page` | ❌ | integer | A page number within the paginated result set. | | `pageSize` | ❌ | integer | Number of results to return per page. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/schedules/?page=1&pageSize=1", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "count": integer "next"?: string (uri) // Optional "previous"?: string (uri) // Optional "results": [ { "id": string (uuid) "name": string "prompt": string "chatbot": string (uuid) "chatbotName": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "saveResultToContext"?: boolean // Optional "enabled"?: boolean // Optional "lastExecutedAt"?: string (timestamp) // Optional "executionCount"?: integer // Optional "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) "countsTowardLimit": boolean "createdAt": string (timestamp) } ] } ``` **Example Response Values** ```json { "count": 123, "next": "http://api.example.org/accounts/?page=4", "previous": "http://api.example.org/accounts/?page=2", "results": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "prompt": "Response string", "chatbot": "550e8400-e29b-41d4-a716-446655440000", "chatbotName": "Response string", "executionMode": "in_context", "scheduleType": "cron", "cronExpression": "Response string", "intervalSeconds": 456, "oneShotAt": "Response string", "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "saveResultToContext": false, "enabled": false, "lastExecutedAt": "Response string", "executionCount": 456, "maxExecutions": 456, "endDate": "Response string", "countsTowardLimit": false, "createdAt": "Response string" } ] } ``` *** ### Create Schedule POST `/api/v1/schedules/` #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | chatbot | string (uuid) | Yes | | | name | string | Yes | | | executionMode | string (enum: in\_context, isolated) | Yes | `in_context`: In Context ; `isolated`: Isolated; | | prompt | string | Yes | | | contextVariables | object | No | | | inbox | string (uuid) | Yes | | | saveResultToContext | boolean | No | | | deliveryConversationIds | array\[string] | No | | | deliveryWebhookUrls | array\[string] | No | | | scheduleType | string (enum: cron, interval, one\_shot) | Yes | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot; | | cronExpression | string | No | | | intervalSeconds | integer | No | | | oneShotAt | string (timestamp) | No | | | timezone | string | No | | | enabled | boolean | No | | | maxExecutions | integer | No | | | endDate | string (date) | No | Last day the schedule runs, in its own timezone; the first run due after that day turns it off. | **Example Request Schema** ```typescript { "chatbot": string (uuid) "name": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "enabled"?: boolean // Optional "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) } ``` **Example Request Values** ```json { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X POST "https://api.maiagent.ai/api/v1/schedules/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (payload) const data = { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }; axios.post("https://api.maiagent.ai/api/v1/schedules/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request Body (payload) data = { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": None, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": True, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": True, "maxExecutions": 123, "endDate": "Example string" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/schedules/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'chatbot' => '550e8400-e29b-41d4-a716-446655440000', 'name' => 'Example name', 'executionMode' => 'in_context', 'prompt' => 'Example string', 'contextVariables' => null, 'inbox' => '550e8400-e29b-41d4-a716-446655440000', 'saveResultToContext' => true, 'deliveryConversationIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'deliveryWebhookUrls' => [ 'https://example.com/file.jpg' ], 'scheduleType' => 'cron', 'cronExpression' => 'Example string', 'intervalSeconds' => 123, 'oneShotAt' => 'Example string', 'timezone' => 'Example string', 'enabled' => true, 'maxExecutions' => 123, 'endDate' => 'Example string' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 201** **Example Response Schema** ```typescript { "id": string (uuid) "chatbot": string (uuid) "organization": string (uuid) "name": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "dedicatedContact": string (uuid) "dedicatedConversation": string (uuid) "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "periodicTask": integer "enabled"?: boolean // Optional "lastExecutedAt": string (timestamp) "executionCount": integer "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) "countsTowardLimit": boolean "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "chatbot": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "executionMode": "in_context", "prompt": "Response string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": false, "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000", "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000", "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Response string", "intervalSeconds": 456, "oneShotAt": "Response string", "timezone": "Response string", "periodicTask": 456, "enabled": false, "lastExecutedAt": "Response string", "executionCount": 456, "maxExecutions": 456, "endDate": "Response string", "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Retrieve a Specific Schedule GET `/api/v1/schedules/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------ | | `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API Call Example (Shell) curl -X GET "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; axios.get("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php get("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "chatbot": string (uuid) "organization": string (uuid) "name": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "dedicatedContact": string (uuid) "dedicatedConversation": string (uuid) "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "periodicTask": integer "enabled"?: boolean // Optional "lastExecutedAt": string (timestamp) "executionCount": integer "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) "countsTowardLimit": boolean "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "chatbot": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "executionMode": "in_context", "prompt": "Response string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": false, "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000", "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000", "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Response string", "intervalSeconds": 456, "oneShotAt": "Response string", "timezone": "Response string", "periodicTask": 456, "enabled": false, "lastExecutedAt": "Response string", "executionCount": 456, "maxExecutions": 456, "endDate": "Response string", "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Partially Update Schedule PATCH `/api/v1/schedules/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------ | | `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | name | string | No | | | prompt | string | No | | | contextVariables | object | No | | | saveResultToContext | boolean | No | | | deliveryConversationIds | array\[string] | No | | | deliveryWebhookUrls | array\[string] | No | | | scheduleType | string (enum: cron, interval, one\_shot) | No | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot; | | cronExpression | string | No | | | intervalSeconds | integer | No | | | oneShotAt | string (timestamp) | No | | | timezone | string | No | | | enabled | boolean | No | | | maxExecutions | integer | No | | | endDate | string (date) | No | Last day the schedule runs, in its own timezone; the first run due after that day turns it off. | **Example Request Schema** ```typescript { "name"?: string // Optional "prompt"?: string // Optional "contextVariables"?: object // Optional "saveResultToContext"?: boolean // Optional "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType"?: string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot (Optional) "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "enabled"?: boolean // Optional "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) } ``` **Example Request Values** ```json { "name": "Example name", "prompt": "Example string", "contextVariables": null, "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X PATCH "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Example name", "prompt": "Example string", "contextVariables": null, "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request body (payload) const data = { "name": "Example name", "prompt": "Example string", "contextVariables": null, "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }; axios.patch("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request body (payload) data = { "name": "Example name", "prompt": "Example string", "contextVariables": None, "saveResultToContext": True, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": True, "maxExecutions": 123, "endDate": "Example string" } response = requests.patch(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php patch("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'name' => 'Example name', 'prompt' => 'Example string', 'contextVariables' => null, 'saveResultToContext' => true, 'deliveryConversationIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'deliveryWebhookUrls' => [ 'https://example.com/file.jpg' ], 'scheduleType' => 'cron', 'cronExpression' => 'Example string', 'intervalSeconds' => 123, 'oneShotAt' => 'Example string', 'timezone' => 'Example string', 'enabled' => true, 'maxExecutions' => 123, 'endDate' => 'Example string' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status code: 200** **Example Response Schema** ```typescript { "id": string (uuid) "chatbot": string (uuid) "organization": string (uuid) "name": string "executionMode": { } "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "dedicatedContact": string (uuid) "dedicatedConversation": string (uuid) "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "periodicTask": integer "enabled"?: boolean // Optional "lastExecutedAt": string (timestamp) "executionCount": integer "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) "countsTowardLimit": boolean "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "chatbot": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "executionMode": {}, "prompt": "Response string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": false, "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000", "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000", "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Response string", "intervalSeconds": 456, "oneShotAt": "Response string", "timezone": "Response string", "periodicTask": 456, "enabled": false, "lastExecutedAt": "Response string", "executionCount": 456, "maxExecutions": 456, "endDate": "Response string", "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Delete a Schedule DELETE `/api/v1/schedules/{id}/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------ | | `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (Shell) curl -X DELETE "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; // Request Body (payload) const data = null; axios.delete("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.delete(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php delete("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body | Status Code | Description | | ----------- | ---------------- | | 204 | No response body | *** ### Run Schedule Now POST `/api/v1/schedules/{id}/run-now/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------ | | `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. | #### Request Body **Request Parameters** | Field | Type | Required | Description | | ----------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- | | chatbot | string (uuid) | Yes | | | name | string | Yes | | | executionMode | string (enum: in\_context, isolated) | Yes | `in_context`: In Context ; `isolated`: Isolated; | | prompt | string | Yes | | | contextVariables | object | No | | | inbox | string (uuid) | Yes | | | saveResultToContext | boolean | No | | | deliveryConversationIds | array\[string] | No | | | deliveryWebhookUrls | array\[string] | No | | | scheduleType | string (enum: cron, interval, one\_shot) | Yes | `cron`: Cron ; `interval`: Interval ; `one_shot`: One Shot; | | cronExpression | string | No | | | intervalSeconds | integer | No | | | oneShotAt | string (timestamp) | No | | | timezone | string | No | | | enabled | boolean | No | | | maxExecutions | integer | No | | | endDate | string (date) | No | Last day the schedule runs, in its own timezone; the first run due after that day turns it off. | **Request Schema Example** ```typescript { "chatbot": string (uuid) "name": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "enabled"?: boolean // Optional "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) } ``` **Example Request Values** ```json { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (Shell) curl -X POST "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/" \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }' # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' } }; // Request Body (payload) const data = { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": true, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": true, "maxExecutions": 123, "endDate": "Example string" }; axios.post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/" headers = { "Authorization": "Api-Key YOUR_API_KEY", "Content-Type": "application/json" } # Request Body (payload) data = { "chatbot": "550e8400-e29b-41d4-a716-446655440000", "name": "Example name", "executionMode": "in_context", "prompt": "Example string", "contextVariables": None, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": True, "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Example string", "intervalSeconds": 123, "oneShotAt": "Example string", "timezone": "Example string", "enabled": True, "maxExecutions": 123, "endDate": "Example string" } response = requests.post(url, json=data, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/run-now/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY', 'Content-Type' => 'application/json' ], 'json' => [ 'chatbot' => '550e8400-e29b-41d4-a716-446655440000', 'name' => 'Example name', 'executionMode' => 'in_context', 'prompt' => 'Example string', 'contextVariables' => null, 'inbox' => '550e8400-e29b-41d4-a716-446655440000', 'saveResultToContext' => true, 'deliveryConversationIds' => [ '550e8400-e29b-41d4-a716-446655440000' ], 'deliveryWebhookUrls' => [ 'https://example.com/file.jpg' ], 'scheduleType' => 'cron', 'cronExpression' => 'Example string', 'intervalSeconds' => 123, 'oneShotAt' => 'Example string', 'timezone' => 'Example string', 'enabled' => true, 'maxExecutions' => 123, 'endDate' => 'Example string' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 202** **Response Schema Example** ```typescript { "status"?: string // Optional } ``` **Example Response Values** ```json { "status": "scheduled" } ``` *** ### Enable or Disable Schedule POST `/api/v1/schedules/{id}/toggle/` #### Parameters | Parameter Name | Required | Type | Description | | -------------- | -------- | ------ | ------------------------------------------------ | | `id` | ✅ | string | A UUID string identifying this Chatbot Schedule. | #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (Shell) curl -X POST "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/" \ -H "Authorization: Api-Key YOUR_API_KEY" # Replace YOUR_API_KEY and verify the request data before running. ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const axios = require('axios'); // Set request headers const config = { headers: { 'Authorization': 'Api-Key YOUR_API_KEY' } }; // Request Body (payload) const data = null; axios.post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/", data, config) .then(response => { console.log('Response received successfully:'); console.log(response.data); }) .catch(error => { console.error('Request error:'); console.error(error.response?.data || error.message); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/" headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.post(url, headers=headers) try: print("Response received successfully:") print(response.json()) except Exception as e: print("Request error:", e) ``` {% endtab %} {% tab title="PHP" %} ```php post("https://api.maiagent.ai/api/v1/schedules/550e8400-e29b-41d4-a716-446655440000/toggle/", [ 'headers' => [ 'Authorization' => 'Api-Key YOUR_API_KEY' ] ]); $data = json_decode($response->getBody(), true); echo "Response received successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Body **Status Code: 200** **Response Schema Example** ```typescript { "id": string (uuid) "chatbot": string (uuid) "organization": string (uuid) "name": string "executionMode": string (enum: in_context, isolated) // * `in_context` - In Context * `isolated` - Isolated "prompt": string "contextVariables"?: object // Optional "inbox": string (uuid) "saveResultToContext"?: boolean // Optional "dedicatedContact": string (uuid) "dedicatedConversation": string (uuid) "deliveryConversationIds"?: [ // Optional string (uuid) ] "deliveryWebhookUrls"?: [ // Optional string (uri) ] "scheduleType": string (enum: cron, interval, one_shot) // * `cron` - Cron * `interval` - Interval * `one_shot` - One Shot "cronExpression"?: string // Optional "intervalSeconds"?: integer // Optional "oneShotAt"?: string (timestamp) // Optional "timezone"?: string // Optional "periodicTask": integer "enabled"?: boolean // Optional "lastExecutedAt": string (timestamp) "executionCount": integer "maxExecutions"?: integer // Optional "endDate"?: string (date) // Last day the schedule runs, in its own timezone; the first run due after that day turns it off. (Optional) "countsTowardLimit": boolean "createdAt": string (timestamp) "updatedAt": string (timestamp) } ``` **Example Response Values** ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "chatbot": "550e8400-e29b-41d4-a716-446655440000", "organization": "550e8400-e29b-41d4-a716-446655440000", "name": "Response string", "executionMode": "in_context", "prompt": "Response string", "contextVariables": null, "inbox": "550e8400-e29b-41d4-a716-446655440000", "saveResultToContext": false, "dedicatedContact": "550e8400-e29b-41d4-a716-446655440000", "dedicatedConversation": "550e8400-e29b-41d4-a716-446655440000", "deliveryConversationIds": [ "550e8400-e29b-41d4-a716-446655440000" ], "deliveryWebhookUrls": [ "https://example.com/file.jpg" ], "scheduleType": "cron", "cronExpression": "Response string", "intervalSeconds": 456, "oneShotAt": "Response string", "timezone": "Response string", "periodicTask": 456, "enabled": false, "lastExecutedAt": "Response string", "executionCount": 456, "maxExecutions": 456, "endDate": "Response string", "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` **Status Code: 400** **Response Schema Example** ```typescript { "detail"?: string // Optional } ``` **Example Response Values** ```json { "detail": "Response string" } ``` *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/api/en/api-reference/ai-zhu-li.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.