> 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 created by the organization) | | embeddingModel | string (uuid) | No | Embedding model used to vectorize text; optional | | rerankerModel | string (uuid) | No | Model used for reranking; optional | | 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 Text-to-SQL) | | organization | string (uuid) | No | Organization the chatbot belongs to; if empty, it 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 structure 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; default: 12, minimum: 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 only as the lowest-priority fallback when the caller does not provide query\_metadata. | | useFullRetrievalRange | boolean | No | When enabled, ignores LLM top\_k truncation and returns the complete 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 | Enables dynamic tool searching, allowing the agent to discover and load tools dynamically through tool\_searching\_tool | | 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 returned per retrieval (similarity\_top\_k for vector retrieval); default: 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. "largeLanguageModel": string (uuid) // Large language model used by the chatbot to generate responses (including custom AI Gateway models created by the organization) "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) } ] "databases"?: [ // List of SQL databases the chatbot can access (for Text-to-SQL) (Optional) { "id": string (uuid) } ] "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, it 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 structure 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; default: 12, minimum: 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 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 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; 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 // Enables dynamic tool searching, allowing the agent to discover and load tools dynamically through tool_searching_tool (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); 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) "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", "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, "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 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", "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, "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'); // Configure 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", "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, "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", "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, "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', '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, '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: 201** **Response Schema Example** ```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) "llm": // ID, name, and retirement information of the bound model, read directly from the FK; returned even if the model has been disabled by the organization { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; after it passes, a daily job switches the assistant to the replacement and disables this model. null means no retirement is scheduled "replacement": // Model that takes over after retirement (id and name); null means none is specified, and no automatic migration occurs on expiry { "id": string (uuid) "name": 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, it 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 structure 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 to retrieve; default: 12, minimum: 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 only as the lowest-priority fallback when the caller does not provide 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 // Thinking level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool_searching_tool (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 lookup (similarity_top_k of the vector search); 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": "Example string", "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000", "llm": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "retiresAt": "Example string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } }, "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", "instructions": "Example string", "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } ], "databases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } ], "updatedAt": "Example string", "organization": "550e8400-e29b-41d4-a716-446655440000", "replyMode": {}, "template": "Example string", "unanswerableTemplate": "Example string", "totalWordsCount": 456, "outputMode": {}, "rawOutputFormat": null, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "description": "Example string", "displayName": "Example string", "toolType": "Example string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "description": "Example string" } ], "connectors": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example 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": "Example string", "turnHandling": null, "enableVoiceReply": false }, "thinkingConfig": null, "enableToolSearching": false, "maxAgentIterations": 456, "agentTimeoutSeconds": 456, "agentTimeoutMessage": "Example 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": "Example 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" # Make sure to 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 error:'); 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 error:", 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 error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **Status Code: 200** **Example Response Structure** ```typescript [ { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; after it passes, a daily job switches assistants to the replacement and disables this model. null means no retirement is scheduled "replacement": // Model that takes over after retirement (id and name); null means none is specified, so nothing is migrated automatically at expiry { "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 settings 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 (weakest to strongest); default is always null (Optional) "canDisable"?: boolean // Whether this model can turn thinking off; 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 thinks on its own, or the platform default level enables thinking (Optional) "unsetLevel"?: string // Level the platform actually sends when none is set; null means no thinking parameter is sent and the model's own default applies (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. } ] ``` **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" } ] ``` *** ### List AI Assistants GET `/api/v1/chatbots/` #### Parameters | Parameter | Required | Type | Description | | -------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createdByMember` | ❌ | string | Filter by creator: member id in this organization (the id returned by the member roster, including deactivated 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 # Example API Call (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 error:'); 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 error:", 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 error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response **Status code: 200** **Response Schema Example** ```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 serializer for the LLM: identifier fields plus retirement information, so the frontend can warn when a model is about to be retired. { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; after it passes, a daily job switches the assistant to the replacement and disables this model. null means no retirement is scheduled "replacement": // Model that takes over after retirement (id and name); null means unspecified, and no automatic migration happens at expiry { "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 // Enables dynamic tool search, letting the agent discover and load tools via tool_searching_tool. (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) "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": "Example string", "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } ], "largeLanguageModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "retiresAt": "Example string", "replacement": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } }, "embeddingModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "isDefault": false, "isMultimodal": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "image": "https://example.com/file.jpg" } }, "rerankerModel": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "isDefault": false, "icon": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "image": "https://example.com/file.jpg" } }, "knowledgeBases": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } ], "tools": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "description": "Example string", "displayName": "Example string", "toolType": "Example string" } ], "skills": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string", "description": "Example string" } ], "agentMode": {}, "replyMode": {}, "updatedAt": "Example string", "enableEvaluation": false, "enableInlineCitations": false, "enableToolSearching": false, "enableCodeInterpreter": false, "enableBrowserTool": false, "enableImageSearch": false, "numberOfRetrievedChunks": 456, "useFullRetrievalRange": false, "isMultimodalLlm": false, "voiceConfig": { "enabled": false }, "createdBy": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" }, "isLocked": false, "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000", "canUpdate": false, "canDelete": false, "team": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Example string" } } ] } ``` *** ### Retrieve a Specific AI Assistant GET `/api/v1/chatbots/{id}/` #### Parameters | Parameter | Required | Type | Description | | --------- | -------- | ------ | ----------- | | `id` | ✅ | 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/" \ -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 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.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/", [ '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 **Status code: 200** **Response Schema Example** ```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-owned AI Gateway models) "llm": // The bound model's id, name, and retirement information, read directly from the FK; returned even if the model has been disabled by the organization { "id": string (uuid) "name": string "retiresAt": string (date) // Provider retirement date; after it passes, a daily job switches the assistant to the replacement and disables this model. null means no retirement is scheduled "replacement": // Model that takes over after retirement (id and name); null means unspecified, and no automatic migration happens at expiry { "id": string (uuid) "name": 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 (used by the Text-to-SQL feature) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, it is a personal chatbot (Optional) "replyMode"?: // Reply mode: normal reply or streaming reply * `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 to retrieve; default: 12, minimum: 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 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 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; 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 // Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool_searching_tool (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 lookup (similarity_top_k of the vector search); 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. } ``` **Response Example** ```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" } }, "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, "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 | 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 | Large language model used by the chatbot to generate answers (including organization-built AI Gateway models) | | embeddingModel | string (uuid) | No | Embedding model used to vectorize text; optional | | rerankerModel | string (uuid) | No | Model used for reranking; optional | | 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 Text-to-SQL) | | organization | string (uuid) | No | Organization the chatbot belongs to; if empty, it 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 structure 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; default: 12, minimum: 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 only as the lowest-priority fallback when the caller does not provide query\_metadata. | | useFullRetrievalRange | boolean | No | When enabled, ignores LLM top\_k truncation and returns the complete 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 | Thinking level: null (model default) or {"reasoning\_effort": "off | | enableToolSearching | boolean | No | Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool\_searching\_tool | | 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 retrieved per long-term memory lookup (similarity\_top\_k of the vector search); default: 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) // Large language model used by the chatbot to generate answers (including organization-built AI Gateway models) "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) } ] "databases"?: [ // List of SQL databases the chatbot can access (for Text-to-SQL) (Optional) { "id": string (uuid) } ] "organization"?: string (uuid) // Organization the chatbot belongs to; if empty, it 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 structure 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; default: 12, minimum: 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 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 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; 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 // Enables dynamic tool search, allowing the agent to discover and load tools dynamically via tool_searching_tool (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); 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) "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", "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, "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", "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, "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" }' # Make sure to 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", "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, "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", "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, "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', '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, '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 retrieved successfully:\n"; print_r($data); } catch (Exception $e) { echo 'Request error: ' . $e->getMessage(); } ?> ``` {% endtab %} {% endtabs %} #### Response Content **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) // The large language model the chatbot uses to generate answers (including organization-built AI Gateway models) "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; after it passes, a daily job switches the assistant to the replacement and disables this model. null means no retirement is scheduled "replacement": // The model that takes over after retirement (id and name); null means none is specified, and no automatic migration happens at expiry { "id": string (uuid) "name": string } } "embeddingModel"?: string (uuid) // The embedding model used to vectorize text; optional (optional) "rerankerModel"?: string (uuid) // The 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 (used by the Text-to-SQL feature) (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 reply or streaming reply * `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 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 to retrieve; defaults to 12, minimum 1 (optional) "defaultLabelRelations"?: object // Assistant-level default knowledge base label filter, in the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller does not pass 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 // Thinking level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (optional) "enableToolSearching"?: boolean // Enables dynamic tool searching, allowing the agent to discover and load tools dynamically through tool_searching_tool (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 lookup (similarity_top_k of the vector search); 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. } ``` **Response Example 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" } }, "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, "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 Content **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 organization-created AI Gateway models) | | embeddingModel | string (uuid) | No | Embedding model used to vectorize text; optional | | rerankerModel | string (uuid) | No | Model used for reranking; optional | | 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, tables, or a 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 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; default: 12, minimum: 1 | | defaultLabelRelations | object | No | Assistant-level default 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 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 effort: null (model default) or {"reasoning\_effort": "off | | enableToolSearching | boolean | No | Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool\_searching\_tool | | 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 retrieved per long-term memory search (similarity\_top\_k for vector retrieval); default: 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 organization-created AI Gateway models) (Optional) "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) } ] "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, tables, or a 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) } ] "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; default: 12, minimum: 1 (Optional) "defaultLabelRelations"?: object // Assistant-level default 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 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 effort: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool_searching_tool (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 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) "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", "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, "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", "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, "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", "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, "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", "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, "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', '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, '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 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 the chatbot uses to generate responses (including custom AI Gateway models created by the organization) "llm": // The associated 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 task switches the assistant to 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 the retirement date { "id": string (uuid) "name": string } } "embeddingModel"?: string (uuid) // The embedding model used to vectorize text; optional (optional) "rerankerModel"?: string (uuid) // The 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) // The 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, tables, or a 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 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 // Thinking level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional) "enableToolSearching"?: boolean // Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool_searching_tool (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 search (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) "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" } }, "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, "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 an 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'); // Configure 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 custom AI Gateway models created by the organization) "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) // The provider's retirement date; once reached, the daily scheduled task 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 no replacement is specified and no automatic migration occurs on the retirement date { "id": string (uuid) "name": string } } "embeddingModel"?: string (uuid) // The embedding model used to vectorize text; optional (Optional) "rerankerModel"?: string (uuid) // The 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 the Text-to-SQL feature) (Optional) { "id": string (uuid) "name": string } ] "updatedAt": string (timestamp) "organization"?: string (uuid) // The 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, tables, or a custom format * `text` - Text * `json_schema` - JSON Schema (Optional) { } "rawOutputFormat"?: object // JSON structure 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 references retrieved; defaults to 12, with a minimum of 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 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 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 // Enables dynamic tool search, allowing the agent to discover and load tools dynamically through tool_searching_tool (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); 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) "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" } }, "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, "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 a prompt with 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 # Example API Call (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 "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, "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 | | **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 } ``` **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 } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # Example API Call (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 }' # 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 }; 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 } 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 ] ]); $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 "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, "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 "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, "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` *** ### Partially Update a 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 | | **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 } ``` **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 } ``` #### 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 }' # 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 }; 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 } 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 ] ]); $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 "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, "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 a Schedule Immediately 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 | | **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 } ``` **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 } ``` #### Code Examples {% tabs %} {% tab title="Shell/Bash" %} ```bash # API call example (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 }' # 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 }; 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 } 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 ] ]); $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** **Example Response Schema** ```typescript { "status"?: string // Optional } ``` **Example Response Values** ```json { "status": "scheduled" } ``` *** ### Enable or Disable a 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 # API call example (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** **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 "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, "countsTowardLimit": false, "createdAt": "Response string", "updatedAt": "Response string" } ``` **Status code: 400** **Example Response Schema** ```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.