{ "openapi": "3.0.0", "paths": { "/ai-agents/agents": { "post": { "operationId": "AgentsController_createAgent", "parameters": [ { "name": "chatApiVersion", "required": false, "in": "header", "description": "Chat API version. Defaults to `v3.0`.", "schema": { "type": "string", "default": "v3.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentDTO" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the agent" }, "appId": { "type": "string", "description": "Application ID" }, "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "description": "URL to the agent's avatar" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "description": "Integration platform identifier" }, "integrationType": { "type": "string", "description": "Type of connection" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of connected tools" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of connected actions" }, "integrationMeta": { "type": "object", "description": "Integration-specific configuration", "properties": { "baseUrl": { "type": "string" }, "agentId": { "type": "string" } } }, "metaData": { "type": "object", "description": "Agent metadata", "properties": { "greetingMessage": { "type": "string" }, "introductoryMessage": { "type": "string" }, "suggestedMessages": { "type": "array", "items": { "type": "string" } } } }, "_id": { "type": "string", "description": "Internal document ID" }, "createdAt": { "type": "integer", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "integer", "format": "date-time", "description": "Last update timestamp" } } } } }, "example": { "agent": { "uid": "550e8400-e29b-41d4-a716-446655440000", "appId": "my-app-id", "name": "My Agent", "icon": "https://example.com/icon.png", "isActive": true, "integrateWith": "openai", "integrationType": "agent", "tools": [ "tool1" ], "actions": [ "action1" ], "instruction": "You are a helpful assistant", "integrationMeta": {}, "metaData": {}, "deletedAt": null, "createdAt": "2025-12-01T00:00:00.000Z", "updatedAt": "2025-12-01T00:00:00.000Z" } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agents" ], "description": "Creates a new BYO Agent that delegates conversations to an external AI Agent. Use this endpoint to register a BYO (Bring Your Own) agent powered by frameworks like Mastra, CrewAI, or LangGraph.\n\n**Validation:** All referenced tools and actions are validated before the agent is created.", "summary": "Create BYO Agent" }, "get": { "operationId": "AgentsController_getAgents", "parameters": [], "responses": { "200": { "description": "List of agents", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GetAgentDetailDto" } }, "example": [ { "uid": "550e8400-e29b-41d4-a716-446655440000", "appId": "my-app-id", "name": "My Agent", "icon": "https://example.com/icon.png", "isActive": true, "integrateWith": "openai", "integrationType": "agent", "tools": [ "tool1" ], "actions": [ "action1" ], "instruction": "You are a helpful assistant", "integrationMeta": {}, "metaData": {}, "deletedAt": null, "createdAt": "2025-12-01T00:00:00.000Z", "updatedAt": "2025-12-01T00:00:00.000Z" } ] } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agents" ], "summary": "List BYO Agents", "description": "Retrieves all BYO Agents configured for your CometChat app. Use this endpoint to view all registered BYO (Bring Your Own) agents and their current configuration." } }, "/ai-agents/tools": { "post": { "operationId": "ToolsController_createTool", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDto" } } } }, "responses": { "201": { "description": "Tool created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_myTool" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "myTool" }, "type": { "type": "string", "enum": [ "action", "tool" ], "example": "action" }, "displayName": { "type": "string", "example": "My Tool" }, "executionText": { "type": "string", "example": "Running my tool..." }, "doNotExecute": { "type": "boolean", "example": false }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "myTool" }, "description": { "type": "string", "example": "A helpful tool" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "integer", "format": "date-time" }, "updatedAt": { "type": "integer", "format": "date-time" } } }, "example": { "_id": "myapp_myTool", "appId": "my-app-id", "name": "myTool", "type": "action", "displayName": "My Tool", "executionText": "Running my tool...", "doNotExecute": false, "tool": { "name": "myTool", "description": "A helpful tool", "parameters": { "type": "object", "properties": {}, "required": [] } }, "createdAt": "2025-12-01T00:00:00.000Z", "updatedAt": "2025-12-01T00:00:00.000Z" } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Tools" ], "description": "Defines custom tools that agents can invoke during conversations.\n\n**Naming:** The tool name must be unique per application.\n\n**Type:** When `doNotExecute` is `true`, the type is set to `tool`. Otherwise, it is set to `action`.", "summary": "Create Tool" }, "get": { "operationId": "ToolsController_getAllTools", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "Filter tools by type", "schema": { "enum": [ "action", "tool" ], "type": "string" } } ], "responses": { "200": { "description": "List of tools", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_myTool" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "myTool" }, "type": { "type": "string", "enum": [ "action", "tool" ], "example": "action" }, "displayName": { "type": "string", "example": "My Tool" }, "executionText": { "type": "string", "example": "Running my tool..." }, "doNotExecute": { "type": "boolean", "example": false }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "myTool" }, "description": { "type": "string", "example": "A helpful tool" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "integer", "format": "date-time" }, "updatedAt": { "type": "integer", "format": "date-time" } } } }, "example": [ { "_id": "myapp_myTool", "appId": "my-app-id", "name": "myTool", "type": "action", "displayName": "My Tool", "executionText": "Running my tool...", "doNotExecute": false, "tool": { "name": "myTool", "description": "A helpful tool", "parameters": { "type": "object", "properties": {}, "required": [] } }, "createdAt": "2025-12-01T00:00:00.000Z", "updatedAt": "2025-12-01T00:00:00.000Z" } ] } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Tools" ], "description": "Retrieves all tools configured for your CometChat app. Use this endpoint to view available tools and actions, or filter by type.\n\n**Filtering:** Use the `type` query parameter to filter by `action` or `tool`.", "summary": "List Tools" } }, "/ai-agents/tools/{name}": { "get": { "operationId": "ToolsController_getToolByName", "parameters": [ { "name": "name", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool details", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_myTool" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "myTool" }, "type": { "type": "string", "enum": [ "action", "tool" ], "example": "action" }, "displayName": { "type": "string", "example": "My Tool" }, "executionText": { "type": "string", "example": "Running my tool..." }, "doNotExecute": { "type": "boolean", "example": false }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "myTool" }, "description": { "type": "string", "example": "A helpful tool" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "integer", "format": "date-time" }, "updatedAt": { "type": "integer", "format": "date-time" } } }, "example": { "_id": "myapp_myTool", "appId": "my-app-id", "name": "myTool", "type": "action", "displayName": "My Tool", "executionText": "Running my tool...", "doNotExecute": false, "tool": { "name": "myTool", "description": "A helpful tool", "parameters": { "type": "object", "properties": {}, "required": [] } }, "createdAt": "2025-12-01T00:00:00.000Z", "updatedAt": "2025-12-01T00:00:00.000Z" } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Tools" ], "description": "Retrieves a specific tool by its unique name. Use this endpoint to inspect a tool's configuration, parameters, and description.", "summary": "Get Tool" }, "put": { "operationId": "ToolsController_updateTool", "parameters": [ { "name": "name", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDto" } } } }, "responses": { "200": { "description": "Tool updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_myTool" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "myTool" }, "type": { "type": "string", "enum": [ "action", "tool" ], "example": "action" }, "displayName": { "type": "string", "example": "My Tool" }, "executionText": { "type": "string", "example": "Running my tool..." }, "doNotExecute": { "type": "boolean", "example": false }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "myTool" }, "description": { "type": "string", "example": "A helpful tool" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "integer", "format": "date-time" }, "updatedAt": { "type": "integer", "format": "date-time" } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Tools" ], "description": "Updates an existing tool by its unique name. Use this endpoint to modify a tool's description, parameters, or behavior.\n\n**Restrictions:** The tool name cannot be changed after creation. The provided tool configuration (name, description, parameters) is merged with the existing values.", "summary": "Update Tool" }, "delete": { "operationId": "ToolsController_deleteTool", "parameters": [ { "name": "name", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tool deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" }, "example": { "deleted": true } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Tools" ], "description": "Deletes a tool by its unique name.", "summary": "Delete Tool" } }, "/ai-agents/agent-builder/agents/available-models": { "get": { "operationId": "AgentBuilderController_getAvailableModels", "parameters": [], "responses": { "200": { "description": "List of available AI models", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string", "example": "gpt-4o-mini" }, "provider": { "type": "string", "example": "openai" }, "settings": { "type": "object", "example": {} }, "default": { "type": "boolean", "example": false } } } }, "example": [ { "model": "gpt-4o-mini", "provider": "openai", "settings": {}, "default": false }, { "model": "gpt-4o", "provider": "openai", "settings": {}, "default": true }, { "model": "claude-sonnet-4-20250514", "provider": "anthropic", "settings": {}, "default": false } ] } } } }, "security": [ { "apiKey": [] } ], "summary": "List Available Models", "tags": [ "Agent Builder" ], "description": "Retrieves the list of AI models available for agents. Use this endpoint to discover supported models before creating or updating an agent.\n\n**Model details:** Each model includes its provider, configuration settings, and whether it is the default. The default model is used when no model is explicitly specified during agent creation." } }, "/ai-agents/agent-builder/agents/variables/all": { "get": { "operationId": "AgentBuilderController_getAvailableVariables", "parameters": [ { "name": "groupByCategory", "required": false, "in": "query", "description": "Group variables by category", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of variables (flat array or grouped by category)", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "sourceType": { "type": "string" }, "category": { "type": "string" }, "usageCount": { "type": "number" }, "usedByAgents": { "type": "array", "items": { "type": "object" } }, "usedByTools": { "type": "object" } } } }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } }, "example": { "auth": [], "custom": [] } } ] }, "example": [ { "name": "auth.uid", "description": "Authenticated user UID", "sourceType": "auth", "category": "auth", "usageCount": 2, "usedByAgents": [ { "uid": "agent-1", "name": "Support Agent" } ], "usedByTools": {} } ] } } } }, "security": [ { "apiKey": [] } ], "summary": "List All Variables", "tags": [ "Agent Builder" ], "description": "Retrieves all enabled variables (predefined and custom) for the application. Use this endpoint to view variable definitions and understand where they are used.\n\n**Usage tracking:** Each variable includes information showing which agents reference it in their instructions and which API tools use it.\n\n**Grouping:** Set `groupByCategory` to `true` to group results by category (e.g., auth, custom); otherwise results are returned as a flat array." } }, "/ai-agents/agent-builder/agents": { "post": { "operationId": "AgentBuilderController_create", "parameters": [ { "name": "chatApiVersion", "required": false, "in": "header", "description": "Chat API version. Defaults to `v3.0`.", "schema": { "type": "string", "default": "v3.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCometChatAgentDto" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "agent": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Create Agent", "tags": [ "Agent Builder" ], "description": "Creates a new agent with optional tools, API tools, MCP servers, and frontend actions. Use this endpoint to set up a fully configured agent in a single request.\n\n**Validation:** All referenced tools, API tools, and MCP servers are validated before creation." }, "get": { "operationId": "AgentBuilderController_findAll", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" }, "description": "Maximum number of results to return per page." }, { "name": "affix", "required": false, "in": "query", "schema": { "enum": [ "prepend", "append" ], "type": "string" }, "description": "To paginate over results, use the value of affix as prepend or append." }, { "name": "createdAt", "required": false, "in": "query", "schema": { "type": "number" }, "description": "To be used with affix for pagination." }, { "name": "search", "required": false, "in": "query", "description": "Search term to filter agents by name, description, or other fields", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } }, "meta": { "type": "object", "properties": { "previous": { "type": "object", "example": { "affix": "prepend", "createdAt": 1700000000000 } }, "current": { "type": "object", "properties": { "limit": { "type": "number" }, "count": { "type": "number" } } }, "next": { "type": "object", "example": { "affix": "append", "createdAt": 1700000000000 } } } } } }, "example": { "data": [ { "uid": "agent-uuid-1234", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } ], "meta": { "previous": { "affix": "prepend", "createdAt": 1700000000000 }, "current": { "limit": 10, "count": 1 }, "next": { "affix": "append", "createdAt": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "List Agents", "tags": [ "Agent Builder" ], "description": "Retrieves a paginated list of agents for your CometChat app. Use this endpoint to browse, search, and manage your agents.\n\n**Search:** Use the `search` parameter to filter agents by name, description, or UID." } }, "/ai-agents/agent-builder/agents/variables/custom": { "get": { "operationId": "AgentBuilderController_getAllCustomVariables", "parameters": [], "responses": { "200": { "description": "List of custom variables", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "user.plan" }, "description": { "type": "string", "example": "The user subscription plan" }, "sourceType": { "type": "string", "enum": [ "message_metadata", "user_metadata", "constant" ], "example": "user_metadata" }, "sourcePath": { "type": "string", "example": "metadata.plan" }, "constantValue": { "type": "string", "example": "premium" }, "defaultValue": { "type": "string", "example": "free" }, "category": { "type": "string", "enum": [ "custom" ], "example": "custom" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } }, "example": [ { "_id": "507f1f77bcf86cd799439011", "appId": "my-app-id", "name": "user.plan", "description": "The user subscription plan", "sourceType": "user_metadata", "sourcePath": "metadata.plan", "constantValue": "", "defaultValue": "free", "category": "custom", "createdAt": 1700000000000, "updatedAt": 1700000000000 } ] } } } }, "security": [ { "apiKey": [] } ], "summary": "List Custom Variables", "tags": [ "Agent Builder" ], "description": "Retrieves all custom variables defined for the application. Use this endpoint to view and manage dynamic variables used in agent instructions.\n\n**Variable types:** Custom variables can source values from message metadata, user metadata, or constant values. Each variable includes its source type, resolution path, and default value." }, "post": { "operationId": "AgentBuilderController_createCustomVariable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomVariableDto" } } } }, "responses": { "200": { "description": "Custom variable created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "user.plan" }, "description": { "type": "string", "example": "The user subscription plan" }, "sourceType": { "type": "string", "example": "user_metadata" }, "sourcePath": { "type": "string", "example": "metadata.plan" }, "constantValue": { "type": "string", "example": "premium" }, "defaultValue": { "type": "string", "example": "free" }, "category": { "type": "string", "example": "custom" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } }, "example": { "_id": "507f1f77bcf86cd799439011", "appId": "my-app-id", "name": "user.plan", "description": "The user subscription plan", "sourceType": "user_metadata", "sourcePath": "metadata.plan", "constantValue": "", "defaultValue": "free", "category": "custom", "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } }, "security": [ { "apiKey": [] } ], "summary": "Create Custom Variable", "tags": [ "Agent Builder" ], "description": "Creates a new custom variable for the application. Use this endpoint to define dynamic values that can be injected into agent instructions.\n\n**Source types:** Variables can source values from message metadata, user metadata, or a constant value.\n\n**Naming:** Variable names must be unique within the app and follow the pattern `[a-zA-Z][a-zA-Z0-9_.]*`." } }, "/ai-agents/agent-builder/agents/variables/custom/{variableId}": { "patch": { "operationId": "AgentBuilderController_updateCustomVariable", "parameters": [ { "name": "variableId", "required": true, "in": "path", "description": "Variable ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomVariableDto" } } } }, "responses": { "200": { "description": "Custom variable updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "user.plan" }, "description": { "type": "string", "example": "The user subscription plan" }, "sourceType": { "type": "string", "enum": [ "message_metadata", "user_metadata", "constant" ], "example": "user_metadata" }, "sourcePath": { "type": "string", "example": "metadata.plan" }, "constantValue": { "type": "string", "example": "premium" }, "defaultValue": { "type": "string", "example": "free" }, "category": { "type": "string", "enum": [ "custom" ], "example": "custom" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } }, "example": { "_id": "507f1f77bcf86cd799439011", "appId": "my-app-id", "name": "user.plan", "description": "Updated description", "sourceType": "user_metadata", "sourcePath": "metadata.plan", "constantValue": "", "defaultValue": "premium", "category": "custom", "createdAt": 1700000000000, "updatedAt": 1700000100000 } } } } }, "security": [ { "apiKey": [] } ], "summary": "Update Custom Variable", "tags": [ "Agent Builder" ], "description": "Updates an existing custom variable by its ID. Use this endpoint to modify a variable's source, default value, or other properties.\n\n**Partial updates:** Only the provided fields are updated; omitted fields remain unchanged.\n\n**Restrictions:** The variable name cannot be changed after creation." }, "delete": { "operationId": "AgentBuilderController_deleteCustomVariable", "parameters": [ { "name": "variableId", "required": true, "in": "path", "description": "Variable ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Custom variable deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Variable deleted successfully" } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Custom Variable", "tags": [ "Agent Builder" ], "description": "Deletes a custom variable by its ID.\n\n**Impact:** Any agent instructions referencing this variable will no longer resolve its value." } }, "/ai-agents/agent-builder/api-tools": { "get": { "operationId": "ApiToolsController_getAllApiTools", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" }, "description": "Maximum number of results to return per page." }, { "name": "affix", "required": false, "in": "query", "schema": { "enum": [ "prepend", "append" ], "type": "string" }, "description": "To paginate over results, use the value of affix as prepend or append." }, { "name": "createdAt", "required": false, "in": "query", "schema": { "type": "number" }, "description": "To be used with affix for pagination." } ], "responses": { "200": { "description": "Paginated list of API tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-api-tool" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-api-tool" }, "name": { "type": "string", "example": "My API Tool" }, "description": { "type": "string", "example": "Calls an external API" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "endpoint": { "type": "string", "example": "https://api.example.com/search" }, "method": { "type": "string", "example": "GET" }, "enableBasicAuth": { "type": "boolean", "example": false }, "headers": { "type": "string", "nullable": true, "example": "{\"Content-Type\":\"application/json\"}" }, "bodyTemplate": { "type": "string", "nullable": true, "example": "{\"query\":\"{{query}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "example": false }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "query" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The search query" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "my-api-tool" }, "description": { "type": "string", "example": "Calls an external API" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } }, "meta": { "type": "object", "properties": { "previous": { "type": "object", "example": { "affix": "prepend", "createdAt": 1700000000000 } }, "current": { "type": "object", "example": { "limit": 10, "count": 5 } }, "next": { "type": "object", "example": { "affix": "append", "createdAt": 1700000000000 } } } } } }, "example": { "data": [ { "_id": "myapp_my-api-tool", "appId": "my-app-id", "slug": "my-api-tool", "name": "My API Tool", "description": "Calls an external API", "icon": "https://example.com/icon.png", "endpoint": "https://api.example.com/search", "method": "GET", "enableBasicAuth": false, "headers": "{\"Content-Type\":\"application/json\"}", "bodyTemplate": "{\"query\":\"{{query}}\"}", "allowAdditionalProperties": false, "parameters": [ { "key": "query", "type": "string", "description": "The search query", "required": true } ], "tool": { "name": "my-api-tool", "description": "Calls an external API", "parameters": { "type": "object", "properties": {}, "required": [] } }, "createdAt": 1700000000000, "updatedAt": 1700000000000 } ], "meta": { "previous": { "affix": "prepend", "createdAt": 1700000000000 }, "current": { "limit": 10, "count": 1 }, "next": { "affix": "append", "createdAt": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "List API Tools", "tags": [ "Agent Builder API Tools" ], "description": "Retrieves a paginated list of API tools for the application. Use this endpoint to browse and manage custom API tool configurations." }, "post": { "operationId": "ApiToolsController_createApiTool", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiToolDto" } } } }, "responses": { "201": { "description": "API tool created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-api-tool" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-api-tool" }, "name": { "type": "string", "example": "My API Tool" }, "description": { "type": "string", "example": "Calls an external API" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "endpoint": { "type": "string", "example": "https://api.example.com/search" }, "method": { "type": "string", "example": "GET" }, "enableBasicAuth": { "type": "boolean", "example": false }, "headers": { "type": "string", "nullable": true, "example": "{\"Content-Type\":\"application/json\"}" }, "bodyTemplate": { "type": "string", "nullable": true, "example": "{\"query\":\"{{query}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "example": false }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "query" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The search query" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "my-api-tool" }, "description": { "type": "string", "example": "Calls an external API" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder API Tools" ], "description": "Creates a new API tool configuration for the application. Use this endpoint to define a custom API endpoint that agents can call during conversations.\n\n**Uniqueness:** The slug must be unique per application.", "summary": "Create API Tool" } }, "/ai-agents/agent-builder/api-tools/{slug}": { "get": { "operationId": "ApiToolsController_getApiToolBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API tool details", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-api-tool" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-api-tool" }, "name": { "type": "string", "example": "My API Tool" }, "description": { "type": "string", "example": "Calls an external API" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "endpoint": { "type": "string", "example": "https://api.example.com/search" }, "method": { "type": "string", "example": "GET" }, "enableBasicAuth": { "type": "boolean", "example": false }, "headers": { "type": "string", "nullable": true, "example": "{\"Content-Type\":\"application/json\"}" }, "bodyTemplate": { "type": "string", "nullable": true, "example": "{\"query\":\"{{query}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "example": false }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "query" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The search query" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "my-api-tool" }, "description": { "type": "string", "example": "Calls an external API" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder API Tools" ], "description": "Retrieves a specific API tool by its slug. Use this endpoint to inspect an API tool's configuration, parameters, and connected agents.", "summary": "Get API Tool" }, "patch": { "operationId": "ApiToolsController_updateApiTool", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiToolDto" } } } }, "responses": { "200": { "description": "API tool updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-api-tool" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-api-tool" }, "name": { "type": "string", "example": "My API Tool" }, "description": { "type": "string", "example": "Calls an external API" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "endpoint": { "type": "string", "example": "https://api.example.com/search" }, "method": { "type": "string", "example": "GET" }, "enableBasicAuth": { "type": "boolean", "example": false }, "headers": { "type": "string", "nullable": true, "example": "{\"Content-Type\":\"application/json\"}" }, "bodyTemplate": { "type": "string", "nullable": true, "example": "{\"query\":\"{{query}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "example": false }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "query" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The search query" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "my-api-tool" }, "description": { "type": "string", "example": "Calls an external API" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder API Tools" ], "description": "Updates an existing API tool by its slug. Use this endpoint to modify an API tool's parameters, description, or endpoint configuration.", "summary": "Update API Tool" }, "delete": { "operationId": "ApiToolsController_deleteApiTool", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "API tool deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Operation completed successfully" } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder API Tools" ], "description": "Deletes an API tool by its slug.", "summary": "Delete API Tool" } }, "/ai-agents/agent-builder/mcp-servers": { "post": { "operationId": "McpServersController_createMcpServer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpServerDto" } } } }, "responses": { "201": { "description": "MCP server created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-mcp-server" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-mcp-server" }, "name": { "type": "string", "example": "My MCP Server" }, "description": { "type": "string", "example": "A Model Context Protocol server" }, "url": { "type": "string", "example": "https://mcp.example.com/sse" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } }, "example": { "_id": "myapp_my-mcp-server", "appId": "my-app-id", "slug": "my-mcp-server", "name": "My MCP Server", "description": "A Model Context Protocol server", "url": "https://mcp.example.com/sse", "icon": "https://example.com/icon.png", "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder MCP Servers" ], "description": "Creates a new MCP (Model Context Protocol) server configuration for the application. Use this endpoint to register an MCP server that agents can connect to.\n\n**Uniqueness:** The slug must be unique per application.", "summary": "Create MCP Server" }, "get": { "operationId": "McpServersController_getAllMcpServers", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" }, "description": "Maximum number of results to return per page." }, { "name": "affix", "required": false, "in": "query", "schema": { "enum": [ "prepend", "append" ], "type": "string" }, "description": "To paginate over results, use the value of affix as prepend or append." }, { "name": "createdAt", "required": false, "in": "query", "schema": { "type": "number" }, "description": "To be used with affix for pagination." } ], "responses": { "200": { "description": "Paginated list of MCP servers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-mcp-server" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-mcp-server" }, "name": { "type": "string", "example": "My MCP Server" }, "description": { "type": "string", "example": "A Model Context Protocol server" }, "url": { "type": "string", "example": "https://mcp.example.com/sse" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } }, "meta": { "type": "object", "properties": { "previous": { "type": "object", "example": { "affix": "prepend", "createdAt": 1700000000000 } }, "current": { "type": "object", "example": { "limit": 10, "count": 5 } }, "next": { "type": "object", "example": { "affix": "append", "createdAt": 1700000000000 } } } } } }, "example": { "data": [ { "_id": "myapp_my-mcp-server", "appId": "my-app-id", "slug": "my-mcp-server", "name": "My MCP Server", "description": "A Model Context Protocol server", "url": "https://mcp.example.com/sse", "icon": "https://example.com/icon.png", "createdAt": 1700000000000, "updatedAt": 1700000000000 } ], "meta": { "previous": { "affix": "prepend", "createdAt": 1700000000000 }, "current": { "limit": 10, "count": 1 }, "next": { "affix": "append", "createdAt": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder MCP Servers" ], "description": "Retrieves a paginated list of MCP servers for the application. Use this endpoint to browse and manage MCP server configurations.", "summary": "List MCP Servers" } }, "/ai-agents/agent-builder/mcp-servers/{slug}": { "get": { "operationId": "McpServersController_getMcpServerBySlug", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server details", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-mcp-server" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-mcp-server" }, "name": { "type": "string", "example": "My MCP Server" }, "description": { "type": "string", "example": "A Model Context Protocol server" }, "url": { "type": "string", "example": "https://mcp.example.com/sse" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder MCP Servers" ], "description": "Retrieves a specific MCP server by its slug. Use this endpoint to inspect an MCP server's configuration and connected agents.", "summary": "Get MCP Server" }, "patch": { "operationId": "McpServersController_updateMcpServer", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServerDto" } } } }, "responses": { "200": { "description": "MCP server updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_my-mcp-server" }, "appId": { "type": "string", "example": "my-app-id" }, "slug": { "type": "string", "example": "my-mcp-server" }, "name": { "type": "string", "example": "My MCP Server" }, "description": { "type": "string", "example": "A Model Context Protocol server" }, "url": { "type": "string", "example": "https://mcp.example.com/sse" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder MCP Servers" ], "description": "Updates an existing MCP server by its slug. Use this endpoint to modify an MCP server's configuration or connection details.", "summary": "Update MCP Server" }, "delete": { "operationId": "McpServersController_deleteMcpServer", "parameters": [ { "name": "slug", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "MCP server deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Operation completed successfully" } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agent Builder MCP Servers" ], "description": "Deletes an MCP server by its slug.", "summary": "Delete MCP Server" } }, "/ai-agents/agent-builder/frontend-actions": { "get": { "operationId": "FrontendActionsController_getAllFrontendActions", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" }, "description": "Maximum number of results to return per page." }, { "name": "affix", "required": false, "in": "query", "schema": { "enum": [ "prepend", "append" ], "type": "string" }, "description": "To paginate over results, use the value of affix as prepend or append." }, { "name": "createdAt", "required": false, "in": "query", "schema": { "type": "number" }, "description": "To be used with affix for pagination." } ], "responses": { "200": { "description": "Paginated list of frontend actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_onUserClick" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "User Click Action" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "triggerFunction": { "type": "string", "example": "onUserClick" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "userId" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The user identifier" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "onUserClick" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } }, "meta": { "type": "object", "properties": { "previous": { "type": "object", "example": { "affix": "prepend", "createdAt": 1700000000000 } }, "current": { "type": "object", "example": { "limit": 10, "count": 5 } }, "next": { "type": "object", "example": { "affix": "append", "createdAt": 1700000000000 } } } } } }, "example": { "data": [ { "_id": "myapp_onUserClick", "appId": "my-app-id", "name": "User Click Action", "description": "Triggered when a user clicks a button", "triggerFunction": "onUserClick", "icon": "https://example.com/icon.png", "parameters": [ { "key": "userId", "type": "string", "description": "The user identifier", "required": true } ], "tool": { "name": "onUserClick", "description": "Triggered when a user clicks a button", "parameters": { "type": "object", "properties": {}, "required": [] } }, "createdAt": 1700000000000, "updatedAt": 1700000000000 } ], "meta": { "previous": { "affix": "prepend", "createdAt": 1700000000000 }, "current": { "limit": 10, "count": 1 }, "next": { "affix": "append", "createdAt": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "List Frontend Actions", "tags": [ "Agent Builder Frontend Actions" ], "description": "Retrieves a paginated list of frontend actions for the application. Use this endpoint to browse and manage frontend action configurations." }, "post": { "operationId": "FrontendActionsController_createFrontendAction", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFrontendActionDto" } } } }, "responses": { "201": { "description": "Frontend action created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_onUserClick" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "User Click Action" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "triggerFunction": { "type": "string", "example": "onUserClick" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "userId" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The user identifier" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "onUserClick" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Create Frontend Action", "tags": [ "Agent Builder Frontend Actions" ], "description": "Creates a new frontend action for the application. Use this endpoint to define a client-side UI operation that agents can trigger during conversations.\n\n**Uniqueness:** The trigger function must be unique per application." } }, "/ai-agents/agent-builder/frontend-actions/{id}": { "get": { "operationId": "FrontendActionsController_getFrontendActionById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Frontend action details", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_onUserClick" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "User Click Action" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "triggerFunction": { "type": "string", "example": "onUserClick" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "userId" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The user identifier" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "onUserClick" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Get Frontend Action", "tags": [ "Agent Builder Frontend Actions" ], "description": "Retrieves a specific frontend action by its unique ID. Use this endpoint to inspect a frontend action's configuration, parameters, and trigger function." }, "patch": { "operationId": "FrontendActionsController_updateFrontendAction", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFrontendActionDto" } } } }, "responses": { "200": { "description": "Frontend action updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "example": "myapp_onUserClick" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "User Click Action" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "triggerFunction": { "type": "string", "example": "onUserClick" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "userId" }, "type": { "type": "string", "example": "string" }, "description": { "type": "string", "example": "The user identifier" }, "required": { "type": "boolean", "example": true } } } }, "tool": { "type": "object", "properties": { "name": { "type": "string", "example": "onUserClick" }, "description": { "type": "string", "example": "Triggered when a user clicks a button" }, "parameters": { "type": "object", "example": { "type": "object", "properties": {}, "required": [] } } } }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Update Frontend Action", "tags": [ "Agent Builder Frontend Actions" ], "description": "Updates an existing frontend action by its unique ID. Use this endpoint to modify a frontend action's parameters, description, or trigger function." }, "delete": { "operationId": "FrontendActionsController_deleteFrontendAction", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Frontend action deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Operation completed successfully" } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Frontend Action", "tags": [ "Agent Builder Frontend Actions" ], "description": "Deletes a frontend action by its unique ID." } }, "/ai-agents/agent-builder/knowledge-base/uploads/initiate": { "post": { "description": "Generates presigned URLs and creates upload records for one or more files. Use this endpoint to prepare files for upload to the knowledge base.\n\n**Workflow:** After receiving the presigned URLs, upload the files directly to the provided URLs, then use the Add Knowledge Base Files endpoint to associate them with an agent.", "operationId": "RagController_initiateUpload", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateUploadDto" }, "examples": { "example1": { "summary": "Upload multiple files", "value": { "files": [ { "fileName": "document.pdf", "mimeType": "application/pdf", "fileSize": 1024000 }, { "fileName": "document_2.pdf", "mimeType": "application/pdf", "fileSize": 512000 } ] } } } } } }, "responses": { "201": { "description": "Presigned URLs generated and upload records created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploads": { "type": "array", "items": { "type": "object", "properties": { "uploadId": { "type": "string", "description": "Unique upload session ID" }, "fileName": { "type": "string", "description": "Original file name" }, "mimeType": { "type": "string", "description": "MIME type of the file" }, "fileSize": { "type": "number", "description": "File size in bytes" }, "s3Key": { "type": "string", "description": "S3 object key for the upload" }, "presignedUrl": { "type": "string", "description": "Presigned URL for direct S3 upload" } } } } } }, "example": { "uploads": [ { "uploadId": "550e8400-e29b-41d4-a716-446655440000", "fileName": "document.pdf", "mimeType": "application/pdf", "fileSize": 1024000, "s3Key": "my-app-id/uploads/550e8400/document.pdf", "presignedUrl": "https://s3.amazonaws.com/bucket/..." } ] } } } } }, "security": [ { "apiKey": [] } ], "summary": "Initiate File Uploads", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/uploads/{uniqueId}": { "delete": { "description": "Deletes an uploaded file and all associated data from the knowledge base by its unique ID.\n\n**Cleanup:** Removes the file, associated embeddings, and any agent references to this file.", "operationId": "RagController_deleteUploadedFile", "parameters": [ { "name": "uniqueId", "required": true, "in": "path", "description": "Unique upload ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Uploaded file deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "File and all associated data deleted successfully" }, "data": { "type": "object", "properties": { "uploadId": { "type": "string" }, "fileName": { "type": "string" }, "deletedFromAgents": { "type": "boolean" }, "vectorsDeleted": { "type": "boolean" } } } } }, "example": { "success": true, "message": "File and all associated data deleted successfully", "data": { "uploadId": "550e8400-e29b-41d4-a716-446655440000", "fileName": "document.pdf", "deletedFromAgents": true, "vectorsDeleted": true, "s3FileDeleted": true } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Uploaded File", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/text": { "post": { "description": "Creates a new text-based knowledge base entry. Use this endpoint to add custom text content that agents can reference during conversations.\n\n**Processing:** Accepts a title and text content, converts it to a Markdown file, and adds it to the knowledge base for indexing.", "operationId": "RagController_createTextDetail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTextDetailDto" }, "examples": { "example1": { "summary": "Create a text detail", "value": { "title": "Company Policy Document", "text": "This document outlines the company policies and procedures for remote work, including communication guidelines, working hours expectations, and performance metrics." } } } } } }, "responses": { "201": { "description": "Text detail created and uploaded to S3 successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Text detail created and uploaded successfully" }, "data": { "type": "object", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the text detail" }, "title": { "type": "string", "description": "Title of the text detail" }, "fileName": { "type": "string", "description": "Generated .md file name" }, "s3Key": { "type": "string", "description": "S3 object key for the uploaded file" }, "status": { "type": "string", "description": "Current processing status", "example": "indexing" } } } } }, "example": { "success": true, "message": "Text detail created and uploaded successfully", "data": { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "title": "Company Policy Document", "fileName": "company-policy-document.md", "s3Key": "my-app-id/text/f47ac10b/company-policy-document.md", "status": "indexing" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Create Text Entry", "tags": [ "knowledge-base" ] }, "get": { "description": "Retrieves all text-based knowledge base entries for the application. Use this endpoint to view and manage text content in the knowledge base.", "operationId": "RagController_getTextDetails", "parameters": [], "responses": { "200": { "description": "Text details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "example": { "data": [ { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "title": "Company Policy Document", "text": "This document outlines...", "fileName": "company-policy-document.md", "s3Key": "my-app-id/text/f47ac10b/company-policy-document.md", "status": "indexed", "createdAt": 1700000000000, "updatedAt": 1700000000000 } ] } } } } }, "security": [ { "apiKey": [] } ], "summary": "List Text Entries", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/text/{uniqueId}": { "get": { "description": "Retrieves a specific text-based knowledge base entry by its unique ID. Use this endpoint to inspect the content and status of a text entry.", "operationId": "RagController_getTextDetailById", "parameters": [ { "name": "uniqueId", "required": true, "in": "path", "description": "Unique text detail ID", "schema": { "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "string" } } ], "responses": { "200": { "description": "Text detail retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "fileName": { "type": "string" }, "s3Key": { "type": "string" }, "status": { "type": "string" }, "vectorizationStatus": { "type": "string" }, "createdAt": { "type": "number" }, "updatedAt": { "type": "number" }, "isActive": { "type": "boolean" } } } } }, "example": { "data": { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "title": "Company Policy Document", "text": "This document outlines...", "fileName": "company-policy-document.md", "s3Key": "my-app-id/text/f47ac10b/company-policy-document.md", "status": "indexed", "vectorizationStatus": "completed", "createdAt": 1700000000000, "updatedAt": 1700000000000, "isActive": true } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Get Text Entry", "tags": [ "knowledge-base" ] }, "patch": { "description": "Updates a specific text-based knowledge base entry by its unique ID. Use this endpoint to modify the title or content of an existing text entry.\n\n**Re-indexing:** The content is re-uploaded and the entry status is reset to indexing.", "operationId": "RagController_updateTextDetail", "parameters": [ { "name": "uniqueId", "required": true, "in": "path", "description": "Unique text detail ID", "schema": { "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTextDetailDto" }, "examples": { "example1": { "summary": "Update text detail", "value": { "title": "Updated Company Policy Document", "text": "This is the updated document content with new policies and procedures..." } } } } } }, "responses": { "200": { "description": "Text detail updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "title": { "type": "string" }, "fileName": { "type": "string" }, "s3Key": { "type": "string" }, "status": { "type": "string" }, "vectorizationStatus": { "type": "string" } } } } }, "example": { "success": true, "message": "Text detail updated successfully", "data": { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "title": "Updated Title", "fileName": "updated-title.md", "s3Key": "my-app-id/text/f47ac10b/updated-title.md", "status": "indexing" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Update Text Entry", "tags": [ "knowledge-base" ] }, "delete": { "description": "Deletes a text-based knowledge base entry and all associated data by its unique ID.\n\n**Cleanup:** Removes the text content, associated embeddings, and any agent references to this entry.", "operationId": "RagController_deleteText", "parameters": [ { "name": "uniqueId", "required": true, "in": "path", "description": "Unique text entry ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Text entry deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Text detail and all associated data deleted successfully" }, "data": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "fileName": { "type": "string" }, "deletedFromAgents": { "type": "boolean" }, "vectorsDeleted": { "type": "boolean" } } } } }, "example": { "success": true, "message": "Text detail and all associated data deleted successfully", "data": { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "fileName": "company-policy-document.md", "uniqueFileId": "file-uuid-123", "deletedFromAgents": true, "vectorsDeleted": true, "s3FileDeleted": true } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Text Entry", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base": { "get": { "description": "Retrieves knowledge base records for the application. Use this endpoint to browse all knowledge base sources including files, text entries, and websites.", "operationId": "RagController_getKnowledgeBase", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "To be used with affix for pagination.", "schema": { "example": "1732492800000.12345", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return per page.", "schema": { "example": 20, "type": "number" } }, { "name": "affix", "required": false, "in": "query", "description": "To paginate over results, use the value of affix as prepend or append.", "schema": { "enum": [ "append", "prepend" ], "type": "string" } }, { "name": "start", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "end", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "endTime", "required": false, "in": "query", "description": "End timestamp (Unix timestamp in milliseconds) to filter records created before this time", "schema": { "example": 1732579200000, "type": "number" } }, { "name": "startTime", "required": false, "in": "query", "description": "Start timestamp (Unix timestamp in milliseconds) to filter records created after this time", "schema": { "example": 1732492800000, "type": "number" } } ], "responses": { "200": { "description": "Knowledge base records retrieved successfully with pagination metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of knowledge base records (excludes _id, __v, paginationKey)", "items": { "type": "object", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the record" }, "appId": { "type": "string", "description": "Application ID" }, "sourceName": { "type": "string", "description": "Name of the source file or text detail" }, "type": { "type": "string", "description": "Type of source (uploads, text-details)" }, "status": { "type": "string", "description": "Current status (inSync, indexing, indexed, failed)" }, "lastSynced": { "type": "number", "description": "Timestamp of last synchronization" }, "createdAt": { "type": "number", "description": "Creation timestamp" }, "updatedAt": { "type": "number", "description": "Last update timestamp" } } } }, "meta": { "type": "object", "description": "Pagination metadata for navigation", "properties": { "current": { "type": "object", "properties": { "limit": { "type": "number", "description": "Requested page limit" }, "count": { "type": "number", "description": "Actual number of records returned" } } }, "previous": { "type": "object", "description": "Previous page navigation (only present if previous page exists)", "properties": { "affix": { "type": "string", "enum": [ "prepend" ], "description": "Direction for previous page" }, "cursor": { "type": "string", "description": "Cursor for previous page" } } }, "next": { "type": "object", "description": "Next page navigation (only present if next page exists)", "properties": { "affix": { "type": "string", "enum": [ "append" ], "description": "Direction for next page" }, "cursor": { "type": "string", "description": "Cursor for next page" } } } } } } }, "example": { "data": [ { "uniqueId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "appId": "my-app-id", "sourceName": "document.pdf", "type": "uploads", "status": "indexed", "lastSynced": 1700000000000, "createdAt": 1700000000000, "updatedAt": 1700000000000 } ], "meta": { "current": { "limit": 10, "count": 1 }, "previous": { "affix": "prepend", "cursor": "1700000000000.12345" }, "next": { "affix": "append", "cursor": "1700000000000.12345" } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "List Knowledge Base Records", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/{sourceType}/{uniqueId}/pages": { "get": { "description": "Retrieves paginated pages for a specific knowledge base source file. Use this endpoint to inspect the individual pages extracted from a knowledge base source.", "operationId": "RagController_getSourcePages", "parameters": [ { "name": "sourceType", "required": true, "in": "path", "description": "Source type (uploads, text, website)", "schema": { "enum": [ "uploads", "text", "website" ], "type": "string" } }, { "name": "uniqueId", "required": true, "in": "path", "description": "Unique file ID to fetch pages for", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return per page.", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "To be used with affix for pagination.", "schema": { "type": "number" } }, { "name": "affix", "required": false, "in": "query", "description": "To paginate over results, use the value of affix as prepend or append.", "schema": { "enum": [ "prepend", "append" ], "type": "string" } } ], "responses": { "200": { "description": "Source pages retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sourceDetails": { "type": "object", "properties": { "fileName": { "type": "string", "example": "product-guide.pdf" }, "totalPages": { "type": "number", "example": 1 }, "createdAt": { "type": "integer", "example": "2026-03-12T12:52:28.063000" } } }, "pageContent": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "pageNumber": { "type": "number" }, "charCount": { "type": "number" } } } } } }, "meta": { "type": "object", "properties": { "current": { "type": "object", "properties": { "limit": { "type": "number" }, "count": { "type": "number" } } } } } } }, "example": { "data": { "sourceDetails": { "fileName": "product-guide.pdf", "totalPages": 1, "createdAt": "2026-03-12T12:52:28.063000" }, "pageContent": [ { "content": "This is the extracted text content from the first page of the uploaded document. It contains the information that was indexed into the knowledge base for retrieval during agent conversations.", "pageNumber": 1, "charCount": 185 } ] }, "meta": { "current": { "limit": 1, "count": 1 } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Get Source Pages", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/{sourceType}/{uniqueId}/sync": { "patch": { "description": "Retries the indexing process for a specific knowledge base source that failed during its initial processing. Provide the source type and its unique ID to re-trigger vectorization.\n\n**Supported source types:** `uploads`, `text`, `website`.", "operationId": "RagController_revectorizeSource", "parameters": [ { "name": "sourceType", "required": true, "in": "path", "description": "Source type (uploads, text, website)", "schema": { "enum": [ "uploads", "text", "website" ], "type": "string" } }, { "name": "uniqueId", "required": true, "in": "path", "description": "Unique source ID to sync", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revectorization triggered successfully.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Retry Knowledge Base Source Indexing", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/knowledge-base/status/poll": { "post": { "operationId": "RagController_getBatchStatus", "parameters": [], "requestBody": { "required": true, "description": "Array of unique IDs to query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusQueryDto" } } } }, "responses": { "200": { "description": "Status for requested unique IDs", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "id1": "indexing", "id2": "indexed" } } }, "example": { "success": true, "data": { "id1": "indexing", "id2": "indexed" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Poll Knowledge Base Status", "tags": [ "knowledge-base" ], "description": "Retrieves the indexing status for one or more knowledge base sources by their IDs. Use this endpoint to monitor the progress of file uploads, text entries, or website crawls being indexed.\n\n**Batch support:** Accepts multiple IDs in a single request to efficiently check status across sources." } }, "/ai-agents/agent-builder/knowledge-base/website/scrape": { "post": { "description": "Scrapes a website to discover and crawl its pages for the knowledge base. Use this endpoint to add website content as a knowledge source for agents.\n\n**Configuration:** Supports options for URL filtering and crawl depth control.", "operationId": "CrawlWebPagesController_crawlWebsite", "parameters": [], "requestBody": { "required": true, "description": "Website crawling configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapePagesDto" }, "examples": { "basic": { "summary": "Website sitemap scrape", "description": "Scrape website and fetch sitemap with basic configuration", "value": { "url": "https://example.com", "maxDepth": 3, "maxPages": 5 } } } } } }, "responses": { "200": { "description": "Website scraped successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Website scrape completed successfully" }, "data": { "type": "object", "properties": { "crawlId": { "type": "string", "example": "crawl-1701789123456" }, "crawlDuration": { "type": "number", "example": 120000 }, "status": { "type": "string", "example": "completed" }, "sitemap": { "type": "object", "properties": { "found": { "type": "boolean", "example": true }, "url": { "type": "string", "example": "https://docs.example.com/sitemap.xml" }, "totalUrls": { "type": "number", "example": 245 }, "urls": { "type": "array", "items": { "type": "string" } }, "lastModified": { "type": "string", "example": "2025-12-05T10:30:00Z" } } } } } } }, "example": { "success": true, "message": "Website scrape completed successfully", "data": { "crawlId": "crawl-1701789123456", "crawlDuration": 120000, "status": "completed", "sitemap": { "found": true, "url": "https://docs.example.com/sitemap.xml", "totalUrls": 245, "urls": [ "https://docs.example.com/page1", "https://docs.example.com/page2" ], "lastModified": "2025-12-05T10:30:00Z" } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Crawl Website", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/individual-page": { "post": { "description": "Scrapes a single webpage to extract its content for the knowledge base. Use this endpoint to add a specific page without crawling an entire website.\n\n**Extraction:** Returns the page title, description, and full content.", "operationId": "CrawlWebPagesController_scrapePage", "parameters": [], "requestBody": { "required": true, "description": "Single page scraping configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeIndividualPageDto" }, "examples": { "basic": { "summary": "Basic page scrape", "description": "Simple page content extraction", "value": { "url": "https://docs.example.com/getting-started", "timeout": 30000, "format": "markdown" } } } } } }, "responses": { "200": { "description": "Page scraped successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Page scraped successfully" }, "data": { "type": "object", "properties": { "url": { "type": "string", "example": "https://docs.example.com/getting-started" }, "title": { "type": "string", "example": "Getting Started Guide" }, "description": { "type": "string", "example": "Learn how to get started with our platform" }, "content": { "type": "string", "example": "# Getting Started\n\nWelcome to our platform..." }, "metadata": { "type": "object", "properties": { "og": { "type": "object" }, "twitter": { "type": "object" }, "canonical": { "type": "string" }, "language": { "type": "string" } } }, "scraper": { "type": "string", "example": "Firecrawl" }, "crawlDuration": { "type": "number", "example": 2500 }, "contentLength": { "type": "number", "example": 1024 }, "timestamp": { "type": "string", "example": "2025-12-05T17:30:00Z" } } } } }, "example": { "success": true, "message": "Page scraped successfully", "data": { "url": "https://docs.example.com/getting-started", "title": "Getting Started Guide", "description": "Learn how to get started with our platform", "content": "# Getting Started\n\nWelcome to our platform...", "metadata": { "og": {}, "twitter": {}, "canonical": "", "language": "en" }, "scraper": "Firecrawl", "crawlDuration": 2500, "contentLength": 1024, "timestamp": "2025-12-05T17:30:00Z" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Scrape Single Page", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/{parentUniqueId}/discovered-urls": { "get": { "description": "Retrieves all URLs discovered during a website crawl. Use this endpoint to review which pages were found before processing them.", "operationId": "CrawlWebPagesController_getDiscoveredUrls", "parameters": [ { "name": "parentUniqueId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "To be used with affix for pagination.", "schema": { "example": "1701789000000", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of results to return per page.", "schema": { "example": 20, "type": "number" } }, { "name": "affix", "required": false, "in": "query", "description": "To paginate over results, use the value of affix as prepend or append.", "schema": { "enum": [ "append", "prepend" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by URL processing status", "schema": { "enum": [ "discovered", "processing", "processed", "failed", "skipped" ], "type": "string" } }, { "name": "startTime", "required": false, "in": "query", "description": "Start timestamp (Unix timestamp in milliseconds) to filter records created after this time", "schema": { "example": 1701780000000, "type": "number" } }, { "name": "endTime", "required": false, "in": "query", "description": "End timestamp (Unix timestamp in milliseconds) to filter records created before this time", "schema": { "example": 1701790000000, "type": "number" } }, { "name": "parentId", "required": true, "in": "path", "description": "Unique ID of the parent crawl (from WebPages collection)", "schema": { "example": "uuid-1234-5678-9abc" } } ], "responses": { "200": { "description": "Discovered URLs retrieved successfully with pagination metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of discovered URL records", "items": { "type": "object", "properties": { "urlId": { "type": "string", "description": "Unique identifier for the discovered URL", "example": "uuid-abcd-1234" }, "url": { "type": "string", "description": "The discovered URL", "example": "https://docs.example.com/guide" }, "title": { "type": "string", "description": "Page title extracted from the URL", "example": "Getting Started Guide" }, "description": { "type": "string", "description": "Page description or meta description", "example": "Learn how to get started..." }, "content": { "type": "string", "description": "Page content preview (truncated to 500 characters)", "example": "Page content preview..." }, "status": { "type": "string", "description": "Processing status of the URL", "example": "processed" }, "lastCrawledAt": { "type": "number", "description": "Timestamp when URL was last crawled", "example": 1701789123456 }, "retryCount": { "type": "number", "description": "Number of retry attempts", "example": 0 }, "createdAt": { "type": "number", "description": "Creation timestamp", "example": 1701789000000 }, "updatedAt": { "type": "number", "description": "Last update timestamp", "example": 1701789123456 }, "vectorizationStatus": { "type": "string", "description": "Status of content vectorization", "example": "completed" }, "chunksCreated": { "type": "number", "description": "Number of text chunks created", "example": 5 }, "embeddingsGenerated": { "type": "number", "description": "Number of embeddings generated", "example": 5 } } } }, "meta": { "type": "object", "description": "Pagination metadata for navigation", "properties": { "current": { "type": "object", "properties": { "limit": { "type": "number", "description": "Records per page limit used for this request" }, "count": { "type": "number", "description": "Number of records returned in this page" } } }, "previous": { "type": "object", "description": "Navigation info for previous page (newer records). Present only if there are newer records available.", "properties": { "affix": { "type": "string", "enum": [ "prepend" ], "description": "Use \"prepend\" to get previous/newer records" }, "cursor": { "type": "string", "description": "Cursor value to use in next request for previous page" } } }, "next": { "type": "object", "description": "Navigation info for next page (older records). Present only if there are older records available.", "properties": { "affix": { "type": "string", "enum": [ "append" ], "description": "Use \"append\" to get next/older records" }, "cursor": { "type": "string", "description": "Cursor value to use in next request for next page" } } } } } } }, "example": { "data": [ { "urlId": "uuid-abcd-1234", "url": "https://docs.example.com/guide", "title": "Getting Started Guide", "description": "Learn how to get started...", "content": "Page content preview...", "status": "processed", "lastCrawledAt": 1701789123456, "retryCount": 0, "createdAt": 1701789000000, "updatedAt": 1701789123456, "vectorizationStatus": "completed", "chunksCreated": 5, "embeddingsGenerated": 5 } ], "meta": { "current": { "limit": 10, "count": 1 }, "previous": { "affix": "prepend", "cursor": "1701789000000" }, "next": { "affix": "append", "cursor": "1701789000000" } } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Get Discovered URLs", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/{parentUniqueId}/discovered-urls/process": { "post": { "description": "Marks discovered URLs for exclusion and initiates batch crawling of the remaining URLs. Use this endpoint to selectively process pages discovered during a website crawl.", "operationId": "CrawlWebPagesController_processDiscoveredUrls", "parameters": [ { "name": "parentUniqueId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Discovered URLs processing configuration. App ID is taken from header, not body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDiscoveredUrlsDto" } } } }, "responses": { "200": { "description": "Batch processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Batch processing initiated successfully" }, "data": { "type": "object", "properties": { "batchId": { "type": "string", "example": "batch-1701789123456" }, "urlsProcessed": { "type": "number", "example": 2 }, "totalUrls": { "type": "number", "example": 2 }, "webhookUrl": { "type": "string", "example": "https://webhook.site/b4994000-62d9-4e17-928f-790282cb5815" }, "status": { "type": "string", "example": "processing" } } } } }, "example": { "success": true, "message": "Batch processing initiated successfully", "data": { "batchId": "batch-1701789123456", "urlsProcessed": 2, "totalUrls": 2, "webhookUrl": "https://webhook.site/b4994000-62d9-4e17-928f-790282cb5815", "status": "processing" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Process Discovered URLs", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/{parentUniqueId}/discovered-urls/status/poll": { "post": { "description": "Retrieves the processing status of discovered URLs by their unique IDs. Use this endpoint to monitor the progress of URL crawling within a parent website crawl.\n\n**Behavior:** Only returns records for existing unique IDs; non-existing IDs are omitted from the response.", "operationId": "CrawlWebPagesController_getDiscoveredUrlsStatus", "parameters": [ { "name": "parentUniqueId", "required": true, "in": "path", "description": "Parent website crawl unique ID", "schema": { "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "string" } } ], "requestBody": { "required": true, "description": "Array of discovered URL unique IDs to query status for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveredUrlsStatusQueryDto" }, "examples": { "example1": { "summary": "Query multiple discovered URL statuses", "value": { "uniqueId": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1" ] } } } } } }, "responses": { "200": { "description": "Status for requested discovered URLs (omits non-existing uniqueIds)", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "fb45bb1e-bc81-45a8-85be-36b2aa4f289e": "processed", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1": "discovered" } } }, "example": { "success": true, "data": { "fb45bb1e-bc81-45a8-85be-36b2aa4f289e": "processed", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1": "discovered" } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Poll Discovered URLs Status", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/{parentUniqueId}/discovered-urls/sync": { "patch": { "description": "Retries the indexing process for specific pages under a website knowledge base source. Pass the unique IDs of the pages to re-index, or send an empty array to automatically retry all pages that failed during a previous indexing attempt.", "operationId": "CrawlWebPagesController_syncDiscoveredUrls", "parameters": [ { "name": "parentUniqueId", "required": true, "in": "path", "description": "Parent website crawl unique ID", "schema": { "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "string" } } ], "requestBody": { "required": true, "description": "Array of discovered URL unique IDs to sync. Only non-excluded URLs will be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDiscoveredUrlsDto" }, "examples": { "sync_specific_urls": { "summary": "Sync specific discovered URLs", "description": "Process only the specified discovered URLs that are not excluded", "value": { "uniqueIds": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1", "550e8400-e29b-41d4-a716-446655440003" ] } } } } } }, "responses": { "200": { "description": "Sync processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Sync processing initiated successfully" }, "data": { "type": "object", "properties": { "batchId": { "type": "string", "example": "sync-batch-1701789123456" }, "urlsProcessed": { "type": "number", "example": 2 }, "totalRequested": { "type": "number", "example": 3 }, "excludedUrls": { "type": "number", "example": 1 }, "webhookUrl": { "type": "string", "example": "https://webhook.site/b4994000-62d9-4e17-928f-790282cb5815" }, "status": { "type": "string", "example": "processing" }, "processedUrls": { "type": "array", "items": { "type": "string" }, "example": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1" ] } } } } }, "example": { "success": true, "message": "Sync processing initiated successfully", "data": { "batchId": "sync-batch-1701789123456", "urlsProcessed": 2, "totalRequested": 3, "excludedUrls": 1, "webhookUrl": "https://webhook.site/b4994000-62d9-4e17-928f-790282cb5815", "status": "processing", "processedUrls": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1" ] } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Retry Indexing for Website Pages", "tags": [ "crawl-web-pages" ] } }, "/ai-agents/agent-builder/knowledge-base/website/{uniqueId}": { "delete": { "description": "Deletes a website crawl and all associated data from the knowledge base by its unique ID.\n\n**Cleanup:** Removes all crawled pages, associated embeddings, and any agent references to this website.", "operationId": "CrawlWebPagesController_deleteWebsite", "parameters": [ { "name": "uniqueId", "required": true, "in": "path", "description": "Unique website crawl ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Website and all associated data deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Website and all associated data deleted successfully" }, "data": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "deletedFromAgents": { "type": "boolean" }, "vectorsDeleted": { "type": "boolean" } } } } }, "example": { "success": true, "message": "File and all associated data deleted successfully", "data": { "uniqueId": "website-uuid-123", "deletedFromAgents": true, "vectorsDeleted": true, "s3FileDeleted": true } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Website", "tags": [ "knowledge-base" ] } }, "/ai-agents/agent-builder/agents/{uid}/enabled-items": { "get": { "operationId": "AgentBuilderController_getEnabledItems", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } }, { "name": "tools", "required": false, "in": "query", "description": "Include enabled tools (default: true)", "schema": { "default": true, "type": "boolean" } }, { "name": "frontendActions", "required": false, "in": "query", "description": "Include enabled frontend actions (default: true)", "schema": { "default": true, "type": "boolean" } }, { "name": "apiTools", "required": false, "in": "query", "description": "Include enabled API tools (default: true)", "schema": { "default": true, "type": "boolean" } }, { "name": "mcpServers", "required": false, "in": "query", "description": "Include enabled MCP servers (default: true)", "schema": { "default": true, "type": "boolean" } }, { "name": "key", "required": false, "in": "query", "description": "Search term to filter by name/description", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Categorized enabled items for the agent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } } }, "frontendActions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "triggerFunction": { "type": "string" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } } } } } } }, "apiTools": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" } } } } } } }, "mcpServers": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "url": { "type": "string" } } } } } } } }, "example": { "data": { "tools": [ { "slug": "gmail", "name": "Gmail", "description": "Gmail integration", "icon": "https://example.com/gmail-icon.png", "actions": [ { "slug": "GMAIL_SEND_EMAIL", "name": "Send Email", "description": "Send an email via Gmail" } ] } ], "frontendActions": [ { "id": "myapp_onUserClick", "name": "User Click Action", "description": "Triggered when a user clicks a button", "triggerFunction": "onUserClick", "parameters": [ { "key": "userId", "type": "string", "description": "The user identifier", "required": true } ] } ], "apiTools": [ { "slug": "my-api-tool", "name": "My API Tool", "description": "Calls an external API", "icon": "https://example.com/icon.png", "endpoint": "https://api.example.com/search", "method": "GET", "parameters": [ { "key": "query", "type": "string", "description": "The search query", "required": true } ] } ], "mcpServers": [ { "slug": "my-mcp-server", "name": "My MCP Server", "description": "A Model Context Protocol server", "icon": "https://example.com/icon.png", "url": "https://mcp.example.com/sse" } ] } } } } } }, "security": [ { "apiKey": [] } ], "summary": "List Agent Tools and Actions", "tags": [ "Agent Builder" ], "description": "Retrieves all enabled items for a specific agent, categorized by type. Use this endpoint to see which tools, frontend actions, API tools, and MCP servers are currently enabled for an agent.\n\n**Categories:** Results are grouped into tools, frontend actions, API tools, and MCP servers. Use query parameters to include or exclude specific categories.\n\n**Search:** Use the `key` parameter to filter enabled items by name or description." } }, "/ai-agents/agent-builder/agents/{uid}/tools/add": { "patch": { "operationId": "AgentBuilderController_addToolsToAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentToolsDto" } } } }, "responses": { "200": { "description": "Tools successfully added to the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Add Tools to Agent", "tags": [ "Agent Builder" ], "description": "Adds one or more tools to a specific agent. Use this endpoint to extend an agent's capabilities with additional tool integrations.\n\n**Request body:** The `tools` array contains tool slugs. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/tools/remove": { "patch": { "operationId": "AgentBuilderController_removeToolsFromAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentToolsDto" } } } }, "responses": { "200": { "description": "Tools successfully removed from the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove Tools from Agent", "tags": [ "Agent Builder" ], "description": "Removes one or more tools from a specific agent. Use this endpoint to revoke tool access from an agent.\n\n**Request body:** The `tools` array contains tool slugs to remove. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/mcp/add": { "patch": { "operationId": "AgentBuilderController_addMcpServersToAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentMcpDto" } } } }, "responses": { "200": { "description": "MCP servers successfully added to the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Add MCP Servers to Agent", "tags": [ "Agent Builder" ], "description": "Adds one or more MCP servers to a specific agent. Use this endpoint to connect an agent to additional Model Context Protocol servers.\n\n**Request body:** The `mcps` array contains MCP server slugs. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/mcp/remove": { "patch": { "operationId": "AgentBuilderController_removeMcpServersFromAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentMcpDto" } } } }, "responses": { "200": { "description": "MCP servers successfully removed from the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove MCP Servers from Agent", "tags": [ "Agent Builder" ], "description": "Removes one or more MCP servers from a specific agent. Use this endpoint to disconnect MCP servers from an agent.\n\n**Request body:** The `mcps` array contains MCP server slugs to remove. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/api-tools/add": { "patch": { "operationId": "AgentBuilderController_addApiToolsToAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentApiToolsDto" } } } }, "responses": { "200": { "description": "API tools successfully added to the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Add API Tools to Agent", "tags": [ "Agent Builder" ], "description": "Adds one or more API tools to a specific agent. Use this endpoint to give an agent access to custom API tool integrations.\n\n**Request body:** The `apiTools` array contains API tool slugs. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/api-tools/remove": { "patch": { "operationId": "AgentBuilderController_removeApiToolsFromAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentApiToolsDto" } } } }, "responses": { "200": { "description": "API tools successfully removed from the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove API Tools from Agent", "tags": [ "Agent Builder" ], "description": "Removes one or more API tools from a specific agent. Use this endpoint to revoke API tool access from an agent.\n\n**Request body:** The `apiTools` array contains API tool slugs to remove. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/frontend-actions/add": { "patch": { "operationId": "AgentBuilderController_addFrontendActionsToAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentFrontendActionsDto" } } } }, "responses": { "200": { "description": "Frontend actions successfully added to the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Add Frontend Actions to Agent", "tags": [ "Agent Builder" ], "description": "Adds one or more frontend actions to a specific agent. Use this endpoint to enable an agent to trigger client-side UI operations.\n\n**Frontend actions** allow agents to interact with the user interface, such as opening dialogs, navigating pages, or updating UI state.\n\n**Request body:** The `frontendActions` array contains frontend action identifiers. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/frontend-actions/remove": { "patch": { "operationId": "AgentBuilderController_removeFrontendActionsFromAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageAgentFrontendActionsDto" } } } }, "responses": { "200": { "description": "Frontend actions successfully removed from the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } } } }, "example": { "success": true, "data": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail", "slack" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove Frontend Actions from Agent", "tags": [ "Agent Builder" ], "description": "Removes one or more frontend actions from a specific agent. Use this endpoint to revoke frontend action capabilities from an agent.\n\n**Request body:** The `frontendActions` array contains frontend action identifiers to remove. Returns the updated agent object." } }, "/ai-agents/agent-builder/agents/{uid}/tools/{slug}/actions/add": { "patch": { "operationId": "AgentBuilderController_addActionsToTool", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "AI Agent UID", "schema": { "type": "string" } }, { "name": "slug", "required": true, "in": "path", "description": "Tool slug (e.g., gmail, googlesheets)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageActionsDto" } } } }, "responses": { "200": { "description": "Actions added successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Enable actions for a tool", "description": "Adds actions to a specific tool attached to an agent.", "tags": [ "Agent Builder" ] } }, "/ai-agents/agent-builder/agents/{uid}/tools/{slug}/actions/remove": { "patch": { "operationId": "AgentBuilderController_removeActionsFromTool", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "AI Agent UID", "schema": { "type": "string" } }, { "name": "slug", "required": true, "in": "path", "description": "Tool slug (e.g., gmail, googlesheets)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageActionsDto" } } } }, "responses": { "200": { "description": "Actions removed successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove actions for a tool", "description": "Removes actions from a specific tool attached to an agent.", "tags": [ "Agent Builder" ] } }, "/ai-agents/agent-builder/agents/{uid}/tools/{slug}/actions": { "get": { "operationId": "ReadyToUseToolsController_getAvailableToolsForAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "AI Agent UID", "schema": { "type": "string" } }, { "name": "slug", "required": true, "in": "path", "description": "Get actions available within a tool (e.g., send-email, draft-email)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available tool actions retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" } } } }, "example": [ { "name": "GMAIL_SEND_EMAIL", "displayName": "Send Email", "description": "Send an email via Gmail" }, { "name": "GMAIL_DRAFT_EMAIL", "displayName": "Draft Email", "description": "Create a draft email" } ] } } } }, "security": [ { "apiKey": [] } ], "summary": "Get actions available within a tool for agent", "description": "Lists all actions available for a specific tool attached to an agent.", "tags": [ "Agent Builder Ready to Use Tools" ] } }, "/ai-agents/agents/{uid}": { "patch": { "operationId": "AgentsController_updateAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "schema": { "type": "string" }, "description": "Unique identifier of the agent" }, { "name": "chatApiVersion", "required": false, "in": "header", "description": "Chat API version. Defaults to `v3.0`.", "schema": { "type": "string", "default": "v3.0" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentDTO" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessBooleanResponse" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agents" ], "description": "Updates an existing BYO Agent by its UID. Use this endpoint to modify agent configuration, update referenced tools, or change the connected AI framework.\n\n**Validation:** Referenced tools and actions are validated if provided.", "summary": "Update BYO Agent" }, "delete": { "operationId": "AgentsController_deleteAgent", "parameters": [ { "name": "uid", "required": true, "in": "path", "schema": { "type": "string" }, "description": "Unique identifier of the agent" } ], "responses": { "200": { "description": "Agent deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Agent with UID '863f3501-af1b-46c1-9740-5c725b85daba' has been deleted successfully" } } } } }, "security": [ { "apiKey": [] } ], "tags": [ "Agents" ], "description": "Deletes a BYO Agent by its UID.", "summary": "Delete BYO Agent" } }, "/ai-agents/agent-builder/agents/{uid}/tools/search": { "get": { "operationId": "AgentBuilderController_searchAllTools", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } }, { "name": "key", "required": false, "in": "query", "description": "Search term to filter actions by name, description, or slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregated search results from all tool sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "type": "object" }, "example": [] } } }, "example": { "success": true, "results": [] } } } } }, "security": [ { "apiKey": [] } ], "summary": "Search Agent Tools", "tags": [ "Agent Builder" ], "description": "Searches across all tool types available for an agent, including ready-to-use tools, API tools, and MCP servers. Use this endpoint to find specific tools across all categories.\n\n**Filtering:** Use the `key` parameter to filter by name, description, or slug, and the `slug` parameter to filter by a specific integration." } }, "/ai-agents/agent-builder/agents/{uid}": { "get": { "operationId": "AgentBuilderController_findOne", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string", "example": "agent-uuid-1234" }, "appId": { "type": "string", "example": "my-app-id" }, "name": { "type": "string", "example": "Support Agent" }, "icon": { "type": "string", "example": "https://example.com/icon.png" }, "isActive": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "A helpful support agent" }, "tools": { "type": "array", "items": { "type": "string" }, "example": [ "gmail", "slack" ] }, "files": { "type": "array", "items": { "type": "string" }, "example": [] }, "websites": { "type": "array", "items": { "type": "string" }, "example": [] }, "otherKbIntegrations": { "type": "array", "items": { "type": "string" }, "example": [] }, "apiTools": { "type": "array", "items": { "type": "string" }, "example": [] }, "mcpServers": { "type": "array", "items": { "type": "string" }, "example": [] }, "frontendActions": { "type": "array", "items": { "type": "string" }, "example": [] }, "ragVersion": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "lastMessageAt": { "type": "number", "nullable": true, "example": 1700000000000 }, "instruction": { "type": "string", "example": "You are a helpful assistant" }, "formattedInstruction": { "type": "string", "example": "You are a helpful assistant" }, "metaData": { "type": "object", "example": {} }, "model": { "type": "string", "example": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "example": {} }, "createdAt": { "type": "number", "example": 1700000000000 }, "updatedAt": { "type": "number", "example": 1700000000000 } } }, "example": { "uid": "agent-uuid-1234", "appId": "my-app-id", "name": "Support Agent", "icon": "https://example.com/icon.png", "isActive": true, "description": "A helpful support agent", "tools": [ "gmail" ], "files": [], "websites": [], "otherKbIntegrations": [], "apiTools": [], "mcpServers": [], "frontendActions": [], "ragVersion": "v2", "lastMessageAt": null, "instruction": "You are a helpful assistant", "formattedInstruction": "You are a helpful assistant", "metaData": {}, "model": "gpt-4o-mini", "modelMetaData": {}, "createdAt": 1700000000000, "updatedAt": 1700000000000 } } } } }, "security": [ { "apiKey": [] } ], "summary": "Get Agent", "tags": [ "Agent Builder" ], "description": "Retrieves a specific agent by its UID. Use this endpoint to inspect an agent's full configuration, including its tools, model, and instructions." }, "patch": { "operationId": "AgentBuilderController_update", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCometChatAgentDto" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessBooleanResponse" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Update Agent", "tags": [ "Agent Builder" ], "description": "Updates an existing agent by its UID. Use this endpoint to modify an agent's configuration, instructions, model, or connected tools.\n\n**Validation:** Referenced tools, API tools, and MCP servers are validated if provided." }, "delete": { "operationId": "AgentBuilderController_remove", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageResponse" }, "example": { "success": true, "message": "Operation completed successfully" } } } } }, "security": [ { "apiKey": [] } ], "summary": "Delete Agent", "tags": [ "Agent Builder" ], "description": "Deletes an agent by its UID." } }, "/ai-agents/agent-builder/agents/{uid}/knowledge-base/{sourceType}/add": { "patch": { "operationId": "AgentBuilderController_addFilesToKnowledgeBase", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } }, { "name": "sourceType", "required": true, "in": "path", "description": "Source type (uploads, knowledge-base, etc.)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageKnowledgeBaseFilesDto" } } } }, "responses": { "200": { "description": "Files added to knowledge base successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Add Files to Agent Knowledge Base", "tags": [ "Agent Builder" ], "description": "Associates uploaded files or text entries with an agent's knowledge base. Use this endpoint after uploading files via the Initiate File Uploads endpoint to make them available to the agent.\n\n**Source types:** Specify the source type (e.g., uploads, text) in the path." } }, "/ai-agents/agent-builder/agents/{uid}/knowledge-base/{sourceType}/remove": { "patch": { "operationId": "AgentBuilderController_removeFilesFromKnowledgeBase", "parameters": [ { "name": "uid", "required": true, "in": "path", "description": "Unique identifier of the agent", "schema": { "type": "string" } }, { "name": "sourceType", "required": true, "in": "path", "description": "Source type (uploads, knowledge-base, etc.)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageKnowledgeBaseFilesDto" } } } }, "responses": { "200": { "description": "Files removed from knowledge base successfully", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } } }, "security": [ { "apiKey": [] } ], "summary": "Remove Files from Agent Knowledge Base", "tags": [ "Agent Builder" ], "description": "Removes files or text entries from an agent's knowledge base. Use this endpoint to disassociate specific sources from an agent without deleting the underlying content.\n\n**Source types:** Specify the source type (e.g., uploads, text) in the path." } } }, "info": { "title": "AI Agents APIs", "description": "API reference for CometChat AI Agents service", "version": "1.0" }, "tags": [ { "name": "ai-agent", "description": "" } ], "servers": [ { "url": "https://{appId}.api-{region}.cometchat.io/v3", "variables": { "appId": { "default": "appId", "description": "(Required) App ID" }, "region": { "enum": [ "us", "eu", "in" ], "default": "us", "description": "Select Region" } } } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "API Key (i.e. Rest API Key from the Dashboard).", "name": "apikey", "in": "header" } }, "schemas": { "CreateAgentDTO": { "discriminator": { "propertyName": "integrateWith", "mapping": { "mastra": "#/components/schemas/CreateMastraAgentDTO", "mastra-legacy": "#/components/schemas/CreateMastraLegacyAgentDTO", "langgraph": "#/components/schemas/CreateLangGraphAgentDTO", "crewai": "#/components/schemas/CreateCrewAIAgentDTO", "vercelV5": "#/components/schemas/CreateVercelV5AgentDTO", "ag2": "#/components/schemas/CreateAG2AgentDTO", "rasa": "#/components/schemas/CreateRasaAgentDTO", "agno": "#/components/schemas/CreateAgnoAgentDTO", "ag-ui": "#/components/schemas/CreateAGUIAgentDTO" } }, "oneOf": [ { "$ref": "#/components/schemas/CreateMastraAgentDTO" }, { "$ref": "#/components/schemas/CreateMastraLegacyAgentDTO" }, { "$ref": "#/components/schemas/CreateLangGraphAgentDTO" }, { "$ref": "#/components/schemas/CreateCrewAIAgentDTO" }, { "$ref": "#/components/schemas/CreateVercelV5AgentDTO" }, { "$ref": "#/components/schemas/CreateAG2AgentDTO" }, { "$ref": "#/components/schemas/CreateRasaAgentDTO" }, { "$ref": "#/components/schemas/CreateAgnoAgentDTO" }, { "$ref": "#/components/schemas/CreateAGUIAgentDTO" } ] }, "CreateMastraAgentDTO": { "title": "Mastra", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My Mastra Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "mastra" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "Mastra-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Mastra agent is hosted", "example": "https://my-mastra-app.example.com" }, "agentId": { "type": "string", "description": "Mastra Agent ID", "example": "weatherAgent" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateMastraLegacyAgentDTO": { "title": "Mastra (Legacy)", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My Legacy Mastra Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "mastra-legacy" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "Mastra (Legacy) configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Mastra agent is hosted", "example": "https://my-mastra-legacy.example.com" }, "agentId": { "type": "string", "description": "Mastra Agent ID", "example": "weatherAgent" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateLangGraphAgentDTO": { "title": "LangGraph", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My LangGraph Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "langgraph" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "LangGraph-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your agent is hosted", "example": "https://my-langgraph-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateCrewAIAgentDTO": { "title": "CrewAI", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My CrewAI Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "crewai" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "CrewAI compatible agent configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your CrewAI agent is hosted", "example": "https://my-crewai-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateVercelV5AgentDTO": { "title": "Vercel AI V5", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My Vercel Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "vercelV5" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "Vercel AI V5 configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Vercel AI agent is hosted", "example": "https://my-vercel-app.vercel.app/api/chat" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Bearer token123" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateAG2AgentDTO": { "title": "AG2", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My AG2 Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "ag2" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "AG2-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your AG2 agent is hosted", "example": "https://my-ag2-app.example.com" }, "defaultUserId": { "type": "string", "description": "Default User ID", "example": "user_123" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line. Should be valid JSON", "example": "{\"authorization\": \"Bearer token123\"}" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateRasaAgentDTO": { "title": "Rasa", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My Rasa Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "rasa" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "Rasa-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Rasa agent is hosted", "example": "https://my-rasa-app.example.com" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateAgnoAgentDTO": { "title": "Agno", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My Agno Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "agno" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "Agno-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Agno agent is hosted", "example": "https://my-agno-app.example.com" }, "agentId": { "type": "string", "description": "Agno Agent ID", "example": "my-agent-id" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateAGUIAgentDTO": { "title": "AG-UI", "type": "object", "required": [ "name", "integrateWith", "integrationType", "icon" ], "properties": { "name": { "type": "string", "description": "Name of the agent", "example": "My AG-UI Agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "ag-ui" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "required": [ "baseUrl" ], "description": "AG-UI compatible agent configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your AG-UI agent is hosted", "example": "https://my-agui-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "GetAgentDetailDto": { "type": "object", "properties": { "uid": { "type": "string", "description": "Unique identifier of the agent" }, "appId": { "type": "string", "description": "Application ID" }, "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "description": "URL to the agent's avatar" }, "isActive": { "type": "boolean", "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "description": "Integration platform identifier" }, "integrationType": { "type": "string", "description": "Type of connection" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of connected tools" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of connected actions" }, "integrationMeta": { "type": "object", "description": "Integration-specific configuration" }, "metaData": { "type": "object", "description": "Agent metadata" }, "_id": { "type": "string", "description": "Internal document ID" }, "createdAt": { "type": "integer", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "integer", "format": "date-time", "description": "Last update timestamp" } } }, "UpdateAgentDTO": { "discriminator": { "propertyName": "integrateWith", "mapping": { "mastra": "#/components/schemas/UpdateMastraAgentDTO", "mastra-legacy": "#/components/schemas/UpdateMastraLegacyAgentDTO", "langgraph": "#/components/schemas/UpdateLangGraphAgentDTO", "crewai": "#/components/schemas/UpdateCrewAIAgentDTO", "vercelV5": "#/components/schemas/UpdateVercelV5AgentDTO", "ag2": "#/components/schemas/UpdateAG2AgentDTO", "rasa": "#/components/schemas/UpdateRasaAgentDTO", "agno": "#/components/schemas/UpdateAgnoAgentDTO", "ag-ui": "#/components/schemas/UpdateAGUIAgentDTO" } }, "oneOf": [ { "$ref": "#/components/schemas/UpdateMastraAgentDTO" }, { "$ref": "#/components/schemas/UpdateMastraLegacyAgentDTO" }, { "$ref": "#/components/schemas/UpdateLangGraphAgentDTO" }, { "$ref": "#/components/schemas/UpdateCrewAIAgentDTO" }, { "$ref": "#/components/schemas/UpdateVercelV5AgentDTO" }, { "$ref": "#/components/schemas/UpdateAG2AgentDTO" }, { "$ref": "#/components/schemas/UpdateRasaAgentDTO" }, { "$ref": "#/components/schemas/UpdateAgnoAgentDTO" }, { "$ref": "#/components/schemas/UpdateAGUIAgentDTO" } ] }, "UpdateMastraAgentDTO": { "title": "Mastra", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "mastra" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "Mastra-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Mastra agent is hosted", "example": "https://my-mastra-app.example.com" }, "agentId": { "type": "string", "description": "Mastra Agent ID", "example": "weatherAgent" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateMastraLegacyAgentDTO": { "title": "Mastra (Legacy)", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "mastra-legacy" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "Mastra (Legacy) configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Mastra agent is hosted", "example": "https://my-mastra-legacy.example.com" }, "agentId": { "type": "string", "description": "Mastra Agent ID", "example": "weatherAgent" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateLangGraphAgentDTO": { "title": "LangGraph", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "langgraph" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "LangGraph-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your agent is hosted", "example": "https://my-langgraph-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateCrewAIAgentDTO": { "title": "CrewAI", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "crewai" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "CrewAI compatible agent configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your CrewAI agent is hosted", "example": "https://my-crewai-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateVercelV5AgentDTO": { "title": "Vercel AI V5", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "vercelV5" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "Vercel AI V5 configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Vercel AI agent is hosted", "example": "https://my-vercel-app.vercel.app/api/chat" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Bearer token123" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateAG2AgentDTO": { "title": "AG2", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "ag2" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "AG2-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your AG2 agent is hosted", "example": "https://my-ag2-app.example.com" }, "defaultUserId": { "type": "string", "description": "Default User ID", "example": "user_123" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line. Should be valid JSON", "example": "{\"authorization\": \"Bearer token123\"}" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateRasaAgentDTO": { "title": "Rasa", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "rasa" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "Rasa-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Rasa agent is hosted", "example": "https://my-rasa-app.example.com" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateAgnoAgentDTO": { "title": "Agno", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "agno" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "Agno-specific configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your Agno agent is hosted", "example": "https://my-agno-app.example.com" }, "agentId": { "type": "string", "description": "Agno Agent ID", "example": "my-agent-id" }, "headers": { "type": "string", "description": "Headers as key:value pairs, each on a new line" } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "UpdateAGUIAgentDTO": { "title": "AG-UI", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "format": "url", "description": "URL to the icon/avatar of the agent" }, "isActive": { "type": "boolean", "default": true, "description": "Whether the agent is active" }, "integrateWith": { "type": "string", "enum": [ "ag-ui" ], "description": "Integration platform identifier" }, "integrationType": { "type": "string", "enum": [ "agent" ], "description": "Type of connection" }, "integrationMeta": { "type": "object", "description": "AG-UI compatible agent configuration", "properties": { "baseUrl": { "type": "string", "description": "The web address where your AG-UI agent is hosted", "example": "https://my-agui-app.example.com" }, "headers": { "type": "object", "description": "Custom headers as JSON object (e.g., authorization tokens)", "example": { "authorization": "Basic your_basic_auth" } } } }, "tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool names (must exist in the app's tools)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "List of action names (must exist in the app's actions)" }, "metaData": { "type": "object", "description": "Metadata for the agent", "properties": { "greetingMessage": { "type": "string", "description": "Greeting message shown when a conversation starts" }, "introductoryMessage": { "type": "string", "description": "Introductory message for the agent" }, "suggestedMessages": { "type": "array", "items": { "type": "string" }, "description": "Quick prompts users can click to start a conversation" } } } } }, "CreateTagDto": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "style": { "type": "object" } }, "required": [ "id", "text", "style" ] }, "UpdateTagDto": { "type": "object", "properties": { "text": { "type": "string" }, "style": { "type": "object" } }, "required": [ "text", "style" ] }, "ToolDto": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Display name shown in the UI for this tool", "example": "Get Weather" }, "description": { "type": "string", "description": "Description of what the tool does. Required when doNotExecute is false.", "example": "Fetches current weather data for a given location" }, "executionText": { "type": "string", "description": "Text displayed while the tool is executing", "example": "Fetching weather data..." }, "name": { "type": "string", "description": "Unique function name for the tool. Must start with a letter, underscore, or dollar sign, followed by alphanumeric characters, underscores, dollar signs, or hyphens.", "pattern": "^[a-zA-Z_$][a-zA-Z0-9_$-]*$", "example": "get_weather" }, "doNotExecute": { "type": "boolean", "description": "When true, the tool will not be executed locally and parameters/description become optional", "default": false }, "parameters": { "description": "Tool parameter definitions. Required when doNotExecute is false, but can be an empty object. Must be empty or omitted when doNotExecute is true.", "allOf": [ { "$ref": "#/components/schemas/ParametersDto" } ] } }, "required": [ "displayName", "executionText", "name" ] }, "MessageEventDTO": { "type": "object", "properties": {} }, "CreateCometChatAgentDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "description": "URL to the icon/avatar of the agent" }, "description": { "type": "string", "description": "Description of the agent" }, "tools": { "description": "Array of tool names available to this agent", "type": "array", "items": { "type": "string" } }, "apiTools": { "description": "Array of API tool names available to this agent", "type": "array", "items": { "type": "string" } }, "mcpServers": { "description": "Array of MCP server names available to this agent", "type": "array", "items": { "type": "string" } }, "instruction": { "type": "string", "description": "Instructions for the agent behavior" }, "metaData": { "type": "object", "description": "Additional metadata for the agent" }, "model": { "type": "string", "description": "AI model to use for this agent", "default": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "description": "Configuration metadata for the AI model", "properties": { "temperature": { "type": "number", "description": "Controls randomness in responses. Lower values make output more focused and deterministic.", "example": 0.7 }, "maxTokens": { "type": "number", "description": "Maximum number of tokens to generate in the response.", "example": 4096 } }, "additionalProperties": true }, "isActive": { "type": "boolean", "default": true, "description": "Is the agent active?" } }, "required": [ "name" ] }, "UpdateCometChatAgentDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the agent" }, "icon": { "type": "string", "description": "URL to the icon/avatar of the agent" }, "description": { "type": "string", "description": "Description of the agent" }, "tools": { "description": "Array of tool names available to this agent", "type": "array", "items": { "type": "string" } }, "apiTools": { "description": "Array of API tool names available to this agent", "type": "array", "items": { "type": "string" } }, "mcpServers": { "description": "Array of MCP server names available to this agent", "type": "array", "items": { "type": "string" } }, "instruction": { "type": "string", "description": "Instructions for the agent behavior" }, "metaData": { "type": "object", "description": "Additional metadata for the agent" }, "model": { "type": "string", "description": "AI model to use for this agent", "default": "gpt-4o-mini" }, "modelMetaData": { "type": "object", "description": "Configuration metadata for the AI model", "properties": { "temperature": { "type": "number", "description": "Controls randomness in responses. Lower values make output more focused and deterministic.", "example": 0.7 }, "maxTokens": { "type": "number", "description": "Maximum number of tokens to generate in the response.", "example": 4096 } }, "additionalProperties": true }, "isActive": { "type": "boolean", "default": true, "description": "Is the agent active?" } } }, "ManageAgentToolsDto": { "type": "object", "properties": { "tools": { "description": "Array of tool names to add or remove", "example": [ "gmail", "google-sheets", "slack" ], "type": "array", "items": { "type": "string" } } }, "required": [ "tools" ] }, "ManageAgentMcpDto": { "type": "object", "properties": { "mcps": { "description": "Array of MCP server slugs to add or remove", "example": [ "filesystem", "git", "postgres" ], "type": "array", "items": { "type": "string" } } }, "required": [ "mcps" ] }, "ManageAgentApiToolsDto": { "type": "object", "properties": { "apiTools": { "description": "Array of API tool slugs to add or remove", "example": [ "get_weather", "send_email", "create_task" ], "type": "array", "items": { "type": "string" } } }, "required": [ "apiTools" ] }, "ManageAgentFrontendActionsDto": { "type": "object", "properties": { "frontendActions": { "description": "Array of frontend action function names to add or remove", "example": [ "openProduct_modal", "showNotification" ], "type": "array", "items": { "type": "string" } } }, "required": [ "frontendActions" ] }, "ManageKnowledgeBaseFilesDto": { "type": "object", "properties": { "uniqueIds": { "description": "Array of file IDs to be added to the knowledge base", "example": [ "60f7b3b3b3b3b3b3b3b3b3b3", "60f7b3b3b3b3b3b3b3b3b3b4" ], "type": "array", "items": { "type": "string" } } }, "required": [ "uniqueIds" ] }, "ManageActionsDto": { "type": "object", "properties": { "actions": { "description": "Array of action names to add or remove", "example": [ "send-email", "draft-email", "read-emails" ], "type": "array", "items": { "type": "string" } } }, "required": [ "actions" ] }, "CreateCustomVariableDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique variable name. Must start with a letter and contain only alphanumeric characters, underscores, and dots.", "maxLength": 50, "pattern": "^[a-zA-Z][a-zA-Z0-9_.]*$", "example": "user.preferred_language" }, "description": { "type": "string", "description": "Human-readable description of the variable", "maxLength": 200, "example": "The preferred language of the user" }, "sourceType": { "type": "string", "description": "Source from which the variable value is resolved", "enum": [ "message_metadata", "user_metadata", "constant" ], "example": "user_metadata" }, "sourcePath": { "type": "string", "description": "Dot-notation path to extract the value from the source metadata", "maxLength": 100, "example": "language" }, "constantValue": { "type": "string", "description": "Fixed value used when sourceType is constant", "maxLength": 500, "example": "en" }, "defaultValue": { "type": "string", "description": "Fallback value used when the source path does not resolve", "maxLength": 200, "example": "en" } }, "required": [ "name", "sourceType" ] }, "UpdateCustomVariableDto": { "type": "object", "properties": { "description": { "type": "string", "description": "Human-readable description of the variable", "maxLength": 200, "example": "The preferred language of the user" }, "sourceType": { "type": "string", "description": "Source from which the variable value is resolved", "enum": [ "message_metadata", "user_metadata", "constant" ], "example": "user_metadata" }, "sourcePath": { "type": "string", "description": "Dot-notation path to extract the value from the source metadata", "maxLength": 100, "example": "language" }, "constantValue": { "type": "string", "description": "Fixed value used when sourceType is constant", "maxLength": 500, "example": "en" }, "defaultValue": { "type": "string", "description": "Fallback value used when the source path does not resolve", "maxLength": 200, "example": "en" } } }, "TestVariableResolutionDto": { "type": "object", "properties": {} }, "ApiToolSampleContextDto": { "type": "object", "properties": { "senderUid": { "type": "string", "description": "Sender user ID", "example": "user123" }, "senderRole": { "type": "string", "description": "Sender role", "example": "default" }, "senderMetadata": { "type": "object", "description": "Sender metadata object", "example": { "department": "engineering", "level": "senior" } }, "receiverUid": { "type": "string", "description": "Receiver user ID (defaults to agent ID)", "example": "agent456" }, "messageMetadata": { "type": "object", "description": "Message metadata object", "example": { "priority": "high", "source": "web" } } }, "required": [ "senderUid" ] }, "TestApiToolVariablesDto": { "type": "object", "properties": { "sampleContext": { "description": "Sample context for variable resolution", "allOf": [ { "$ref": "#/components/schemas/ApiToolSampleContextDto" } ] }, "sampleQueryParams": { "type": "object", "description": "Sample query parameters to test resolution", "example": { "userId": "[{variable-auth: \"sender.uid\"}]", "limit": "10" } } }, "required": [ "sampleContext" ] }, "ApiToolParameter": { "type": "object", "properties": { "key": { "type": "string", "description": "Parameter key/name", "example": "email" }, "type": { "type": "string", "description": "Parameter type", "example": "string" }, "description": { "type": "string", "description": "Parameter description", "example": "Email of the lead" }, "required": { "type": "boolean", "description": "Whether the parameter is required", "example": false } }, "required": [ "key", "type", "description" ] }, "CreateApiToolDto": { "type": "object", "properties": { "slug": { "type": "string", "description": "Slug for the API tool (unique)", "example": "create_lead" }, "description": { "type": "string", "description": "Description of the API tool", "example": "When to use, preconditions, what it returns" }, "endpoint": { "type": "string", "description": "API endpoint URL", "example": "https://api.example.com/leads" }, "method": { "type": "string", "description": "HTTP method", "example": "POST", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "enableBasicAuth": { "type": "boolean", "description": "Whether to enable basic authentication", "example": true }, "basicAuthUsername": { "type": "string", "description": "Basic auth username (required if enableBasicAuth is true)", "example": "username" }, "basicAuthPassword": { "type": "string", "description": "Basic auth password (required if enableBasicAuth is true)", "example": "password" }, "headers": { "type": "string", "description": "HTTP headers as a JSON string (e.g., '{\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer token\"}')", "example": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer token\"}" }, "bodyTemplate": { "type": "string", "description": "Body template for the API request", "example": "{\"name\": \"{{name}}\", \"email\": \"{{email}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "description": "Whether to allow additional properties", "example": false, "default": false }, "parameters": { "description": "Array of parameters for the API tool", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Parameter key/name", "example": "email" }, "type": { "type": "string", "description": "Parameter type", "example": "string" }, "description": { "type": "string", "description": "Parameter description", "example": "Email of the lead" }, "required": { "type": "boolean", "description": "Whether the parameter is required", "example": false } }, "required": [ "key", "type", "description" ] } }, "icon": { "type": "string", "description": "Icon for the API Tool", "example": "http://localhost:3001" }, "name": { "type": "string", "description": "Name of the API tool", "example": "Create Lead" } }, "required": [ "slug", "description", "endpoint", "method", "enableBasicAuth", "name" ] }, "UpdateApiToolDto": { "type": "object", "properties": { "slug": { "type": "string", "description": "Slug for the API tool (unique)", "example": "create_lead" }, "description": { "type": "string", "description": "Description of the API tool", "example": "When to use, preconditions, what it returns" }, "endpoint": { "type": "string", "description": "API endpoint URL", "example": "https://api.example.com/leads" }, "method": { "type": "string", "description": "HTTP method", "example": "POST", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "enableBasicAuth": { "type": "boolean", "description": "Whether to enable basic authentication", "example": true }, "basicAuthUsername": { "type": "string", "description": "Basic auth username (required if enableBasicAuth is true)", "example": "username" }, "basicAuthPassword": { "type": "string", "description": "Basic auth password (required if enableBasicAuth is true)", "example": "password" }, "headers": { "type": "string", "description": "HTTP headers as a JSON string (e.g., '{\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer token\"}')", "example": "{\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer token\"}" }, "bodyTemplate": { "type": "string", "description": "Body template for the API request", "example": "{\"name\": \"{{name}}\", \"email\": \"{{email}}\"}" }, "allowAdditionalProperties": { "type": "boolean", "description": "Whether to allow additional properties", "example": false, "default": false }, "parameters": { "description": "Array of parameters for the API tool", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Parameter key/name", "example": "email" }, "type": { "type": "string", "description": "Parameter type", "example": "string" }, "description": { "type": "string", "description": "Parameter description", "example": "Email of the lead" }, "required": { "type": "boolean", "description": "Whether the parameter is required", "example": false } }, "required": [ "key", "type", "description" ] } }, "icon": { "type": "string", "description": "Icon for the API Tool", "example": "http://localhost:3001" } } }, "CreateMcpServerDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the MCP server (human readable)", "example": "Weather Server" }, "slug": { "type": "string", "description": "Slug of the MCP server (unique, URL-safe)", "example": "weather-server" }, "description": { "type": "string", "description": "Description of the MCP server", "example": "Provides weather data for cities" }, "url": { "type": "string", "description": "URL of the MCP server", "example": "http://localhost:3001" }, "icon": { "type": "string", "description": "Icon for the MCP server", "example": "http://localhost:3001/icon.png" } }, "required": [ "name", "slug", "url" ] }, "UpdateMcpServerDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name of the MCP server (human readable)", "example": "Weather Server" }, "description": { "type": "string", "description": "Updated description of the MCP server", "example": "Provides weather data for cities" }, "url": { "type": "string", "description": "Updated URL of the MCP server", "example": "http://localhost:3002" }, "icon": { "type": "string", "description": "Updated icon for the MCP server", "example": "http://localhost:3002/icon.png" } } }, "FrontendActionParameter": { "type": "object", "properties": { "key": { "type": "string", "description": "Parameter key/name", "example": "productId" }, "type": { "type": "string", "description": "Parameter type", "example": "string" }, "description": { "type": "string", "description": "Parameter description", "example": "The ID of the product to display" }, "required": { "type": "boolean", "description": "Whether the parameter is required", "example": true } }, "required": [ "key", "type", "description" ] }, "CreateFrontendActionDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the frontend action", "example": "Open Product Modal" }, "description": { "type": "string", "description": "Description of what the frontend action does", "example": "Opens a modal displaying product details for the specified product ID" }, "triggerFunction": { "type": "string", "description": "The function name that the frontend will execute (used as unique identifier)", "example": "showProductModal" }, "parameters": { "description": "Array of parameters for the frontend action", "type": "array", "items": { "$ref": "#/components/schemas/FrontendActionParameter" } }, "icon": { "type": "string", "description": "Icon URL for the frontend action", "example": "https://example.com/icon.png" } }, "required": [ "name", "description", "triggerFunction" ] }, "UpdateFrontendActionDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the frontend action", "example": "Open Product Modal" }, "description": { "type": "string", "description": "Description of what the frontend action does", "example": "Opens a modal displaying product details" }, "parameters": { "description": "Array of parameters for the frontend action", "type": "array", "items": { "$ref": "#/components/schemas/FrontendActionParameter" } }, "icon": { "type": "string", "description": "Icon URL for the frontend action", "example": "https://example.com/icon.png" } } }, "FileDescriptorDto": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Name of the file", "example": "document.pdf" }, "mimeType": { "type": "string", "description": "MIME type of the file", "example": "application/pdf" }, "fileSize": { "type": "number", "description": "Size of the file in bytes", "example": 1024000 } }, "required": [ "fileName", "mimeType", "fileSize" ] }, "InitiateUploadDto": { "type": "object", "properties": { "files": { "description": "List of files to upload", "type": "array", "items": { "$ref": "#/components/schemas/FileDescriptorDto" } } }, "required": [ "files" ] }, "CreateTextDetailDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the text content", "example": "Company Policy Document", "maxLength": 500 }, "text": { "type": "string", "description": "Text content to be processed", "example": "This document outlines the company policies and procedures...", "maxLength": 5000 } }, "required": [ "title", "text" ] }, "UpdateTextDetailDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the text content", "example": "Updated Company Policy Document", "maxLength": 500 }, "text": { "type": "string", "description": "Text content to be processed", "example": "This is the updated document content with new policies and procedures...", "maxLength": 5000 } } }, "StatusQueryDto": { "type": "object", "properties": { "uniqueId": { "description": "Array of unique IDs to query", "example": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1" ], "type": "array", "items": { "type": "string" } } }, "required": [ "uniqueId" ] }, "ScrapePagesDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Target website URL to crawl", "example": "https://docs.example.com" }, "maxDepth": { "type": "number", "description": "Maximum depth to crawl from the starting URL", "minimum": 1, "maximum": 10, "default": 3, "example": 5 }, "maxPages": { "type": "number", "description": "Maximum number of pages to crawl", "minimum": 1, "maximum": 10000, "default": 100, "example": 500 }, "include": { "description": "URL patterns to include in crawling (substring matching)", "example": [ "docs/", "api/", "guides/" ], "type": "array", "items": { "type": "string" } }, "exclude": { "description": "URL patterns to exclude from crawling (substring matching)", "example": [ "login", "signup", "admin", "privacy" ], "type": "array", "items": { "type": "string" } }, "fetchSitemap": { "type": "boolean", "description": "Fetch and return sitemap URLs from the website", "default": false, "example": true } }, "required": [ "url" ] }, "ScrapeIndividualPageDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Target page URL to crawl and extract content from", "example": "https://docs.example.com/getting-started" }, "timeout": { "type": "number", "description": "Request timeout in milliseconds", "minimum": 5000, "maximum": 120000, "default": 30000, "example": 30000 }, "format": { "type": "string", "description": "Extract content in specific format", "enum": [ "markdown", "html", "text" ], "default": "markdown", "example": "markdown" } }, "required": [ "url" ] }, "ProcessDiscoveredUrlsDto": { "type": "object", "properties": { "exclude": { "description": "Array of unique IDs to exclude from crawling", "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "exclude" ] }, "DiscoveredUrlsStatusQueryDto": { "type": "object", "properties": { "uniqueId": { "description": "Array of discovered URL unique IDs to query status for", "example": [ "fb45bb1e-bc81-45a8-85be-36b2aa4f289e", "c2847dcd-636c-4e7a-9217-593ccf2a7bb1" ], "type": "array", "items": { "type": "string" } } }, "required": [ "uniqueId" ] }, "SyncDiscoveredUrlsDto": { "type": "object", "properties": { "uniqueIds": { "description": "Array of unique IDs to sync for batch processing", "example": [ "url-id-1", "url-id-2", "url-id-3" ], "type": "array", "items": { "type": "string" } } }, "required": [ "uniqueIds" ] }, "FormFieldDto": { "type": "object", "properties": { "label": { "type": "string", "description": "Field label" }, "required": { "type": "boolean", "description": "Whether field is required" }, "type": { "type": "string", "description": "Field type (text, url, boolean, dropdown, toggles)" }, "keyInPayload": { "type": "string", "description": "Key to use in payload" }, "keyInData": { "type": "string", "description": "Key to use in data" }, "hidden": { "type": "boolean", "description": "Whether field is hidden", "default": false }, "disabled": { "type": "boolean", "description": "Whether field is disabled", "default": false }, "placeholder": { "type": "object", "description": "Placeholder text/number/object for the field" }, "tip": { "type": "object", "description": "Tip information for the field", "properties": { "title": { "type": "string", "description": "Tip title/text" }, "icon": { "type": "string", "description": "Optional tip icon" } } }, "value": { "type": "object", "description": "Default field value" }, "dynamicOptions": { "type": "object", "description": "Dynamic options configuration" } }, "required": [ "label", "required", "type" ] }, "SubmitDetailsDto": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method" }, "url": { "type": "string", "description": "Submit URL" }, "Authorization": { "type": "string", "description": "Authorization header" }, "redirectPath": { "type": "string", "description": "Redirect path after submit" } }, "required": [ "method", "url" ] }, "CreateFormDto": { "type": "object", "properties": { "formType": { "type": "string", "description": "Form type identifier" }, "name": { "type": "string", "description": "Form name" }, "description": { "type": "string", "description": "Form description" }, "fields": { "description": "Form fields", "type": "array", "items": { "$ref": "#/components/schemas/FormFieldDto" } }, "submitDetails": { "description": "Submit configuration", "allOf": [ { "$ref": "#/components/schemas/SubmitDetailsDto" } ] }, "isActive": { "type": "boolean", "description": "Whether form is active", "default": true }, "version": { "type": "string", "description": "Form version" } }, "required": [ "formType", "name", "fields", "submitDetails" ] }, "UpdateFormDto": { "type": "object", "properties": { "formType": { "type": "string", "description": "Form type identifier" }, "name": { "type": "string", "description": "Form name" }, "description": { "type": "string", "description": "Form description" }, "fields": { "description": "Form fields", "type": "array", "items": { "$ref": "#/components/schemas/FormFieldDto" } }, "submitDetails": { "description": "Submit configuration", "allOf": [ { "$ref": "#/components/schemas/SubmitDetailsDto" } ] }, "isActive": { "type": "boolean", "description": "Whether form is active", "default": true }, "version": { "type": "string", "description": "Form version" } } }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400, "description": "HTTP status code" }, "message": { "type": "string", "example": "Validation failed", "description": "Error message" }, "error": { "type": "string", "example": "Bad Request", "description": "Error type" } }, "required": [ "statusCode", "message", "error" ] }, "SuccessBooleanResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Indicates whether the operation was successful" } }, "required": [ "success" ] }, "SuccessMessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Indicates whether the operation was successful" }, "message": { "type": "string", "example": "Operation completed successfully", "description": "Human-readable result message" } }, "required": [ "success", "message" ] }, "ParametersDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "description": "The type of the parameters object", "example": "object" }, "properties": { "type": "object", "description": "Map of parameter property names to their definitions (type and description)", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" } }, "required": [ "type", "description" ] }, "example": { "username": { "type": "string", "description": "The username" } } }, "required": { "description": "List of required parameter property names", "example": [ "username" ], "type": "array", "items": { "type": "string" } } }, "required": [ "type", "properties" ] }, "DeletedResponse": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true, "description": "Indicates whether the resource was deleted" } }, "required": [ "deleted" ] } } } }