{"openapi":"3.1.0","info":{"title":"Taqat Public API","description":"Strictly-typed REST API for managing AI agents and knowledge bases in a Taqat workspace. Designed for use by both humans and LLM agents (Claude Code, Codex). Authenticate with a workspace API key (sk_prod_*).\n\n**Recommended flow:**\n1. Call `GET /api/v1/capabilities` to discover valid model / tool / knowledge-base / embedding IDs.\n2. Create or update agents and knowledge bases using the discovered IDs.\n3. Use `POST /api/v1/knowledge-bases/search` or `POST /api/v1/knowledge-bases/:id/query` to retrieve from your KBs, or `POST /api/v1/agents/:id/text|chat|stream` to talk to your agents.","version":"1.1.0"},"servers":[{"url":"/","description":"This server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Workspace API key in the form `sk_prod_<32 hex>`. Create one in the workspace settings, then send it as `Authorization: Bearer <key>`."}}},"tags":[{"name":"Agents","description":"Agent CRUD"},{"name":"Capabilities","description":"Discovery endpoints"},{"name":"Knowledge Bases","description":"Knowledge base CRUD + content management"},{"name":"Knowledge Bases — Runtime","description":"Search, RAG query, status, embeddings, file upload"}],"paths":{"/agents":{"post":{"operationId":"postAgents","tags":["Agents"],"summary":"Create an agent","description":"Create a new agent in the API key's workspace. Use the /capabilities endpoints first to discover valid model, tool, and knowledge-base IDs.","responses":{"201":{"description":"Agent created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Server-assigned agent UUID."},"workspaceId":{"type":"string","description":"Workspace this agent belongs to."},"createdBy":{"type":"string","description":"User ID of the API key owner who created the agent."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 last-modification timestamp."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"systemPrompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"welcomeMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"agentMode":{"type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"type":"boolean"},"publishedId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public-channel ID if `published=true`, else null."},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"anyOf":[{"type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"appId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"ID of the app (solution package installation) the agent is attached to. Null if the agent is workspace-scoped without an app."},"triggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false},"description":"Registered triggers for this agent. Empty when none configured."}},"required":["id","workspaceId","createdBy","createdAt","updatedAt","name","description","systemPrompt","welcomeMessage","avatar","visibility","agentMode","published","publishedId","model","capabilities","features","workspace","appId","triggers"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Name conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the agent. Must be unique within the workspace."},"description":{"description":"Short summary of what the agent does. Shown to humans in lists.","type":"string","maxLength":2000},"systemPrompt":{"description":"System prompt that defines the agent's role and behavior. This is sent on every conversation.","type":"string"},"welcomeMessage":{"description":"First message the agent shows users when a new chat starts.","type":"string"},"avatar":{"description":"Public URL of an avatar image. Must resolve to an image asset.","type":"string","format":"uri"},"visibility":{"description":"`private` = only workspace admins and explicitly granted users. `public` = any workspace member. POST default: private.","type":"string","enum":["public","private"]},"agentMode":{"description":"Operating mode. CHAT = conversational; WORKFLOW = step-runner; ASSISTANT = single-turn helper; AUTONOMOUS = self-driven. POST default: CHAT.","type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"description":"When true, the agent is callable from public channels (web embed, API). POST default: false.","type":"boolean"},"model":{"description":"LLM provider + model + sampling parameters. Required on POST.","type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"description":"Tools and knowledge bases the agent may use.","type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"description":"Boolean feature flags. Only fields you include are applied; omitted flags retain their existing value on PATCH.","type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"description":"Sandbox / execution environment. Required for the agent to use file/shell/code tools at runtime. Omit to leave the agent sandbox-less.","type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},"appId":{"description":"App (solution package installation) to attach the agent to. Must belong to the workspace. When omitted, the agent attaches to the workspace's default app so it appears alongside UI-created agents in the standard agents list.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"triggers":{"description":"Event-driven triggers that activate the agent (e.g. new email, new Slack message). Each trigger is registered with Composio at create time.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false}}},"required":["name"],"additionalProperties":false}}}}}},"/agents/{agentId}":{"get":{"operationId":"getAgentsByAgentId","tags":["Agents"],"summary":"Get an agent","responses":{"200":{"description":"Agent detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Server-assigned agent UUID."},"workspaceId":{"type":"string","description":"Workspace this agent belongs to."},"createdBy":{"type":"string","description":"User ID of the API key owner who created the agent."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 last-modification timestamp."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"systemPrompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"welcomeMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"agentMode":{"type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"type":"boolean"},"publishedId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public-channel ID if `published=true`, else null."},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"anyOf":[{"type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"appId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"ID of the app (solution package installation) the agent is attached to. Null if the agent is workspace-scoped without an app."},"triggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false},"description":"Registered triggers for this agent. Empty when none configured."}},"required":["id","workspaceId","createdBy","createdAt","updatedAt","name","description","systemPrompt","welcomeMessage","avatar","visibility","agentMode","published","publishedId","model","capabilities","features","workspace","appId","triggers"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Agent UUID."}]},"put":{"operationId":"putAgentsByAgentId","tags":["Agents"],"summary":"Update an agent (partial body accepted)","responses":{"200":{"description":"Agent updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Server-assigned agent UUID."},"workspaceId":{"type":"string","description":"Workspace this agent belongs to."},"createdBy":{"type":"string","description":"User ID of the API key owner who created the agent."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 last-modification timestamp."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"systemPrompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"welcomeMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"agentMode":{"type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"type":"boolean"},"publishedId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public-channel ID if `published=true`, else null."},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"anyOf":[{"type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"appId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"ID of the app (solution package installation) the agent is attached to. Null if the agent is workspace-scoped without an app."},"triggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false},"description":"Registered triggers for this agent. Empty when none configured."}},"required":["id","workspaceId","createdBy","createdAt","updatedAt","name","description","systemPrompt","welcomeMessage","avatar","visibility","agentMode","published","publishedId","model","capabilities","features","workspace","appId","triggers"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Agent UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the agent. Must be unique within the workspace."},"description":{"description":"Short summary of what the agent does. Shown to humans in lists.","type":"string","maxLength":2000},"systemPrompt":{"description":"System prompt that defines the agent's role and behavior. This is sent on every conversation.","type":"string"},"welcomeMessage":{"description":"First message the agent shows users when a new chat starts.","type":"string"},"avatar":{"description":"Public URL of an avatar image. Must resolve to an image asset.","type":"string","format":"uri"},"visibility":{"description":"`private` = only workspace admins and explicitly granted users. `public` = any workspace member. POST default: private.","type":"string","enum":["public","private"]},"agentMode":{"description":"Operating mode. CHAT = conversational; WORKFLOW = step-runner; ASSISTANT = single-turn helper; AUTONOMOUS = self-driven. POST default: CHAT.","type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"description":"When true, the agent is callable from public channels (web embed, API). POST default: false.","type":"boolean"},"model":{"description":"LLM provider + model + sampling parameters. Required on POST.","type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"description":"Tools and knowledge bases the agent may use.","type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"description":"Boolean feature flags. Only fields you include are applied; omitted flags retain their existing value on PATCH.","type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"description":"Sandbox / execution environment. Required for the agent to use file/shell/code tools at runtime. Omit to leave the agent sandbox-less.","type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},"appId":{"description":"App (solution package installation) to attach the agent to. Must belong to the workspace. When omitted, the agent attaches to the workspace's default app so it appears alongside UI-created agents in the standard agents list.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"triggers":{"description":"Event-driven triggers that activate the agent (e.g. new email, new Slack message). Each trigger is registered with Composio at create time.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false}}},"additionalProperties":false}}}}},"patch":{"operationId":"patchAgentsByAgentId","tags":["Agents"],"summary":"Partially update an agent","responses":{"200":{"description":"Agent updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Server-assigned agent UUID."},"workspaceId":{"type":"string","description":"Workspace this agent belongs to."},"createdBy":{"type":"string","description":"User ID of the API key owner who created the agent."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"ISO 8601 last-modification timestamp."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"systemPrompt":{"anyOf":[{"type":"string"},{"type":"null"}]},"welcomeMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"agentMode":{"type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"type":"boolean"},"publishedId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public-channel ID if `published=true`, else null."},"model":{"type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"anyOf":[{"type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},{"type":"null"}]},"appId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"ID of the app (solution package installation) the agent is attached to. Null if the agent is workspace-scoped without an app."},"triggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false},"description":"Registered triggers for this agent. Empty when none configured."}},"required":["id","workspaceId","createdBy","createdAt","updatedAt","name","description","systemPrompt","welcomeMessage","avatar","visibility","agentMode","published","publishedId","model","capabilities","features","workspace","appId","triggers"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Agent UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the agent. Must be unique within the workspace."},"description":{"description":"Short summary of what the agent does. Shown to humans in lists.","type":"string","maxLength":2000},"systemPrompt":{"description":"System prompt that defines the agent's role and behavior. This is sent on every conversation.","type":"string"},"welcomeMessage":{"description":"First message the agent shows users when a new chat starts.","type":"string"},"avatar":{"description":"Public URL of an avatar image. Must resolve to an image asset.","type":"string","format":"uri"},"visibility":{"description":"`private` = only workspace admins and explicitly granted users. `public` = any workspace member. POST default: private.","type":"string","enum":["public","private"]},"agentMode":{"description":"Operating mode. CHAT = conversational; WORKFLOW = step-runner; ASSISTANT = single-turn helper; AUTONOMOUS = self-driven. POST default: CHAT.","type":"string","enum":["CHAT","WORKFLOW","ASSISTANT","AUTONOMOUS"]},"published":{"description":"When true, the agent is callable from public channels (web embed, API). POST default: false.","type":"boolean"},"model":{"description":"LLM provider + model + sampling parameters. Required on POST.","type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"required":["provider","model"],"additionalProperties":false},"capabilities":{"description":"Tools and knowledge bases the agent may use.","type":"object","properties":{"tools":{"description":"System tools the agent can invoke. Pass an empty array to disable all tool calling. Discover available tools via GET /api/v1/capabilities/tools.","type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system","description":"Discriminator. Use 'system' for built-in tools."},"id":{"type":"string","minLength":1,"description":"System tool ID from GET /api/v1/capabilities/tools (`kind=system` entries)."},"config":{"description":"Optional tool-specific configuration. Shape is defined by the tool's `inputSchema` from /capabilities/tools.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio","description":"Discriminator. Use 'composio' to expose a Composio toolkit's actions."},"appId":{"type":"string","minLength":1,"description":"Composio toolkit slug (e.g. 'gmail', 'slack'). Must be a connected toolkit in the workspace — list via GET /api/v1/capabilities/tools."},"actions":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"Action slugs to enable (e.g. ['gmail_send_email', 'gmail_search']). Discover via the toolkit's `actions` array in /capabilities/tools."}},"required":["kind","appId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"description":"Knowledge bases the agent can query. Pass an empty array to disable knowledge retrieval. Discover via GET /api/v1/capabilities/knowledge-bases.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Knowledge base ID from GET /api/v1/capabilities/knowledge-bases."},"access":{"default":"read","description":"Access level granted to the agent. Defaults to read-only.","type":"string","enum":["read","read-write"]}},"required":["id"],"additionalProperties":false}}},"additionalProperties":false},"features":{"description":"Boolean feature flags. Only fields you include are applied; omitted flags retain their existing value on PATCH.","type":"object","properties":{"attachments":{"description":"Allow users to attach files (images, PDFs, etc.) to messages.","type":"boolean"},"webSearch":{"description":"Enable the built-in web-search capability for this agent.","type":"boolean"},"planning":{"description":"Enable multi-step planning before tool execution.","type":"boolean"},"memory":{"description":"Persist conversation history across messages. POST default: true.","type":"boolean"},"textToSpeech":{"description":"Render assistant replies as audio in addition to text.","type":"boolean"},"followUp":{"description":"Auto-suggest follow-up prompts after each response.","type":"boolean"},"dynamicUi":{"description":"Allow the agent to render structured UI components inline.","type":"boolean"},"scheduledTasks":{"description":"Allow the agent to create / update / delete scheduled and recurring jobs.","type":"boolean"}},"additionalProperties":false},"workspace":{"description":"Sandbox / execution environment. Required for the agent to use file/shell/code tools at runtime. Omit to leave the agent sandbox-less.","type":"object","properties":{"enabled":{"default":false,"description":"Master switch. When false, the agent runs without a workspace and sandbox-bound tools won't execute.","type":"boolean"},"environment":{"default":"local","description":"Execution environment. `local` uses the server's filesystem; `docker`/`daytona`/`cloud` provision a sandbox; `browser` runs in the user's browser (no server-side execution).","type":"string","enum":["local","docker","daytona","cloud","browser"]},"capabilities":{"default":{"fileSystem":true,"shell":false,"codeExecution":false,"browser":false,"desktop":false,"readOnly":false},"description":"Per-tool-category permissions.","type":"object","properties":{"fileSystem":{"default":true,"description":"Allow read/write file tools.","type":"boolean"},"shell":{"default":false,"description":"Allow shell command execution.","type":"boolean"},"codeExecution":{"default":false,"description":"Allow arbitrary code execution (Python, JS, etc.).","type":"boolean"},"browser":{"default":false,"description":"Allow headless-browser tools.","type":"boolean"},"desktop":{"default":false,"description":"Allow desktop GUI tools (mouse, screenshot).","type":"boolean"},"readOnly":{"default":false,"description":"Force every capability to be read-only.","type":"boolean"}},"additionalProperties":false},"advanced":{"default":{"searchIndexing":false,"requireApproval":false,"operationTimeout":60},"description":"Advanced tuning knobs.","type":"object","properties":{"searchIndexing":{"default":false,"description":"Maintain a search index over the workspace files.","type":"boolean"},"requireApproval":{"default":false,"description":"Require user approval before destructive operations.","type":"boolean"},"operationTimeout":{"default":60,"description":"Per-operation timeout in seconds.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"additionalProperties":false},"appId":{"description":"App (solution package installation) to attach the agent to. Must belong to the workspace. When omitted, the agent attaches to the workspace's default app so it appears alongside UI-created agents in the standard agents list.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"triggers":{"description":"Event-driven triggers that activate the agent (e.g. new email, new Slack message). Each trigger is registered with Composio at create time.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Trigger slug, e.g. `GMAIL_NEW_GMAIL_MESSAGE`, `SLACK_RECEIVE_MESSAGE`. Look up via Composio's trigger catalog."},"name":{"type":"string","minLength":1,"description":"Display name for the trigger."},"description":{"description":"Optional human-readable description.","type":"string"},"appId":{"type":"string","minLength":1,"description":"Qualified app id, e.g. `composio.gmail`. Must match an integration on the agent's `capabilities.tools` list."},"values":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"MCP credential profile id from /capabilities/tools (the `connectionId` field on a Composio toolkit)."},"customFieldValues":{"description":"Trigger-specific configuration values. Shape depends on the trigger slug — see the Composio trigger catalog.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["connectionId"],"additionalProperties":false,"description":"Connection + per-trigger configuration."}},"required":["id","name","appId","values"],"additionalProperties":false}}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteAgentsByAgentId","tags":["Agents"],"summary":"Delete an agent","responses":{"200":{"description":"Agent deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"agentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Agent UUID."}]}},"/capabilities":{"get":{"operationId":"getCapabilities","tags":["Capabilities"],"summary":"Combined capability discovery","description":"Returns models, tools, knowledge bases, and embedding info for the API key's workspace. The IDs in the response are the values to pass when creating agents or knowledge bases.","responses":{"200":{"description":"Capabilities.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this exact value as `model.model` when creating an agent. This is the workspace's `providerModelId` from AI Configuration."},"name":{"type":"string","description":"Human-readable model display name as set in AI Configuration."},"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum. Pair with `id` in the create-agent request as `{ provider, model: id }`."},"providerConnected":{"type":"boolean","description":"True when the provider is currently connected in Settings → AI Configuration. Disconnected providers' models can't be used at runtime."},"hasReasoning":{"type":"boolean","description":"Whether the user marked this model as supporting reasoning."},"description":{"type":"string"}},"required":["id","name","provider","providerConnected","hasReasoning","description"],"additionalProperties":false}},"tools":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system"},"id":{"type":"string","description":"Pass this as `capabilities.tools[].id` with `kind: 'system'`."},"name":{"type":"string","description":"Human-readable tool name."},"description":{"type":"string","description":"What the tool does. Use this to decide whether to enable it."},"toolkitId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Toolkit namespace, e.g. 'system.code-execution'."},"inputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"JSON Schema describing the tool's input arguments."}},"required":["kind","id","name","description","toolkitId","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio"},"appId":{"type":"string","description":"Composio toolkit slug — pass as `capabilities.tools[].appId` (kind=composio)."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the toolkit's logo, if known."},"connectionId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Server-resolved connection ID. Read-only — informational only."},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action slug — pass as part of `capabilities.tools[].actions` (kind=composio)."},"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"JSON Schema describing the action's input parameters."}},"required":["id","name","description","inputSchema"],"additionalProperties":false}}},"required":["kind","appId","name","description","logo","connectionId","actions"],"additionalProperties":false}]}},"knowledgeBases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Knowledge base UUID — pass as `capabilities.knowledgeBases[].id`."},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"'knowledge' or 'datasource'."}},"required":["id","title","description","type"],"additionalProperties":false}},"embedding":{"type":"object","properties":{"model":{"type":"string","description":"Embedding model identifier."},"dimensions":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Vector dimensionality."},"maxQueryTokens":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Max input tokens per embed call."}},"required":["model","dimensions","maxQueryTokens"],"additionalProperties":false}},"required":["models","tools","knowledgeBases","embedding"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}}},"/capabilities/models":{"get":{"operationId":"getCapabilitiesModels","tags":["Capabilities"],"summary":"List available LLM models","responses":{"200":{"description":"Models.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this exact value as `model.model` when creating an agent. This is the workspace's `providerModelId` from AI Configuration."},"name":{"type":"string","description":"Human-readable model display name as set in AI Configuration."},"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum. Pair with `id` in the create-agent request as `{ provider, model: id }`."},"providerConnected":{"type":"boolean","description":"True when the provider is currently connected in Settings → AI Configuration. Disconnected providers' models can't be used at runtime."},"hasReasoning":{"type":"boolean","description":"Whether the user marked this model as supporting reasoning."},"description":{"type":"string"}},"required":["id","name","provider","providerConnected","hasReasoning","description"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/capabilities/tools":{"get":{"operationId":"getCapabilitiesTools","tags":["Capabilities"],"summary":"List available system + Composio tools","responses":{"200":{"description":"Tools.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"system"},"id":{"type":"string","description":"Pass this as `capabilities.tools[].id` with `kind: 'system'`."},"name":{"type":"string","description":"Human-readable tool name."},"description":{"type":"string","description":"What the tool does. Use this to decide whether to enable it."},"toolkitId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Toolkit namespace, e.g. 'system.code-execution'."},"inputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"JSON Schema describing the tool's input arguments."}},"required":["kind","id","name","description","toolkitId","inputSchema"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"composio"},"appId":{"type":"string","description":"Composio toolkit slug — pass as `capabilities.tools[].appId` (kind=composio)."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL of the toolkit's logo, if known."},"connectionId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Server-resolved connection ID. Read-only — informational only."},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Action slug — pass as part of `capabilities.tools[].actions` (kind=composio)."},"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"JSON Schema describing the action's input parameters."}},"required":["id","name","description","inputSchema"],"additionalProperties":false}}},"required":["kind","appId","name","description","logo","connectionId","actions"],"additionalProperties":false}]}}},"required":["data"],"additionalProperties":false}}}}}}},"/capabilities/knowledge-bases":{"get":{"operationId":"getCapabilitiesKnowledgeBases","tags":["Capabilities"],"summary":"List workspace knowledge bases (discovery only)","description":"Lightweight list of knowledge bases for use when assembling an agent's `capabilities.knowledgeBases`. For full KB CRUD see /knowledge-bases.","responses":{"200":{"description":"Knowledge bases.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Knowledge base UUID — pass as `capabilities.knowledgeBases[].id`."},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"'knowledge' or 'datasource'."}},"required":["id","title","description","type"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}}}}},"/capabilities/embedding":{"get":{"operationId":"getCapabilitiesEmbedding","tags":["Capabilities"],"summary":"Get the workspace embedding model info","description":"Returns the embedding model, vector dimensionality, and max query tokens used by /knowledge-bases/search and /query.","responses":{"200":{"description":"Embedding capability.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"model":{"type":"string","description":"Embedding model identifier."},"dimensions":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Vector dimensionality."},"maxQueryTokens":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Max input tokens per embed call."}},"required":["model","dimensions","maxQueryTokens"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/knowledge-bases/search":{"post":{"operationId":"postKnowledgeBasesSearch","tags":["Knowledge Bases — Runtime"],"summary":"Semantic search across all knowledge bases in the workspace","description":"Embeds the query and returns chunks ranked by cosine similarity. Use `scope.knowledgeBaseIds` to narrow the search; omit to search all KBs in the workspace.","responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null when `includeContent=false`."},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Cosine similarity (1 = identical)."},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["chunkId","knowledgeBaseId","knowledgeBaseTitle","contentId","content","similarity","metadata"],"additionalProperties":false}},"usage":{"type":"object","properties":{"embeddingTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"model":{"type":"string","description":"Embedding model used for this query."}},"required":["embeddingTokens","model"],"additionalProperties":false}},"required":["query","results","usage"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2048,"description":"Natural-language query to embed."},"scope":{"type":"object","properties":{"knowledgeBaseIds":{"description":"Optional subset of KB IDs to search. Ignored on /:id/search (scope is implied by the URL).","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"additionalProperties":false},"options":{"type":"object","properties":{"topK":{"default":10,"description":"Max number of chunks to return.","type":"integer","minimum":1,"maximum":50},"minSimilarity":{"default":0.5,"description":"Cosine-similarity floor; lower values include weaker matches.","type":"number","minimum":0,"maximum":1},"includeContent":{"default":true,"description":"Whether to return chunk text. Disable for ID-only listings.","type":"boolean"},"includeMetadata":{"default":true,"type":"boolean"}},"additionalProperties":false}},"required":["query"],"additionalProperties":false}}}}}},"/knowledge-bases/{knowledgeBaseId}/search":{"post":{"operationId":"postKnowledgeBasesByKnowledgeBaseIdSearch","tags":["Knowledge Bases — Runtime"],"summary":"Semantic search inside a single knowledge base","responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseTitle":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Null when `includeContent=false`."},"similarity":{"type":"number","minimum":0,"maximum":1,"description":"Cosine similarity (1 = identical)."},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["chunkId","knowledgeBaseId","knowledgeBaseTitle","contentId","content","similarity","metadata"],"additionalProperties":false}},"usage":{"type":"object","properties":{"embeddingTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"model":{"type":"string","description":"Embedding model used for this query."}},"required":["embeddingTokens","model"],"additionalProperties":false}},"required":["query","results","usage"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":2048,"description":"Natural-language query to embed."},"scope":{"type":"object","properties":{"knowledgeBaseIds":{"description":"Optional subset of KB IDs to search. Ignored on /:id/search (scope is implied by the URL).","type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"additionalProperties":false},"options":{"type":"object","properties":{"topK":{"default":10,"description":"Max number of chunks to return.","type":"integer","minimum":1,"maximum":50},"minSimilarity":{"default":0.5,"description":"Cosine-similarity floor; lower values include weaker matches.","type":"number","minimum":0,"maximum":1},"includeContent":{"default":true,"description":"Whether to return chunk text. Disable for ID-only listings.","type":"boolean"},"includeMetadata":{"default":true,"type":"boolean"}},"additionalProperties":false}},"required":["query"],"additionalProperties":false}}}}}},"/knowledge-bases/{knowledgeBaseId}/query":{"post":{"operationId":"postKnowledgeBasesByKnowledgeBaseIdQuery","tags":["Knowledge Bases — Runtime"],"summary":"Ask a question (RAG)","description":"Searches the knowledge base, then asks an LLM to synthesize an answer with `[N]`-style citation markers. Returns the answer plus the cited chunks.","responses":{"200":{"description":"Synthesized answer with citations.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"answer":{"type":"string","description":"Synthesized natural-language answer. May contain `[1]`-style citation markers."},"citations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Citation index referenced in `answer`."},"chunkId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"content":{"type":"string"},"similarity":{"type":"number","minimum":0,"maximum":1},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]}},"required":["id","chunkId","knowledgeBaseId","content","similarity","metadata"],"additionalProperties":false}},"usage":{"type":"object","properties":{"embeddingTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"promptTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"completionTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalTokens":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["embeddingTokens","promptTokens","completionTokens","totalTokens"],"additionalProperties":false}},"required":["answer","citations","usage"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":2048,"description":"Natural-language question."},"options":{"type":"object","properties":{"topK":{"default":6,"type":"integer","minimum":1,"maximum":20},"minSimilarity":{"default":0.5,"type":"number","minimum":0,"maximum":1},"model":{"description":"Override workspace default model. When omitted, the workspace's default model is used.","type":"object","properties":{"provider":{"type":"string","enum":["OPENAI","ANTHROPIC","GROQ","OPEN_ROUTER","DEEPSEEK","CODEX","ZAI","OLLAMA","LM_STUDIO","CLAUDE_CODE","CUSTOM"],"description":"Provider enum matching workspace AI Configuration. Must be one of the providers connected in Settings → AI Configuration. Case-sensitive."},"model":{"type":"string","minLength":1,"description":"Model identifier exactly as listed in GET /api/v1/capabilities/models (the `id` field). Only models added under a connected provider in Settings → AI Configuration are valid."},"temperature":{"description":"Sampling temperature. 0 = deterministic, 2 = highly random. Defaults to 0.5 when omitted.","type":"number","minimum":0,"maximum":2},"maxTokens":{"description":"Maximum tokens to generate per response. Defaults to 150 when omitted.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"topP":{"description":"Nucleus sampling probability mass. Defaults to 1.","type":"number","minimum":0,"maximum":1},"frequencyPenalty":{"description":"Penalty applied to repeated tokens. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2},"presencePenalty":{"description":"Penalty applied to tokens already seen. Range -2..2. Defaults to 0.","type":"number","minimum":-2,"maximum":2}},"additionalProperties":false},"maxAnswerTokens":{"default":500,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"additionalProperties":false}},"required":["question"],"additionalProperties":false}}}}}},"/knowledge-bases/{knowledgeBaseId}/status":{"get":{"operationId":"getKnowledgeBasesByKnowledgeBaseIdStatus","tags":["Knowledge Bases — Runtime"],"summary":"Ingestion status","description":"Per-content-row status. Currently embedding is synchronous — every content row is either `ready` (has embeddings) or `failed` (has no embeddings).","responses":{"200":{"description":"Status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"counts":{"type":"object","properties":{"ready":{"type":"integer","minimum":0,"maximum":9007199254740991},"queued":{"type":"integer","minimum":0,"maximum":9007199254740991},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["ready","queued","failed","total"],"additionalProperties":false},"isReady":{"type":"boolean","description":"True when every content row has finished embedding successfully."}},"required":["knowledgeBaseId","counts","isReady"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}]}},"/knowledge-bases/{knowledgeBaseId}/embeddings":{"get":{"operationId":"getKnowledgeBasesByKnowledgeBaseIdEmbeddings","tags":["Knowledge Bases — Runtime"],"summary":"List embeddings (chunks) for a knowledge base","description":"Returns stored chunks with their metadata. Raw 1536-dim vectors are only included when `?includeVector=true`.","responses":{"200":{"description":"Chunks.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"embeddings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"content":{"type":"string"},"metadata":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"vector":{"description":"Present only when `?includeVector=true`.","type":"array","items":{"type":"number"}}},"required":["id","knowledgeBaseId","contentId","content","metadata","createdAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["knowledgeBaseId","embeddings","pagination"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."},{"in":"query","name":"limit","schema":{"default":100,"type":"integer","exclusiveMinimum":0,"maximum":500}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},{"in":"query","name":"includeVector","schema":{"default":false,"type":"boolean"},"description":"Include raw 1536-dim vectors. Bloats responses; default false."}]}},"/knowledge-bases/{knowledgeBaseId}/files":{"post":{"operationId":"postKnowledgeBasesByKnowledgeBaseIdFiles","tags":["Knowledge Bases — Runtime"],"summary":"Upload a file to a knowledge base","description":"Accepts a single file as multipart/form-data under field `file`. Embedding is synchronous; the response includes the new content row's id and `status: ready` on success.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"File ingested.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contentId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"fileName":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["queued","ready","failed"],"description":"`queued` immediately after upload; promoted to `ready` (or `failed`) once embeddings finish."}},"required":["contentId","knowledgeBaseId","fileName","mimeType","sizeBytes","status"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}]}},"/knowledge-bases":{"get":{"operationId":"getKnowledgeBases","tags":["Knowledge Bases"],"summary":"List knowledge bases","description":"List knowledge bases in the API key's workspace. Supports pagination, search, type filtering, and sort.","responses":{"200":{"description":"Paginated knowledge base list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"knowledgeBases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workspaceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"`knowledge` or `datasource` (internal column value)."},"createdBy":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"contentSize":{"anyOf":[{"type":"object","properties":{"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"formatted":{"type":"string","description":"Human-friendly size, e.g. '4.2 KB'."},"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"chunks":{"type":"integer","minimum":0,"maximum":9007199254740991},"fileCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"webPageCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["bytes","formatted","wordCount","chunks","fileCount","webPageCount"],"additionalProperties":false},{"type":"null"}]}},"required":["id","workspaceId","title","description","type","createdBy","createdAt","updatedAt","contentSize"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"page":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"totalPages":{"type":"integer","minimum":0,"maximum":9007199254740991},"hasNextPage":{"type":"boolean"},"hasPrevPage":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasNextPage","hasPrevPage"],"additionalProperties":false}},"required":["knowledgeBases","pagination"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"query","name":"page","schema":{"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"in":"query","name":"limit","schema":{"default":20,"type":"integer","exclusiveMinimum":0,"maximum":100}},{"in":"query","name":"q","schema":{"type":"string"},"description":"Search title / description (case-insensitive)."},{"in":"query","name":"type","schema":{"type":"string"},"description":"Filter by knowledge type."},{"in":"query","name":"createdBy","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"in":"query","name":"from","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"description":"ISO 8601 — include rows created on/after."},{"in":"query","name":"to","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"description":"ISO 8601 — include rows created on/before."},{"in":"query","name":"sort","schema":{"default":"createdAt:desc","type":"string"},"description":"`field:direction` — e.g. `title:asc`."}]},"post":{"operationId":"postKnowledgeBases","tags":["Knowledge Bases"],"summary":"Create a knowledge base","description":"Create a knowledge base. The request body is discriminated by `type`. `text` and `website` embed content synchronously; `files` creates an empty shell — attach files via POST /:knowledgeBaseId/files.","responses":{"201":{"description":"Knowledge base created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workspaceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"`knowledge` or `datasource` (internal column value)."},"createdBy":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"contentSize":{"anyOf":[{"type":"object","properties":{"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"formatted":{"type":"string","description":"Human-friendly size, e.g. '4.2 KB'."},"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"chunks":{"type":"integer","minimum":0,"maximum":9007199254740991},"fileCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"webPageCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["bytes","formatted","wordCount","chunks","fileCount","webPageCount"],"additionalProperties":false},{"type":"null"}]}},"required":["id","workspaceId","title","description","type","createdBy","createdAt","updatedAt","contentSize"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text","description":"Plain-text content embedded inline."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the KB."},"description":{"description":"Short summary shown in lists.","type":"string","maxLength":2000},"content":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}],"description":"Text to ingest. Single string or array of strings; each item is chunked and embedded."}},"required":["type","title","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"website","description":"Fetch + embed one or more URLs."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the KB."},"description":{"type":"string","maxLength":2000},"urls":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uri"},"description":"URLs to crawl. Each is fetched, cleaned, chunked, and embedded."}},"required":["type","title","urls"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"files","description":"Create an empty KB; attach files via /files."},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the KB."},"description":{"type":"string","maxLength":2000}},"required":["type","title"],"additionalProperties":false}]}}}}}},"/knowledge-bases/{knowledgeBaseId}":{"get":{"operationId":"getKnowledgeBasesByKnowledgeBaseId","tags":["Knowledge Bases"],"summary":"Get knowledge base by ID","responses":{"200":{"description":"Knowledge base detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workspaceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"`knowledge` or `datasource` (internal column value)."},"createdBy":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"contentSize":{"anyOf":[{"type":"object","properties":{"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"formatted":{"type":"string","description":"Human-friendly size, e.g. '4.2 KB'."},"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"chunks":{"type":"integer","minimum":0,"maximum":9007199254740991},"fileCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"webPageCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["bytes","formatted","wordCount","chunks","fileCount","webPageCount"],"additionalProperties":false},{"type":"null"}]}},"required":["id","workspaceId","title","description","type","createdBy","createdAt","updatedAt","contentSize"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}]},"patch":{"operationId":"patchKnowledgeBasesByKnowledgeBaseId","tags":["Knowledge Bases"],"summary":"Update a knowledge base","description":"Update metadata (title / description). Optionally replace `content` (text) or `urls` (website) — previous embeddings for the replaced content are removed.","responses":{"200":{"description":"Knowledge base updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workspaceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","description":"`knowledge` or `datasource` (internal column value)."},"createdBy":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"contentSize":{"anyOf":[{"type":"object","properties":{"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"formatted":{"type":"string","description":"Human-friendly size, e.g. '4.2 KB'."},"wordCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"chunks":{"type":"integer","minimum":0,"maximum":9007199254740991},"fileCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"webPageCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["bytes","formatted","wordCount","chunks","fileCount","webPageCount"],"additionalProperties":false},{"type":"null"}]}},"required":["id","workspaceId","title","description","type","createdBy","createdAt","updatedAt","contentSize"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":2000},"content":{"description":"Replace text content. Re-embeds; previous chunks removed.","anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]},"urls":{"description":"Replace website sources.","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uri"}}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteKnowledgeBasesByKnowledgeBaseId","tags":["Knowledge Bases"],"summary":"Delete a knowledge base","description":"Cascade-delete the KB along with all content rows and embeddings.","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}]}},"/knowledge-bases/{knowledgeBaseId}/content":{"post":{"operationId":"postKnowledgeBasesByKnowledgeBaseIdContent","tags":["Knowledge Bases"],"summary":"Append content to a knowledge base","description":"Append a new content row (text or website URLs) to an existing knowledge base. Re-embeds and returns the new content IDs.","responses":{"201":{"description":"Content appended.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"knowledgeBaseId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contentIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["knowledgeBaseId","contentIds"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"content":{"anyOf":[{"type":"string","minLength":1},{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}]}},"required":["type","content"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"website"},"urls":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","format":"uri"}}},"required":["type","urls"],"additionalProperties":false}]}}}}}},"/knowledge-bases/{knowledgeBaseId}/content/{contentId}":{"delete":{"operationId":"deleteKnowledgeBasesByKnowledgeBaseIdContentByContentId","tags":["Knowledge Bases"],"summary":"Delete a single content row","description":"Remove one content row (and all of its embeddings) from a knowledge base.","responses":{"200":{"description":"Content row deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}},"parameters":[{"in":"path","name":"knowledgeBaseId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Knowledge base UUID."},{"in":"path","name":"contentId","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"required":true,"description":"Content row UUID inside the KB."}]}}}}