{ "openapi": "3.1.0", "info": { "title": "xpander.ai API Service", "description": "\n The xpander.ai API Service provides a unified REST API for managing AI agents,\n executing tasks, managing knowledge bases, and integrating with external systems.\n \n Features:\n - Agent Management: Create, update, deploy, and delete AI agents\n - Task Execution: Invoke agents with support for sync, async, and streaming modes\n - Knowledge Bases: Manage knowledge bases and documents for RAG workflows\n - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows\n - MCP Integration: Model Context Protocol support for standardized AI interactions\n \n Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer `).\n ", "version": "0.001" }, "servers": [ { "url": "https://api.xpander.ai" } ], "paths": { "/health": { "get": { "summary": "Get", "description": "Health check endpoint.\n\nReturns service health status. No authentication required.\nUsed by load balancers and monitoring systems.\n\nReturns:\n str: \"ok\" if service is healthy", "operationId": "get_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": "ok" } } } } } }, "/v1/inbound/email": { "post": { "tags": [ "Inbound Email" ], "summary": "Inbound Email Trigger", "operationId": "Inbound_email_trigger_v1_inbound_email_post", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "status": "accepted", "task_id": "f0f0f0f0-1111-2222-3333-444444444444" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/bash": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: Bash", "description": "Execute a shell command inside the agent's workspace. Supports installing packages, running scripts, and general shell operations.", "operationId": "Workspace__Bash_v1_agents__agent_id__workspace_bash_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BashRequest" }, "example": { "command": "ls -la notes" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BashResponse" }, "example": { "stdout": "total 12\n-rw-r--r--. 1 app app 19 Jul 28 21:10 demo.txt\n", "stderr": "", "exit_code": 0, "duration": 0.014168977737426758 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/file_read": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: File Read", "description": "Read a file from the agent's workspace filesystem. Supports partial reads via line ranges.", "operationId": "Workspace__File_Read_v1_agents__agent_id__workspace_file_read_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReadRequest" }, "example": { "path": "notes/demo.txt" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReadResponse" }, "example": { "content": "hello, world\nsecond line\n", "lines_count": 2, "encoding_detected": "utf-8" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/file_write": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: File Write", "description": "Write (create or overwrite) a file in the agent's workspace filesystem.", "operationId": "Workspace__File_Write_v1_agents__agent_id__workspace_file_write_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileWriteRequest" }, "example": { "path": "notes/demo.txt", "content": "hello, world\n" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileWriteResponse" }, "example": { "path": "notes/demo.txt", "bytes_written": 13, "created": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/file_edit": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: File Edit", "description": "Edit a file in the agent's workspace by replacing exact text occurrences.", "operationId": "Workspace__File_Edit_v1_agents__agent_id__workspace_file_edit_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileEditRequest" }, "example": { "path": "notes/demo.txt", "old_text": "hello, world", "new_text": "hi, world" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileEditResponse" }, "example": { "path": "notes/demo.txt", "replacements_made": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/multi_edit": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: Multi Edit", "description": "Apply multiple edits atomically to one or more files in the agent's workspace. If any edit fails, all changes are rolled back.", "operationId": "Workspace__Multi_Edit_v1_agents__agent_id__workspace_multi_edit_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiEditRequest" }, "example": { "edits": [ { "path": "notes/demo.txt", "old_text": "hello, world", "new_text": "hi, world" }, { "path": "notes/demo.txt", "old_text": "second line", "new_text": "2nd line" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiEditResponse" }, "example": { "results": [ { "path": "notes/demo.txt", "replacements_made": 1 }, { "path": "notes/demo.txt", "replacements_made": 1 } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/glob": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: Glob", "description": "Find files in the agent's workspace matching a glob pattern.", "operationId": "Workspace__Glob_v1_agents__agent_id__workspace_glob_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobRequest" }, "example": { "pattern": "**/*.txt" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobResponse" }, "example": { "matches": [ "/notes/demo.txt" ], "total_found": 1, "truncated": false } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/grep": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: Grep", "description": "Search for a regex pattern across files in the agent's workspace.", "operationId": "Workspace__Grep_v1_agents__agent_id__workspace_grep_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrepRequest" }, "example": { "pattern": "world", "include": "*.txt" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrepResponse" }, "example": { "matches": [ { "file": "/notes/demo.txt", "line": 1, "content": "hello, world", "context": "/agent/data/notes/demo.txt:1:hello, world" } ], "total_matches": 1, "files_with_matches": 1, "summary": "1 match(es) across 1 file(s) for /world/" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/workspace/file_share": { "post": { "tags": [ "API v1", "Agents", "Agents Workspace" ], "summary": "Workspace: File Share", "description": "Publish a file from the agent's workspace to a public CDN URL for sharing.", "operationId": "Workspace__File_Share_v1_agents__agent_id__workspace_file_share_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileShareRequest" }, "example": { "path": "notes/demo.txt" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileShareResponse" }, "example": { "url": "https://links.xpander.ai/a1b2c3d.txt" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/tools": { "get": { "tags": [ "API v1", "Agents", "Agent Tools" ], "summary": "List Agent Tools", "description": "List the tools attached to an agent in a simple, unified shape.", "operationId": "List_agent_tools_v1_agents__agent_id__tools_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" }, "title": "Response List Agent Tools V1 Agents Agent Id Tools Get" }, "example": [ { "id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "type": "action", "name": "Execute Search Query and Retrieve Results", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_id": "68230439d76e61ed7e92e4c3", "operation_name": "TavilySearchServiceExecuteQueryAndReturnResults" } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Agents", "Agent Tools" ], "summary": "Add Agent Tool", "description": "Attach a tool to an agent (action, custom_function, mcp, agent, workflow, or skill). The API handles all catalog resolution and graph wiring.", "operationId": "Add_agent_tool_v1_agents__agent_id__tools_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Deploy the agent after adding so the change takes effect immediately.", "default": true, "title": "Deploy" }, "description": "Deploy the agent after adding so the change takes effect immediately." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AddActionTool" }, { "$ref": "#/components/schemas/AddCustomFunctionTool" }, { "$ref": "#/components/schemas/AddMcpTool" }, { "$ref": "#/components/schemas/AddSubAgentTool" }, { "$ref": "#/components/schemas/AddWorkflowTool" }, { "$ref": "#/components/schemas/AddSkillTool" } ], "discriminator": { "propertyName": "type", "mapping": { "action": "#/components/schemas/AddActionTool", "custom_function": "#/components/schemas/AddCustomFunctionTool", "mcp": "#/components/schemas/AddMcpTool", "agent": "#/components/schemas/AddSubAgentTool", "workflow": "#/components/schemas/AddWorkflowTool", "skill": "#/components/schemas/AddSkillTool" } }, "title": "Payload" }, "example": { "type": "action", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_ids": [ "68230439d76e61ed7e92e4c3" ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" }, "title": "Response Add Agent Tool V1 Agents Agent Id Tools Post" }, "example": [ { "id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "type": "action", "name": "Execute Search Query and Retrieve Results", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_id": "68230439d76e61ed7e92e4c3", "operation_name": "TavilySearchServiceExecuteQueryAndReturnResults" } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/tools/{tool_id}": { "delete": { "tags": [ "API v1", "Agents", "Agent Tools" ], "summary": "Remove Agent Tool", "description": "Remove a tool from an agent by its tool id (the `id` from list agent tools).", "operationId": "Remove_agent_tool_v1_agents__agent_id__tools__tool_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Tool Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Deploy the agent after removing so the change takes effect immediately.", "default": true, "title": "Deploy" }, "description": "Deploy the agent after removing so the change takes effect immediately." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" }, "title": "Response Remove Agent Tool V1 Agents Agent Id Tools Tool Id Delete" }, "example": [] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/scheduled-tasks": { "get": { "tags": [ "API v1", "Agents", "Scheduled Tasks" ], "summary": "List Scheduled Tasks", "description": "List an agent's recurring scheduled tasks.", "operationId": "List_scheduled_tasks_v1_agents__agent_id__scheduled_tasks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledTask" }, "title": "Response List Scheduled Tasks V1 Agents Agent Id Scheduled Tasks Get" }, "example": [] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Agents", "Scheduled Tasks" ], "summary": "Create Scheduled Task", "description": "Create a recurring scheduled task (cron + prompt). The change takes effect immediately.", "operationId": "Create_scheduled_task_v1_agents__agent_id__scheduled_tasks_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledTaskRequest" }, "example": { "cron": "0 9 * * 1", "prompt": "Post the weekly signup summary.", "title": "Weekly signup summary" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTask" }, "example": { "id": "5b5b5b5b-6c6c-7d7d-8e8e-9f9f9f9f9f9f", "title": "Weekly signup summary", "cron": "0 9 * * 1", "prompt": "Post the weekly signup summary.", "enabled": true, "type": "scheduled-job" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/scheduled-tasks/{task_id}": { "patch": { "tags": [ "API v1", "Agents", "Scheduled Tasks" ], "summary": "Update Scheduled Task", "description": "Update a scheduled task's cron, prompt, title, or enabled state. Set enabled=false to pause without deleting.", "operationId": "Update_scheduled_task_v1_agents__agent_id__scheduled_tasks__task_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledTaskRequest" }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTask" }, "example": { "id": "5b5b5b5b-6c6c-7d7d-8e8e-9f9f9f9f9f9f", "title": "Weekly signup summary", "cron": "0 9 * * 1", "prompt": "Post the weekly signup summary.", "enabled": false, "type": "scheduled-job" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Agents", "Scheduled Tasks" ], "summary": "Delete Scheduled Task", "description": "Delete a scheduled task by its id.", "operationId": "Delete_scheduled_task_v1_agents__agent_id__scheduled_tasks__task_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "deleted": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/scheduled-tasks/{task_id}/run": { "post": { "tags": [ "API v1", "Agents", "Scheduled Tasks" ], "summary": "Run Scheduled Task Now", "description": "Fire a scheduled task immediately, regardless of its cron schedule.", "operationId": "Run_scheduled_task_now_v1_agents__agent_id__scheduled_tasks__task_id__run_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/self-schedules/settings": { "get": { "tags": [ "API v1", "Agents", "Self Schedules" ], "summary": "Get Self-Schedule Settings", "description": "Read whether the agent may schedule its own future runs, and its per-task cap.", "operationId": "Get_self_schedule_settings_v1_agents__agent_id__self_schedules_settings_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfScheduleSettings" }, "example": { "can_self_schedule": false, "max_self_schedules": 3 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "API v1", "Agents", "Self Schedules" ], "summary": "Set Self-Schedule Settings", "description": "Enable or disable the agent's self-scheduling capability (and optionally its per-task cap).", "operationId": "Set_self_schedule_settings_v1_agents__agent_id__self_schedules_settings_put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfScheduleSettings" }, "example": { "can_self_schedule": true, "max_self_schedules": 3 } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfScheduleSettings" }, "example": { "can_self_schedule": true, "max_self_schedules": 3 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/self-schedules": { "get": { "tags": [ "API v1", "Agents", "Self Schedules" ], "summary": "List Self-Schedules", "description": "List the agent's self-scheduled future runs.", "operationId": "List_self_schedules_v1_agents__agent_id__self_schedules_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status: scheduled, completed, or failed.", "title": "Status" }, "description": "Filter by status: scheduled, completed, or failed." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SelfScheduleView" }, "title": "Response List Self Schedules V1 Agents Agent Id Self Schedules Get" }, "example": [] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/self-schedules/{schedule_id}": { "delete": { "tags": [ "API v1", "Agents", "Self Schedules" ], "summary": "Cancel Self-Schedule", "description": "Cancel a pending self-scheduled run by its id.", "operationId": "Cancel_self_schedule_v1_agents__agent_id__self_schedules__schedule_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schedule Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "deleted": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents": { "get": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "List Agents (Minimal)", "description": "Retrieve a paginated list of AI agents with minimal information (ID, name, status)", "operationId": "List_agents__minimal__v1_agents_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_MinimalAIAgentWithCreatedByDetails_" }, "example": { "items": [ { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "description": "Searches the web and reports findings as JSON.", "icon": "🚀", "status": "ACTIVE", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "type": "manager", "created_at": "2026-07-28T20:55:54.042725Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "Create Ai Agent", "description": "Create a new AI agent with specified configuration, tools, and knowledge bases", "operationId": "Create_AI_Agent_v1_agents_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" }, "example": { "name": "Research Assistant", "instructions": { "role": [ "You are a web research assistant." ], "goal": [ "Search the web and report findings as JSON." ] }, "output_format": "json" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/full": { "get": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "List Agents (Full)", "description": "Retrieve a paginated list of AI agents with a simplified view (tools as one list, no low-level graph/oas).", "operationId": "List_agents__full__v1_agents_full_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_SimplifiedAIAgent_" }, "example": { "items": [ { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "description": "Searches the web and reports findings as JSON.", "icon": "🚀", "status": "ACTIVE", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "type": "manager", "created_at": "2026-07-28T20:55:54.042725Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "API v1", "Agents" ], "summary": "Get Agent", "description": "Retrieve a specific AI agent in a simplified view (tools as one list, no low-level graph/oas).", "operationId": "Get_Agent_v1_agents__agent_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimplifiedAIAgent" }, "example": { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "description": "Searches the web and reports findings as JSON.", "icon": "🚀", "status": "ACTIVE", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "type": "manager", "created_at": "2026-07-28T20:55:54.042725Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "Update Ai Agent", "description": "Update an existing AI agent's configuration, tools, or knowledge bases. Use deploy=true to apply changes immediately.", "operationId": "Update_AI_Agent_v1_agents__agent_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.", "default": false, "title": "Deploy" }, "description": "Automatically deploy the agent after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" }, "example": { "name": "Research Assistant v2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" }, "example": { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "description": "Searches the web and reports findings as JSON.", "icon": "🚀", "status": "ACTIVE", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "type": "manager", "created_at": "2026-07-28T20:55:54.042725Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "Deploy Ai Agent", "description": "Deploy an AI agent to make it active and available for task execution", "operationId": "Deploy_AI_Agent_v1_agents__agent_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" }, "example": { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "description": "Searches the web and reports findings as JSON.", "icon": "🚀", "status": "ACTIVE", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "type": "manager", "created_at": "2026-07-28T20:55:54.042725Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "Delete Ai Agent", "description": "Permanently delete an AI agent and all associated resources", "operationId": "Delete_AI_Agent_v1_agents__agent_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/invoke/async": { "post": { "tags": [ "API v1", "Agents", "Agents Invocation" ], "summary": "Invoke Agent (Async)", "description": "Invoke an AI agent asynchronously. Returns immediately with task ID for later polling.", "operationId": "Invoke_Agent__Async__v1_agents__agent_id__invoke_async_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent/workflow version to invoke. default = latest", "title": "Version" }, "description": "The agent/workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTask" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "status": "pending" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/invoke/stream": { "post": { "tags": [ "API v1", "Agents", "Agents Invocation" ], "summary": "Invoke Agent (Stream)", "description": "Invoke an AI agent with real-time streaming. Returns Server-Sent Events (SSE) for live task updates.", "operationId": "Invoke_Agent__Stream__v1_agents__agent_id__invoke_stream_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent/workflow version to invoke. default = latest", "title": "Version" }, "description": "The agent/workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "type": "connected", "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "time": "2026-07-28T21:14:22.053899+00:00" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/invoke": { "post": { "tags": [ "API v1", "Agents", "Agents Invocation" ], "summary": "Invoke Agent (Sync)", "description": "Invoke an AI agent and wait for task completion. Returns the final result.", "operationId": "Invoke_Agent__Sync__v1_agents__agent_id__invoke_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The agent/workflow version to invoke. default = latest", "title": "Version" }, "description": "The agent/workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTask" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/tasks": { "get": { "tags": [ "API v1", "Agents", "Tasks CRUD" ], "summary": "Get Agent Tasks", "description": "Retrieve paginated list of task executions for a specific agent with optional filters", "operationId": "Get_Agent_Tasks_v1_agents__agent_id__tasks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by user ID", "title": "User Id" }, "description": "Filter by user ID" }, { "name": "parent_task_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by parent task ID", "title": "Parent Task Id" }, "description": "Filter by parent task ID" }, { "name": "triggering_agent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by triggering agent ID (parent calling agent)", "title": "Triggering Agent Id" }, "description": "Filter by triggering agent ID (parent calling agent)" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AgentExecutionStatus-Input", "description": "Filter by task execution status" }, "description": "Filter by task execution status" }, { "name": "internal_status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by internal task status", "title": "Internal Status" }, "description": "Filter by internal task status" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_TasksListItem_" }, "example": { "items": [ { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "user_id": "user-123", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "title": "Summarize today's signups", "result": "42 new signups today, up 12% week over week.", "source_node_type": "api", "parent_task_id": null, "created_at": "2026-07-28T20:59:02.915959Z", "updated_at": "2026-07-28T20:59:51.661537Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/inbox": { "get": { "tags": [ "API v1", "Agents", "Agents CRUD" ], "summary": "Get Agent Inbox", "description": "List conversations that reached this agent by email or WhatsApp, newest first.", "operationId": "Get_Agent_Inbox_v1_agents__agent_id__inbox_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated channels to include (email, whatsapp). Defaults to every channel enabled on the agent.", "default": "", "title": "Source" }, "description": "Comma-separated channels to include (email, whatsapp). Defaults to every channel enabled on the agent." }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO date/datetime - only conversations created at or after it (a bare date covers the whole UTC day).", "default": "", "title": "From Date" }, "description": "ISO date/datetime - only conversations created at or after it (a bare date covers the whole UTC day)." }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "description": "ISO date/datetime - only conversations created at or before it.", "default": "", "title": "To Date" }, "description": "ISO date/datetime - only conversations created at or before it." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive text matched against conversation titles.", "default": "", "title": "Q" }, "description": "Case-insensitive text matched against conversation titles." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Max conversations to return.", "default": 20, "title": "Limit" }, "description": "Max conversations to return." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxConversationsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/export": { "post": { "tags": [ "API v1", "Agents", "Agents Import/Export" ], "summary": "Export Agent", "description": "Exports an AI agent into a reusable template with configuration and knowledge bases", "operationId": "Export_Agent_v1_agents__agent_id__export_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAgentRequest" }, "example": { "name": "Research Assistant template" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplate" }, "example": { "id": "3c3c3c3c-4d4d-5e5e-6f6f-707070707070", "name": "Research Assistant template", "description": null, "icon": "🚀", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "agent_definition": { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant", "instructions": { "role": [ "You are a web research assistant." ], "goal": [ "Search the web and report findings as JSON." ] } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/template_import/{template_id}": { "post": { "tags": [ "API v1", "Agents", "Agents Import/Export" ], "summary": "Import Agent", "description": "Imports an AI agent from a template and creates a new agent instance", "operationId": "Import_Agent_v1_agents_template_import__template_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAgentRequest" }, "example": { "name": "Research Assistant (from template)" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgent" }, "example": { "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "name": "Research Assistant (from template)", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "ACTIVE" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}/nodes": { "get": { "tags": [ "API v1", "Workflows", "Workflow Nodes" ], "summary": "List Workflow Nodes", "description": "List a workflow's orchestration nodes in a simplified shape.", "operationId": "List_workflow_nodes_v1_workflows__workflow_id__nodes_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeView" }, "title": "Response List Workflow Nodes V1 Workflows Workflow Id Nodes Get" }, "example": [ { "id": "f6f6f6f6-a7a7-b8b8-c9c9-d0d0d0d0d0d0", "type": "action", "name": "Send Message", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_id": "68230439d76e61ed7e92e4c3", "after_node_ids": [], "next_node_ids": [] } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Workflows", "Workflow Nodes" ], "summary": "Add Workflow Node", "description": "Add a node to a workflow DAG (action, agent, or advanced) and wire its edges. Cycles are rejected.", "operationId": "Add_workflow_node_v1_workflows__workflow_id__nodes_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Deploy the workflow after adding so the change takes effect immediately.", "default": true, "title": "Deploy" }, "description": "Deploy the workflow after adding so the change takes effect immediately." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWorkflowNodeRequest" }, "example": { "type": "action", "name": "Send Message", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_id": "68230439d76e61ed7e92e4c3" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeView" }, "title": "Response Add Workflow Node V1 Workflows Workflow Id Nodes Post" }, "example": [ { "id": "f6f6f6f6-a7a7-b8b8-c9c9-d0d0d0d0d0d0", "type": "action", "name": "Send Message", "connection_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "operation_id": "68230439d76e61ed7e92e4c3", "after_node_ids": [], "next_node_ids": [] } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}/nodes/{node_id}": { "delete": { "tags": [ "API v1", "Workflows", "Workflow Nodes" ], "summary": "Remove Workflow Node", "description": "Remove a node from a workflow and scrub any edges that pointed to it.", "operationId": "Remove_workflow_node_v1_workflows__workflow_id__nodes__node_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "node_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Node Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Deploy the workflow after removing so the change takes effect immediately.", "default": true, "title": "Deploy" }, "description": "Deploy the workflow after removing so the change takes effect immediately." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeView" }, "title": "Response Remove Workflow Node V1 Workflows Workflow Id Nodes Node Id Delete" }, "example": [] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows": { "get": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "List Workflows", "description": "Retrieve a paginated list of workflows (orchestration agents)", "operationId": "List_workflows_v1_workflows_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 10, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_WorkflowResponse_" }, "example": { "items": [ { "id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "name": "Blog Content Crew", "description": "A 4-agent sequential pipeline that turns blog post ideas into scheduled posts.", "icon": "📝", "status": "ACTIVE", "type": "orchestration", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "framework": "agno", "access_scope": "personal", "version": 1, "is_latest": true, "created_at": "2026-07-24T22:24:20.304502Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "Create Workflow", "description": "Create a new workflow (orchestration) with specified configuration and nodes", "operationId": "Create_Workflow_v1_workflows_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCreateRequest" }, "example": { "name": "Blog Content Crew", "description": "Turns blog post ideas into scheduled posts." } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}": { "get": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "Get Workflow", "description": "Retrieve detailed information about a specific workflow by its unique identifier", "operationId": "Get_Workflow_v1_workflows__workflow_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" }, "example": { "id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "name": "Blog Content Crew", "description": "A 4-agent sequential pipeline that turns blog post ideas into scheduled posts.", "icon": "📝", "status": "ACTIVE", "type": "orchestration", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "framework": "agno", "access_scope": "personal", "version": 1, "is_latest": true, "created_at": "2026-07-24T22:24:20.304502Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "Update Workflow", "description": "Update an existing workflow's configuration, nodes, or settings. Use deploy=true to apply changes immediately.", "operationId": "Update_Workflow_v1_workflows__workflow_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "deploy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Automatically deploy the workflow after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call.", "default": false, "title": "Deploy" }, "description": "Automatically deploy the workflow after updating to apply changes immediately. Without this, changes are staged but not active until a PUT deploy call." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowUpdateRequest" }, "example": { "name": "Blog Content Crew v2" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" }, "example": { "id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "name": "Blog Content Crew v2", "description": "A 4-agent sequential pipeline that turns blog post ideas into scheduled posts.", "icon": "📝", "status": "ACTIVE", "type": "orchestration", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "framework": "agno", "access_scope": "personal", "version": 1, "is_latest": true, "created_at": "2026-07-24T22:24:20.304502Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "Deploy Workflow", "description": "Deploy a workflow to make it active and available for execution. Validates the workflow configuration and provisions necessary resources.", "operationId": "Deploy_Workflow_v1_workflows__workflow_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" }, "example": { "id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "name": "Blog Content Crew", "description": "A 4-agent sequential pipeline that turns blog post ideas into scheduled posts.", "icon": "📝", "status": "ACTIVE", "type": "orchestration", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "deployment_type": "serverless", "model_provider": "anthropic", "model_name": "claude-sonnet-5", "framework": "agno", "access_scope": "personal", "version": 1, "is_latest": true, "created_at": "2026-07-24T22:24:20.304502Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Workflows", "Workflows CRUD" ], "summary": "Delete Workflow", "description": "Permanently delete a workflow and all associated resources", "operationId": "Delete_Workflow_v1_workflows__workflow_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}/invoke/async": { "post": { "tags": [ "API v1", "Workflows", "Workflows Invocation" ], "summary": "Invoke Workflow (Async)", "description": "Invoke a workflow asynchronously. Returns immediately with task ID.", "operationId": "Invoke_Workflow__Async__v1_workflows__workflow_id__invoke_async_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workflow version to invoke. default = latest", "title": "Version" }, "description": "The workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Draft a post about MCP.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTask" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "status": "pending" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}/invoke/stream": { "post": { "tags": [ "API v1", "Workflows", "Workflows Invocation" ], "summary": "Invoke Workflow (Stream)", "description": "Invoke a workflow with real-time streaming. Returns Server-Sent Events (SSE).", "operationId": "Invoke_Workflow__Stream__v1_workflows__workflow_id__invoke_stream_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workflow version to invoke. default = latest", "title": "Version" }, "description": "The workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Draft a post about MCP.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "type": "connected", "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "time": "2026-07-28T21:14:22.053899+00:00" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workflows/{workflow_id}/invoke": { "post": { "tags": [ "API v1", "Workflows", "Workflows Invocation" ], "summary": "Invoke Workflow (Sync)", "description": "Invoke a workflow and wait for completion. Returns the final result.", "operationId": "Invoke_Workflow__Sync__v1_workflows__workflow_id__invoke_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workflow version to invoke. default = latest", "title": "Version" }, "description": "The workflow version to invoke. default = latest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Draft a post about MCP.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTask" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "b2b2b2b2-c3c3-d4d4-e5e5-f6f6f6f6f6f6", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Draft a post about MCP.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "Draft published to the content calendar for Tuesday.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge": { "get": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD" ], "summary": "List Knowledge Bases", "description": "Returns a paginated list of Knowledge bases", "operationId": "List_knowledge_bases_v1_knowledge_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_KnowledgeBaseItem_" }, "example": { "items": [ { "id": "c3c3c3c3-d4d4-e5e5-f6f6-a7a7a7a7a7a7", "name": "PeopleDB", "description": "Contact records used by the support agent.", "type": "managed", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "agent_id": null, "total_documents": 2 } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD" ], "summary": "Create Knowledge Base", "description": "Creates a knowledge base", "operationId": "Create_knowledge_base_v1_knowledge_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedKnowledgeBaseRequest" }, "example": { "name": "PeopleDB", "description": "Contact records used by the support agent." } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseItem" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge/{kb_id}": { "get": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD" ], "summary": "Get Knowledge Base Details", "description": "Get knowledge base item details by id", "operationId": "Get_knowledge_base_details_v1_knowledge__kb_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseItem" }, "example": { "id": "c3c3c3c3-d4d4-e5e5-f6f6-a7a7a7a7a7a7", "name": "PeopleDB", "description": "Contact records used by the support agent.", "type": "managed", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "agent_id": null, "total_documents": 2 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD" ], "summary": "Delete Knowledge Base", "description": "Deletes knowledge base item by id", "operationId": "Delete_knowledge_base_v1_knowledge__kb_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD" ], "summary": "Update Knowledge Base", "description": "Updates a knowledge base", "operationId": "Update_knowledge_base_v1_knowledge__kb_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedKnowledgeBaseRequest" }, "example": { "name": "PeopleDB", "description": "Updated description." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseItem" }, "example": { "id": "c3c3c3c3-d4d4-e5e5-f6f6-a7a7a7a7a7a7", "name": "PeopleDB", "description": "Updated description.", "type": "managed", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "agent_id": null, "total_documents": 2 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge/{kb_id}/documents": { "get": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD", "Knowledge Documents" ], "summary": "Get Knowledge Base Documents", "description": "Get knowledge base documents", "operationId": "Get_knowledge_base_documents_v1_knowledge__kb_id__documents_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_KnowledgeBaseDocumentItem_" }, "example": { "items": [ { "id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8", "name": "handbook.pdf", "url": "https://example.com/handbook.pdf", "status": "indexed", "created_at": "2026-07-28T20:55:54.042725Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD", "Knowledge Documents" ], "summary": "Add Knowledge Base Documents", "description": "Add knowledge base documents", "operationId": "Add_knowledge_base_documents_v1_knowledge__kb_id__documents_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDocumentsRequest" }, "example": { "document_urls": [ "https://example.com/handbook.pdf" ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/src__models__knowledge__documents__KnowledgeBaseDocumentItem" }, "title": "Response Add Knowledge Base Documents V1 Knowledge Kb Id Documents Post" }, "example": { "items": [ { "id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8", "name": "handbook.pdf", "url": "https://example.com/handbook.pdf", "status": "indexed", "created_at": "2026-07-28T20:55:54.042725Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge/{kb_id}/documents/{document_id}": { "get": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD", "Knowledge Documents" ], "summary": "Get Knowledge Base Document By Id", "description": "Get knowledge base document by id", "operationId": "Get_knowledge_base_document_by_id_v1_knowledge__kb_id__documents__document_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/xpander_dev_utils__models__knowledge_bases__KnowledgeBaseDocumentItem" }, "example": { "id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8", "name": "handbook.pdf", "url": "https://example.com/handbook.pdf", "status": "indexed", "created_at": "2026-07-28T20:55:54.042725Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Knowledge", "Knowledge CRUD", "Knowledge Documents" ], "summary": "Delete Knowledge Base Document By Id", "description": "Delete knowledge base document by id", "operationId": "Delete_knowledge_base_document_by_id_v1_knowledge__kb_id__documents__document_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/knowledge/{kb_id}/search": { "get": { "tags": [ "API v1", "Knowledge", "Knowledge Search" ], "summary": "Search In Knowledge Base", "description": "Searches using vector search in knowledge base", "operationId": "Search_in_knowledge_base_v1_knowledge__kb_id__search_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "kb_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Kb Id" } }, { "name": "search_query", "in": "query", "required": true, "schema": { "type": "string", "description": "Query to search in the VDB", "title": "Search Query" }, "description": "Query to search in the VDB" }, { "name": "use_bubble", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Should use bubble search to return the result capped", "default": false, "title": "Use Bubble" }, "description": "Should use bubble search to return the result capped" }, { "name": "bubble_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Bubble size (padding + result + margin)", "default": 1000, "title": "Bubble Size" }, "description": "Bubble size (padding + result + margin)" }, { "name": "top_k", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Top K Results", "default": 10, "title": "Top K" }, "description": "Top K Results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VectorSearchResult" }, "title": "Response Search In Knowledge Base V1 Knowledge Kb Id Search Get" }, "example": [ { "document_id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8", "score": 0.87, "content": "Support contact numbers are listed in section 4 of the handbook." } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools": { "get": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "List Tools", "description": "Unified catalog of attachable tools: connectors, agents, workflows, custom functions, and MCP servers. Filter with ?type=.", "operationId": "List_tools_v1_tools_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ToolKind" }, { "type": "null" } ], "description": "Filter by tool kind.", "title": "Type" }, "description": "Filter by tool kind. Pass a value to scope the request.", "example": "connector" }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional search query.", "title": "Query" }, "description": "Optional search query.", "example": "firecrawl" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 20, "title": "Per Page" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ToolCatalogItem_" }, "example": { "items": [ { "kind": "connector", "id": "11111111-2222-3333-4444-555555555555", "name": "Firecrawl", "description": "", "logo": "firecrawl", "status": "ready", "total_operations": 6, "using_built_in_auth": true, "connections": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "Firecrawl", "access_scope": "organizational", "is_service_account": false, "owner": null, "version": "0.6", "status": null } ] } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools/search": { "get": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "Search Tools", "description": "Fuzzy search the unified tool catalog by name/description.", "operationId": "Search_tools_v1_tools_search_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Search query.", "title": "Query" }, "description": "Search query.", "example": "firecrawl" }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ToolKind" }, { "type": "null" } ], "description": "Filter by tool kind.", "title": "Type" }, "description": "Filter by tool kind. Pass a value to scope the request.", "example": "connector" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCatalogItem" }, "title": "Response Search Tools V1 Tools Search Get" }, "example": [ { "kind": "connector", "id": "11111111-2222-3333-4444-555555555555", "name": "Firecrawl", "status": "ready", "total_operations": 6, "connections": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "Firecrawl", "access_scope": "organizational" } ] } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools/connectors/{connector_id}/operations": { "get": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "List Connector Operations", "description": "List (or search) a connector connection's operations. Use an operation's `id` as operation_id when attaching it to an agent.", "operationId": "List_connector_operations_v1_tools_connectors__connector_id__operations_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connector Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "connection_id", "in": "query", "required": true, "schema": { "type": "string", "description": "The connection to list operations for.", "title": "Connection Id" }, "description": "The connection to list operations for.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional operation search query.", "title": "Query" }, "description": "Optional operation search query.", "example": "scrape" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorOperationItem" }, "title": "Response List Connector Operations V1 Tools Connectors Connector Id Operations Get" }, "example": [ { "id": "67e2daf399f31f9c55d127a7", "operationId": "FirecrawlScrapingServiceExtractWebpageContent", "path": "/scrape", "method": "post", "summary": "Extract content from a specified webpage URL.", "tags": [ "Scraping Service" ], "pretty_name": "Extract Webpage Content", "pretty_description": "Extracts content from a specified webpage URL." } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools/connectors/{connector_id}/connect": { "post": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "Connect Connector", "description": "Create a connection to a connector. For OAuth2 connectors, returns an oauth2_required response with a connector_page_url to complete browser auth.", "operationId": "Connect_connector_v1_tools_connectors__connector_id__connect_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connector Id" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectConnectorRequest" }, "example": { "name": "My Firecrawl connection", "security": { "api_key": "" } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "My Firecrawl connection", "access_scope": "organizational", "is_service_account": false, "status": "active", "created_at": "2026-07-28T20:55:54.042725Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools/connectors/{connector_id}/connections/{connection_id}/{operation_id}/schema": { "get": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "Get Connector Operation Schema", "description": "Get an operation's input/output schema. `input` is a JSON schema grouping the operation's inputs into `query_params`/`path_params`/`body_params` (the same structure the invoke endpoint accepts); `output` is the operation's success (2xx application/json) response schema. All $ref references are resolved inline. `operation_id` accepts the operation's `id` or `operationId`; pass `_` as connector_id to resolve it from the connection.", "operationId": "Get_connector_operation_schema_v1_tools_connectors__connector_id__connections__connection_id___operation_id__schema_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connector Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connection Id" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" }, "example": "FirecrawlScrapingServiceExtractWebpageContent" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "67e2daf399f31f9c55d127a7", "operationId": "FirecrawlScrapingServiceExtractWebpageContent", "path": "/scrape", "method": "post", "input": { "type": "object", "properties": { "query_params": { "type": "object", "properties": {} }, "path_params": { "type": "object", "properties": {} }, "body_params": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to scrape" } }, "required": [ "url" ] } } }, "output": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object" } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tools/connectors/{connector_id}/connections/{connection_id}/{operation_id}": { "post": { "tags": [ "API v1", "Tools", "Tools Discovery" ], "summary": "Invoke Connector Operation", "description": "Invoke a connector operation on a connection, without an agent or task. Body: `body_params` (request body), `query_params`, `path_params` (by name), `headers` (extra headers for the target API). The operation runs with its spec-defined HTTP method regardless of this POST; connection credentials are applied automatically. `operation_id` accepts the operation's `id` or `operationId`; pass `_` as connector_id to resolve it from the connection. The response is the target API's response. Times out after 300s.", "operationId": "Invoke_connector_operation_v1_tools_connectors__connector_id__connections__connection_id___operation_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connector Id" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Connection Id" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Operation Id" }, "example": "FirecrawlScrapingServiceExtractWebpageContent" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPayload" }, "example": { "body_params": { "url": "https://example.com", "formats": [ "markdown" ] } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "success": true, "data": { "markdown": "# Example Domain\n\nThis domain is for use in documentation examples...", "metadata": { "title": "Example Domain", "sourceURL": "https://example.com", "statusCode": 200 } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/custom_functions": { "get": { "tags": [ "API v1", "Custom Functions", "Custom Functions CRUD" ], "summary": "List Custom Functions", "description": "List all custom functions in the organization. Custom functions are user-defined Python functions that can be attached to agents as tools using attached_tools with id='xpander-custom-functions'.", "operationId": "List_custom_functions_v1_custom_functions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_CustomFunctionItem_" }, "example": { "items": [ { "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9", "name": "Add Document to KB", "description": "", "technical_description": "Takes a knowledge base id and a list of document URLs and POSTs them to the xpander API.", "status": "ready", "limits": { "max_run_time": 15 }, "input_schema": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "document_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledge_base_id", "document_urls" ] } } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "API v1", "Custom Functions", "Custom Functions CRUD" ], "summary": "Create Custom Function", "description": "Create a new custom function. Provide a name, optional description, and Python source code. The code must define a function called `xpander_run_action(...)` that will be executed when the function is invoked. After creation, the function is automatically analyzed for safety and input schema extraction. Status will transition from 'analysing' to 'ready' once analysis completes.", "operationId": "Create_custom_function_v1_custom_functions_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomFunctionRequest" }, "example": { "name": "Add Document to KB", "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n return {\"added\": len(document_urls)}\n" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9", "name": "Add Document to KB", "description": "", "technical_description": "Takes a knowledge base id and a list of document URLs and POSTs them to the xpander API.", "status": "ready", "limits": { "max_run_time": 15 }, "input_schema": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "document_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledge_base_id", "document_urls" ] }, "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n return {\"added\": len(document_urls)}\n" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/custom_functions/{function_id}": { "get": { "tags": [ "API v1", "Custom Functions", "Custom Functions CRUD" ], "summary": "Get Custom Function", "description": "Get a custom function by ID, including its source code, input schema, and status.", "operationId": "Get_custom_function_v1_custom_functions__function_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "function_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Function Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFunctionItem" }, "example": { "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9", "name": "Add Document to KB", "description": "", "technical_description": "Takes a knowledge base id and a list of document URLs and POSTs them to the xpander API.", "status": "ready", "limits": { "max_run_time": 15 }, "input_schema": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "document_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledge_base_id", "document_urls" ] }, "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n return {\"added\": len(document_urls)}\n" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "API v1", "Custom Functions", "Custom Functions CRUD" ], "summary": "Update Custom Function", "description": "Update an existing custom function. You can update name, description, source_code, and limits. If source_code changes, the function is re-analyzed automatically.", "operationId": "Update_custom_function_v1_custom_functions__function_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "function_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Function Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomFunctionRequest" }, "example": { "description": "Adds documents to a managed knowledge base." } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9", "name": "Add Document to KB", "description": "Adds documents to a managed knowledge base.", "technical_description": "Takes a knowledge base id and a list of document URLs and POSTs them to the xpander API.", "status": "ready", "limits": { "max_run_time": 15 }, "input_schema": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "document_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledge_base_id", "document_urls" ] } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Custom Functions", "Custom Functions CRUD" ], "summary": "Delete Custom Function", "description": "Permanently delete a custom function. Make sure to remove it from any agents' attached_tools and graph before deleting.", "operationId": "Delete_custom_function_v1_custom_functions__function_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "function_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Function Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/custom_functions/generate": { "post": { "tags": [ "API v1", "Custom Functions", "Custom Functions" ], "summary": "Generate Custom Function", "description": "AI-generate a custom function from a natural language description. Provide a 'query' describing what the function should do, and optionally 'user_function' (existing code to improve) or 'import_curl' (a cURL command to convert into a function). Returns the generated Python source code.", "operationId": "Generate_custom_function_v1_custom_functions_generate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCustomFunctionRequest" }, "example": { "query": "Add a list of document URLs to a knowledge base." } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCustomFunctionResponse" }, "example": { "id": "e5e5e5e5-f6f6-a7a7-b8b8-c9c9c9c9c9c9", "name": "Add Document to KB", "description": "", "technical_description": "Takes a knowledge base id and a list of document URLs and POSTs them to the xpander API.", "status": "ready", "limits": { "max_run_time": 15 }, "input_schema": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "document_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "knowledge_base_id", "document_urls" ] }, "source_code": "def xpander_run_action(knowledge_base_id: str, document_urls: list):\n return {\"added\": len(document_urls)}\n" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/custom_functions/{function_id}/execute": { "post": { "tags": [ "API v1", "Custom Functions", "Custom Functions" ], "summary": "Execute Custom Function", "description": "Execute a custom function with the provided parameters. The function must be in 'ready' status. Parameters are passed as key-value pairs in the request body matching the function's input_schema.", "operationId": "Execute_custom_function_v1_custom_functions__function_id__execute_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "function_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Function Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "result": { "added": 1 }, "status": "success", "execution_time": 0.42 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks": { "get": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Get Tasks", "description": "Get pagniated tasks list", "operationId": "Get_Tasks_v1_tasks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (starting from 1)", "default": 1, "title": "Page" }, "description": "Page number (starting from 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Items per page (max 50)", "default": 20, "title": "Per Page" }, "description": "Items per page (max 50)" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "description": "filter by user id (optional)", "title": "User Id" }, "description": "filter by user id (optional)" }, { "name": "parent_task_id", "in": "query", "required": false, "schema": { "type": "string", "description": "filter by parent task id (optional)", "title": "Parent Task Id" }, "description": "filter by parent task id (optional)" }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "filter by agent id (optional)", "title": "Agent Id" }, "description": "filter by agent id (optional)" }, { "name": "triggering_agent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "filter by triggering agent id (parent calling agent) (optional)", "title": "Triggering Agent Id" }, "description": "filter by triggering agent id (parent calling agent) (optional)" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AgentExecutionStatus-Input", "description": "filter by task status (optional)" }, "description": "filter by task status (optional)" }, { "name": "internal_status", "in": "query", "required": false, "schema": { "type": "string", "description": "filter by internal status (optional)", "title": "Internal Status" }, "description": "filter by internal status (optional)" }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "filter tasks created on or after this date (ISO 8601, optional)", "title": "From Date" }, "description": "filter tasks created on or after this date (ISO 8601, optional)" }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "filter tasks created on or before this date (ISO 8601, optional)", "title": "To Date" }, "description": "filter tasks created on or before this date (ISO 8601, optional)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_TasksListItem_" }, "example": { "items": [ { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "user_id": "user-123", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "title": "Summarize today's signups", "result": "42 new signups today, up 12% week over week.", "source_node_type": "api", "parent_task_id": null, "created_at": "2026-07-28T20:59:02.915959Z", "updated_at": "2026-07-28T20:59:51.661537Z" } ], "total": 1, "page": 1, "per_page": 20, "total_pages": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Get Task", "description": "Get Task by ID", "operationId": "Get_Task_v1_tasks__task_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecution" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Delete Task", "description": "Delete Task by ID", "operationId": "Delete_Task_v1_tasks__task_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/thread": { "get": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Get Task'S Thread", "description": "Get Task's thread", "operationId": "Get_Task_s_thread_v1_tasks__task_id__thread_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": [ { "id": "f0f0f0f0-1111-2222-3333-444444444444_user_1", "role": "user", "content": "Summarize today's signups.", "created_at": 1785272342 }, { "id": "f0f0f0f0-1111-2222-3333-444444444444_assistant_1", "role": "assistant", "content": "42 new signups today, up 12% week over week.", "created_at": 1785272391 } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/thread/full": { "get": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Get Task'S Full Thread", "description": "Get Task's full thread including sub tasks", "operationId": "Get_Task_s_full_thread_v1_tasks__task_id__thread_full_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "root": [ { "id": "f0f0f0f0-1111-2222-3333-444444444444_user_1", "role": "user", "content": "Summarize today's signups.", "created_at": 1785272342 }, { "id": "f0f0f0f0-1111-2222-3333-444444444444_assistant_1", "role": "assistant", "content": "42 new signups today, up 12% week over week.", "created_at": 1785272391 } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/llm_usage": { "get": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Get Task Llm Usage", "description": "Get LLM token usage for a specific task", "operationId": "Get_Task_LLM_Usage_v1_tasks__task_id__llm_usage_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "tokens": 73712, "input_tokens": 70216, "output_tokens": 3496, "uncached_input_tokens": 10, "cache_read_tokens": 142480, "cache_write_tokens": 44766, "actions": 4, "is_byok": false, "cost": 0.66646, "ai_model": "claude-sonnet-5" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/stop": { "post": { "tags": [ "API v1", "Tasks", "Tasks CRUD" ], "summary": "Stop Task", "description": "Stop a running task", "operationId": "Stop_Task_v1_tasks__task_id__stop_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecution" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/misc/llm_providers": { "get": { "tags": [ "API v1", "Misc", "LLM Providers" ], "summary": "List Llm Providers", "description": "Returns a list of available LLM providers without their models. Use the provider's internal_identifier with GET /misc/llm_providers/{provider_identifier}/models to retrieve available models.", "operationId": "List_LLM_providers_v1_misc_llm_providers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/LLMProviderItem" }, "type": "array", "title": "Response List Llm Providers V1 Misc Llm Providers Get" }, "example": [ { "id": "3f3f3f3f-4a4a-5b5b-6c6c-7d7d7d7d7d7d", "name": "Anthropic", "internal_identifier": "anthropic", "logo": "anthropic", "description": null }, { "id": "4a4a4a4a-5b5b-6c6c-7d7d-8e8e8e8e8e8e", "name": "OpenAI", "internal_identifier": "openai", "logo": "openai", "description": null } ] } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/v1/misc/llm_providers/{provider_identifier}/models": { "get": { "tags": [ "API v1", "Misc", "LLM Providers" ], "summary": "List Llm Models", "description": "Returns available models for a specific LLM provider. Use the model_id value as the agent's model_name field when creating or updating an agent.", "operationId": "List_LLM_models_v1_misc_llm_providers__provider_identifier__models_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "provider_identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Provider Identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LLMModelItem" }, "title": "Response List Llm Models V1 Misc Llm Providers Provider Identifier Models Get" }, "example": [ { "model_id": "claude-opus-5", "display_name": "Claude Opus 5", "tier": 1, "description": "Most capable Anthropic model. 1M-token context, 128k max output, full tool use." }, { "model_id": "claude-sonnet-5", "display_name": "Claude Sonnet 5", "tier": 2, "description": "Balanced speed and capability for everyday agent work." } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/skills/publish": { "post": { "tags": [ "API v1", "Skills" ], "summary": "Publish Skills", "description": "Publish up to 25 skills from a repository into the organization's skill registry. Each skill's visibility, allowlisted agents, access scope, users and groups come from its `xpander.yaml`. Returns one outcome per skill: created, updated, unchanged, archived or error.", "operationId": "Publish_skills_v1_skills_publish_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSkillsRequest" }, "example": { "managed_by": { "repo": "acme/agent-skills", "path_prefix": "skills", "ref": "refs/heads/main", "commit": "9f1c2d3e4b5a6978877665544332211009988776", "run_url": "https://github.com/acme/agent-skills/actions/runs/123456789" }, "archive_missing": true, "dry_run": false, "skills": [ { "name": "quarterly-report", "path": "quarterly-report", "skill_md": "---\nname: quarterly-report\ndescription: Build the quarterly revenue report from the finance warehouse.\n---\n\nRead the report template, query the warehouse, and hand back a PDF.", "bundle_b64": "H4sIAAAAAAAAA+3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAKAAA", "sha256": "4d1f8a3c0b9e7f6d5c4b3a2918273645f0e1d2c3b4a5968778695a4b3c2d1e0f", "metadata": { "visibility": "restricted", "agents": [ "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5" ], "access_scope": "organizational", "users": [], "groups": [ "finance" ] } } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSkillsResponse" }, "example": { "results": [ { "name": "quarterly-report", "outcome": "updated", "skill_id": "5b5b5b5b-6c6c-7d7d-8e8e-9f9f9f9f9f9f", "detail": "bundle changed; visibility org -> restricted" } ], "archived": [ "legacy-invoice-check" ], "warnings": [] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/invoke": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Run Conversation Turn (Sync)", "description": "Send one message to the agent and wait for the reply. The response is the conversation record: `id` is the `conversation_id` (pass it as `id` to continue), `result` is the reply, `status` is the turn's status. Omit `id` to start a new conversation. Sending to a conversation whose turn is still running cancels that turn and runs the new message.", "operationId": "Run_Conversation_Turn_Sync__v1_agents_agent_id_conversations_invoke_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." }, { "name": "sub_tasks", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubTasksMode" }, { "type": "null" } ], "description": "How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed.", "title": "Sub Tasks" }, "description": "How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecution" }, "example": { "id": "7a7a7a7a-1111-2222-3333-555555555555", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 }, "parent_execution": "f0f0f0f0-1111-2222-3333-444444444444", "conversation_id": "f0f0f0f0-1111-2222-3333-444444444444", "is_gateway": false } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/invoke/stream": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Run Conversation Turn (Stream)", "description": "Send one message and stream the turn over SSE: `task_created` with the conversation record (its id is the conversation id), `turn_started`, the reply as `chunk` events, skill calls and cards, then `turn_finished` carrying the reply. Pass `id` = conversation_id to continue a conversation; send Last-Event-ID to resume after a dropped connection.", "operationId": "Run_Conversation_Turn_Stream__v1_agents_agent_id_conversations_invoke_stream_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." }, { "name": "sub_tasks", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/SubTasksMode" }, { "type": "null" } ], "description": "How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed.", "title": "Sub Tasks" }, "description": "How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "type": "connected", "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "time": "2026-07-28T21:14:22.053899+00:00" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/run-state": { "get": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Conversation Run State", "description": "Cheap snapshot of the conversation: whether a turn is running, whether it can take a steer, and the queued follow-ups.", "operationId": "Conversation_Run_State_v1_agents_agent_id_conversations__conversation_id_run_state_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayRunState" }, "example": { "conversation_id": "f0f0f0f0-1111-2222-3333-444444444444", "is_running": false, "is_steerable": false, "steer_target": "none", "active_child_id": null, "queue_depth": 1, "queued_messages": [ { "id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f", "text": "And who created it?", "files": [], "user": null, "enqueued_at": "2026-07-28T21:11:24.343369+00:00", "idempotency_key": null } ], "execution_status": "completed", "conversation_state": "regular" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/messages": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Send Conversation Message", "description": "Add a follow-up message to a conversation. mode=auto queues while a turn is running and answers 'started' when idle; mode=queue always queues; mode=steer hands the message to the running turn at its next skill call (409 when idle); mode=interrupt stops the running turn and runs this message as the next turn.", "operationId": "Send_Conversation_Message_v1_agents_agent_id_conversations__conversation_id_messages_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessageRequest" }, "example": { "text": "And who created it?", "mode": "queue" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMessageAccepted" }, "example": { "action": "queued", "message_id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f", "queue_depth": 1, "steer_target": null } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/drain/stream": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Drain Conversation Queue (Stream)", "description": "Run an idle conversation's queued follow-ups in order, streaming each turn over SSE.", "operationId": "Drain_Conversation_Queue_Stream__v1_agents_agent_id_conversations__conversation_id_drain_stream_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "type": "connected", "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "time": "2026-07-28T21:14:22.053899+00:00" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/stop": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Stop Conversation", "description": "Stop the running turn. Keeps the queued follow-ups unless clear_queue=true.", "operationId": "Stop_Conversation_v1_agents_agent_id_conversations__conversation_id_stop_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayStopRequest" }, "example": { "clear_queue": true } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "stopped": true, "active_child_id": null, "queue_cleared": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/queue": { "delete": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Clear Conversation Queue", "description": "Cancel every pending queued message for the conversation.", "operationId": "Clear_Conversation_Queue_v1_agents_agent_id_conversations__conversation_id_queue_delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "cleared": 1 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/queue/{message_id}": { "delete": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Cancel Queued Message", "description": "Cancel one pending queued message by id.", "operationId": "Cancel_Queued_Message_v1_agents_agent_id_conversations__conversation_id_queue_message_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "removed": true } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/answers": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Submit Question Answers (Stream)", "description": "Submit structured answers to a question card and continue the turn, streaming every event over SSE.", "operationId": "Submit_Question_Answers_Stream__v1_agents_agent_id_conversations__conversation_id_answers_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskUserQuestionsSubmission" }, "example": { "decision_id": "d-1a2b3c", "answers": [ { "question_id": "q1", "answer": "Weekly" } ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/confirm": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Confirm Card-Gated Action (Stream)", "description": "Approve or decline a confirmation card and continue the turn, streaming every event over SSE. The target of the action is read from the card itself, never from the body.", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "approve": { "type": "boolean" } }, "required": [ "request_id" ] } } } }, "responses": { "200": { "description": "Server-Sent Events stream of TaskUpdateEvent frames" } }, "security": [ { "APIKeyHeader": [] } ], "operationId": "Confirm_Card_Gated_Action_Stream__v1_agents_agent_id_conversations__conversation_id_confirm_post" } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/edit/{message_id}": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Edit Message + Re-run (Sync)", "description": "Rewrite an earlier user message and run it again as a new turn, returning the conversation record with the new reply. A turn still running on the conversation is cancelled first.", "operationId": "Edit_Message_Re_run_Sync__v1_agents_agent_id_conversations__conversation_id_edit_message_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "text": "Summarize this week's signups instead.", "user": { "id": "user-123", "email": "you@example.com" } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecution" }, "example": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}/edit/{message_id}/stream": { "post": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Edit Message + Re-run (Stream)", "description": "Stream variant of edit and re-run; streams every event over SSE.", "operationId": "Edit_Message_Re_run_Stream__v1_agents_agent_id_conversations__conversation_id_edit_message_id_stream_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Agent version to run.", "title": "Version" }, "description": "Agent version to run." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentExecutionRequest" }, "example": { "text": "Summarize this week's signups instead.", "user": { "id": "user-123", "email": "you@example.com" } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "type": "connected", "task_id": "f0f0f0f0-1111-2222-3333-444444444444", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "time": "2026-07-28T21:14:22.053899+00:00" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/agents/{agent_id}/conversations/{conversation_id}": { "get": { "tags": [ "API v1", "Agents", "Conversations" ], "summary": "Get Conversation", "description": "Return the conversation record, its thread (every turn), aggregate cost and token usage, and for every sub-task its record, thread and usage.", "operationId": "Get_Conversation_v1_agents_agent_id_conversations__conversation_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponse" }, "example": { "conversation_id": "f0f0f0f0-1111-2222-3333-444444444444", "execution": { "id": "f0f0f0f0-1111-2222-3333-444444444444", "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5", "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e", "status": "completed", "input": { "text": "Summarize today's signups.", "user": { "id": "user-123", "email": "you@example.com" } }, "result": "42 new signups today, up 12% week over week.", "created_at": "2026-07-28T20:59:02.915959Z", "finished_at": "2026-07-28T20:59:51.661537Z", "llm_model_provider": "anthropic", "llm_model_name": "claude-sonnet-5", "tokens": { "input_tokens": 70216, "output_tokens": 3496, "total_tokens": 73712 } }, "activity": [ { "id": "f0f0f0f0-1111-2222-3333-444444444444_user_1", "role": "user", "content": "Summarize today's signups.", "created_at": 1785272342 }, { "id": "f0f0f0f0-1111-2222-3333-444444444444_assistant_1", "role": "assistant", "content": "42 new signups today, up 12% week over week.", "created_at": 1785272391 } ], "sub_executions": [], "feedbacks": [], "usage": { "input_tokens": 70216, "output_tokens": 3496, "tokens": 73712, "cost": 0.66646 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AIAgent": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "unique_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unique Name" }, "origin_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Template" }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id" }, "runtime_environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runtime Environment Id", "description": "Runtime environment (image and environment spec) assigned to the agent, if any." }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "default": "serverless" }, "prompts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompts", "default": [] }, "is_latest": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Latest", "default": false }, "has_pending_changes": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Pending Changes", "default": false }, "deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deep Planning", "default": true }, "enforce_deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce Deep Planning", "default": true }, "use_agent_gateway": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Agent Gateway", "default": false }, "name": { "type": "string", "title": "Name" }, "connectivity_details": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2A" }, { "$ref": "#/components/schemas/AIAgentConnectivityDetailsCurl" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Connectivity Details", "default": {} }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "default": "external-harness", "description": "How the agent runs: 'external-harness' (default; a coding CLI chosen by harness_settings.default_cli) or 'agno' (the built-in loop). Legacy 'claude-code' / 'codex' values read as 'external-harness' with that CLI." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "default": "" }, "tools": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Tools", "default": [] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "default": "xpi:workflow:dusk", "description": "Icon shown next to the agent name: the platform icon id (default 'xpi:workflow:dusk') or a single emoji." }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "default": "male-avatar" }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "default": [] }, "attached_tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Connector" }, "type": "array" }, { "type": "null" } ], "title": "Attached Tools", "default": [] }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "default": "organizational" }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "default": { "role": [], "goal": [], "general": "" } }, "oas": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Oas", "default": {} }, "graph": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentGraphItem-Output" }, "type": "array" }, { "type": "null" } ], "title": "Graph", "default": [] }, "is_omni": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Omni", "default": false }, "skills": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Skills", "default": [], "description": "Skills enabled for the agent (name, description, version), resolved at read time. Attached skills only; built-in runtime capabilities are not listed." }, "runtime_environment": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Runtime Environment", "description": "Flattened environment spec resolved at read time; not persisted." }, "secret_bindings": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Secret Bindings", "description": "Vault secrets bound to the agent as resolved for its runtime; null means none." }, "gated_commands": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Gated Commands", "description": "Workspace commands that need approval before they run: {match, unless?, note?, approvers?, channels?} items where match is literal text. null means no gates; empty approvers asks the agent owner." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "default": "ACTIVE" }, "knowledge_bases": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentKnowledgeBase" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Bases", "default": [] }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "default": 1 }, "organization_id": { "type": "string", "title": "Organization Id" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "default_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default User Id", "description": "Organization user to run as when a non-UI invocation has no resolved user." }, "background_user_overrides": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Background User Overrides", "default": {} }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ] }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "default": false }, "deletable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deletable", "default": true }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "default": "amazon_bedrock" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "default": "global.anthropic.claude-sonnet-5" }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "default": "medium" }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base" }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "markdown" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key" }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "default": "xpander" }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ] }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "default": {} }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "default": "" }, "agno_settings": { "anyOf": [ { "$ref": "#/components/schemas/AgnoSettings" }, { "type": "null" } ], "default": { "session_storage": true, "learning": false, "agent_memories": false, "agentic_culture": false, "user_memories": false, "agentic_memory": false, "session_summaries": false, "num_history_runs": 50, "max_tool_calls_from_history": 0, "tool_call_limit": 0, "coordinate_mode": true, "pii_detection_enabled": false, "pii_detection_mask": true, "prompt_injection_detection_enabled": false, "openai_moderation_enabled": false, "reasoning_tools_enabled": true, "max_plan_retries": 15 } }, "harness_settings": { "anyOf": [ { "$ref": "#/components/schemas/HarnessSettings" }, { "type": "null" } ] }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "default": true }, "is_supervised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Supervised", "default": false }, "orchestration_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrchestrationNode-Output" }, "type": "array" }, { "type": "null" } ], "title": "Orchestration Nodes", "default": [] }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Output" }, { "type": "null" } ], "default": {} }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Output" }, { "type": "null" } ] }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "default": false }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "default": [] }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "default": false }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience" }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience" }, "can_self_schedule": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Can Self Schedule", "default": true }, "max_self_schedules": { "anyOf": [ { "type": "integer", "maximum": 1000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Self Schedules", "default": 3 }, "use_dynamic_tools": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Dynamic Tools", "default": false }, "workspace_tools_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Workspace Tools Enabled", "default": true }, "live_surface_sharing_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Live Surface Sharing Enabled", "default": true, "description": "Whether the agent may share the live surfaces it builds." }, "is_autonomous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Autonomous", "default": false }, "discoverable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Discoverable", "default": true }, "with_auto_context_management": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "With Auto Context Management", "default": true }, "developer_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Developer Access", "default": true }, "should_stage_before_publish": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Stage Before Publish", "default": true }, "webhook_url": { "type": "string", "title": "Webhook Url", "readOnly": true } }, "type": "object", "required": [ "name", "organization_id", "webhook_url" ], "title": "AIAgent" }, "AIAgentAccessScope": { "type": "string", "enum": [ "personal", "organizational" ], "title": "AIAgentAccessScope" }, "AIAgentConnectivityDetailsA2A": { "properties": { "custom_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Custom Headers", "default": {} }, "auth_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2AAuthType" }, { "type": "null" } ], "default": "none" }, "api_key_header_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Header Name", "default": "X-API-Key" }, "auth_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Value" }, "agent_url": { "type": "string", "title": "Agent Url" } }, "type": "object", "required": [ "agent_url" ], "title": "AIAgentConnectivityDetailsA2A" }, "AIAgentConnectivityDetailsA2AAuthType": { "type": "string", "enum": [ "none", "api_key", "basic", "bearer" ], "title": "AIAgentConnectivityDetailsA2AAuthType" }, "AIAgentConnectivityDetailsCurl": { "properties": { "custom_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Custom Headers", "default": {} }, "auth_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2AAuthType" }, { "type": "null" } ], "default": "none" }, "api_key_header_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Header Name", "default": "X-API-Key" }, "auth_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Value" }, "curl_command": { "type": "string", "title": "Curl Command" }, "invoke_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoke Url" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method", "default": "POST" }, "prompt_field_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt Field Name", "default": "" }, "files_field_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Files Field Name", "default": "" }, "task_id_field_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id Field Name", "default": "" } }, "type": "object", "required": [ "curl_command" ], "title": "AIAgentConnectivityDetailsCurl" }, "AIAgentDeploymentType": { "type": "string", "enum": [ "serverless", "container" ], "title": "AIAgentDeploymentType" }, "AIAgentGraphItem-Input": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "item_id": { "type": "string", "title": "Item Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "$ref": "#/components/schemas/AIAgentGraphItemType" }, "sub_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSubType" }, { "type": "null" } ] }, "targets": { "items": { "type": "string" }, "type": "array", "title": "Targets" }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSettings-Input" }, { "type": "null" } ] }, "is_first": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is First", "default": false } }, "type": "object", "required": [ "item_id", "type", "targets" ], "title": "AIAgentGraphItem" }, "AIAgentGraphItem-Output": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "item_id": { "type": "string", "title": "Item Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "type": { "$ref": "#/components/schemas/AIAgentGraphItemType" }, "sub_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSubType" }, { "type": "null" } ] }, "targets": { "items": { "type": "string" }, "type": "array", "title": "Targets" }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSettings-Output" }, { "type": "null" } ] }, "is_first": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is First", "default": false } }, "type": "object", "required": [ "item_id", "type", "targets" ], "title": "AIAgentGraphItem" }, "AIAgentGraphItemA2ASettings": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "type": "object", "title": "AIAgentGraphItemA2ASettings" }, "AIAgentGraphItemAdvancedFilteringOption": { "properties": { "returnables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Returnables" }, "searchables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Searchables" }, "globally_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Globally Enabled", "default": false } }, "type": "object", "title": "AIAgentGraphItemAdvancedFilteringOption" }, "AIAgentGraphItemCodingAgentSettings": { "properties": { "type": { "anyOf": [ { "type": "string", "const": "codex" }, { "type": "null" } ], "title": "Type", "default": "codex" } }, "type": "object", "title": "AIAgentGraphItemCodingAgentSettings" }, "AIAgentGraphItemHITLSettings": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "recipients": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Recipients" }, "hitl_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentHITLType" }, { "type": "null" } ] }, "slack_app": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slack App" }, "should_approve_with_current_user": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Approve With Current User", "default": true } }, "type": "object", "title": "AIAgentGraphItemHITLSettings" }, "AIAgentGraphItemMCPSettings": { "properties": { "type": { "anyOf": [ { "$ref": "#/components/schemas/MCPServerType" }, { "type": "null" } ], "default": "remote" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Command" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "transport": { "anyOf": [ { "$ref": "#/components/schemas/MCPServerTransport" }, { "type": "null" } ], "default": "streamable-http" }, "auth_type": { "anyOf": [ { "$ref": "#/components/schemas/MCPServerAuthType" }, { "type": "null" } ], "default": "none" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key" }, "use_secrets_manager": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Secrets Manager", "default": false }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "additional_scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Additional Scopes", "default": [] }, "headers": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Headers", "default": {} }, "env_vars": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Env Vars", "default": {} }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "default": [] }, "share_user_token_across_other_agents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Share User Token Across Other Agents", "default": true } }, "type": "object", "title": "AIAgentGraphItemMCPSettings" }, "AIAgentGraphItemSchema": { "properties": { "input": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input" }, "output": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output" } }, "type": "object", "title": "AIAgentGraphItemSchema" }, "AIAgentGraphItemSettings-Input": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "schemas": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSchema" }, { "type": "null" } ] }, "advanced_filtering_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemAdvancedFilteringOption" }, { "type": "null" } ] }, "hitl_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemHITLSettings" }, { "type": "null" } ] }, "a2a_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemA2ASettings" }, { "type": "null" } ] }, "coding_agent_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemCodingAgentSettings" }, { "type": "null" } ] }, "mcp_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemMCPSettings" }, { "type": "null" } ] }, "skills_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSkillsSettings" }, { "type": "null" } ] }, "use_cache": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Cache", "default": false }, "use_mock": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Mock", "default": false } }, "type": "object", "title": "AIAgentGraphItemSettings" }, "AIAgentGraphItemSettings-Output": { "properties": { "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "schemas": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSchema" }, { "type": "null" } ] }, "advanced_filtering_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemAdvancedFilteringOption" }, { "type": "null" } ] }, "hitl_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemHITLSettings" }, { "type": "null" } ] }, "a2a_options": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemA2ASettings" }, { "type": "null" } ] }, "coding_agent_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemCodingAgentSettings" }, { "type": "null" } ] }, "mcp_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemMCPSettings" }, { "type": "null" } ] }, "skills_settings": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentGraphItemSkillsSettings" }, { "type": "null" } ] }, "use_cache": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Cache", "default": false }, "use_mock": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Mock", "default": false } }, "type": "object", "title": "AIAgentGraphItemSettings" }, "AIAgentGraphItemSkillsSettings": { "properties": { "enabled_skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Enabled Skills", "default": [] } }, "type": "object", "title": "AIAgentGraphItemSkillsSettings" }, "AIAgentGraphItemSubType": { "type": "string", "enum": [ "sdk", "task", "assistant", "webhook", "operation", "custom_function", "local_tool" ], "title": "AIAgentGraphItemSubType" }, "AIAgentGraphItemType": { "type": "string", "enum": [ "source_node", "agent", "workflow", "tool", "human_in_the_loop", "xpsleep-agent-delay", "custom_agent", "storage", "local_db", "coding_agent", "mcp", "skills" ], "title": "AIAgentGraphItemType" }, "AIAgentHITLType": { "type": "string", "enum": [ "slack" ], "title": "AIAgentHITLType" }, "AIAgentInstructions": { "properties": { "role": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Role", "default": [] }, "goal": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Goal", "default": [] }, "general": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "General", "default": "" } }, "type": "object", "title": "AIAgentInstructions" }, "AIAgentSourceNode": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "type": { "$ref": "#/components/schemas/SourceNodeType" }, "targets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Targets" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "default": {} } }, "type": "object", "required": [ "type" ], "title": "AIAgentSourceNode" }, "AddActionTool": { "properties": { "type": { "type": "string", "const": "action", "title": "Type", "default": "action" }, "connection_id": { "type": "string", "title": "Connection Id", "description": "Connector connection id (the connection to call through)." }, "operation_ids": { "items": { "type": "string" }, "type": "array", "title": "Operation Ids", "description": "Operation catalog ids — the `id` field from GET /tools/connectors/{connector_id}/operations." } }, "type": "object", "required": [ "connection_id", "operation_ids" ], "title": "AddActionTool", "description": "Attach connector operations as agent tools." }, "AddCustomFunctionTool": { "properties": { "type": { "type": "string", "const": "custom_function", "title": "Type", "default": "custom_function" }, "custom_function_id": { "type": "string", "title": "Custom Function Id", "description": "Custom function id." } }, "type": "object", "required": [ "custom_function_id" ], "title": "AddCustomFunctionTool", "description": "Attach a custom function as an agent tool." }, "AddDocumentsRequest": { "properties": { "document_urls": { "items": { "type": "string" }, "type": "array", "title": "Document Urls", "description": "Documents URLs" } }, "type": "object", "required": [ "document_urls" ], "title": "AddDocumentsRequest", "description": "Request model for adding documents to a knowledge base." }, "AddMcpTool": { "properties": { "type": { "type": "string", "const": "mcp", "title": "Type", "default": "mcp" }, "mcp_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Id", "description": "MCP server id from the org registry — the `id` from GET /tools?type=mcp. Provide this OR `url`." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Remote MCP server URL for an inline (non-registry) MCP. Provide this OR `mcp_id`." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name for an inline MCP." }, "transport": { "anyOf": [ { "$ref": "#/components/schemas/MCPServerTransport" }, { "type": "null" } ], "description": "Transport for an inline MCP.", "default": "streamable-http" }, "auth_type": { "anyOf": [ { "$ref": "#/components/schemas/MCPServerAuthType" }, { "type": "null" } ], "description": "Auth type for an inline MCP.", "default": "none" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key", "description": "API key for an inline MCP when auth_type=api_key." }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id", "description": "OAuth2 client id for an inline MCP (optional; empty enables dynamic registration)." }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret", "description": "OAuth2 client secret for an inline MCP." }, "additional_scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Additional Scopes", "description": "Extra OAuth2 scopes for an inline MCP." }, "share_user_token_across_other_agents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Share User Token Across Other Agents", "description": "Share the authorized MCP token across the org's other agents.", "default": true }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Custom headers sent to an inline MCP." }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "description": "Optional subset of the MCP server's tools to expose." } }, "type": "object", "title": "AddMcpTool", "description": "Attach an MCP server — either from the org registry (mcp_id) or inline by URL." }, "AddSkillTool": { "properties": { "type": { "type": "string", "const": "skill", "title": "Type", "default": "skill" }, "skill_name": { "type": "string", "title": "Skill Name", "description": "Skill name — the `name` from GET /skills/catalog." } }, "type": "object", "required": [ "skill_name" ], "title": "AddSkillTool", "description": "Attach a skill from the xpander skills catalog as an agent tool." }, "AddSubAgentTool": { "properties": { "type": { "type": "string", "const": "agent", "title": "Type", "default": "agent" }, "agent_id": { "type": "string", "title": "Agent Id", "description": "Id of the agent to attach as a sub-agent." } }, "type": "object", "required": [ "agent_id" ], "title": "AddSubAgentTool", "description": "Attach another agent as a callable sub-agent tool." }, "AddWorkflowNodeRequest": { "properties": { "type": { "type": "string", "enum": [ "action", "agent", "advanced" ], "title": "Type", "description": "Node kind to add." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Node name." }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id", "description": "Connection id. Required for type=action." }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id", "description": "Operation catalog id. Required for type=action." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Instructions for the action/agent node." }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Agent id. Required for type=agent." }, "advanced": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationNode-Input" }, { "type": "null" } ], "description": "A full OrchestrationNode. Required for type=advanced." }, "after_node_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "After Node Ids", "description": "Append the new node id to the next_node_ids of these existing nodes.", "default": [] }, "next_node_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Next Node Ids", "description": "Ids of nodes to run after the new node.", "default": [] } }, "type": "object", "required": [ "type" ], "title": "AddWorkflowNodeRequest", "description": "Add a node to a workflow DAG. Use `action`/`agent` for the common cases, or `advanced` for full control." }, "AddWorkflowTool": { "properties": { "type": { "type": "string", "const": "workflow", "title": "Type", "default": "workflow" }, "workflow_id": { "type": "string", "title": "Workflow Id", "description": "Id of the workflow to attach." } }, "type": "object", "required": [ "workflow_id" ], "title": "AddWorkflowTool", "description": "Attach a workflow as a callable tool." }, "AgentActivityThread": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "messages": { "items": { "anyOf": [ { "$ref": "#/components/schemas/AgentActivityThreadMessage" }, { "$ref": "#/components/schemas/AgentActivityThreadToolCall" }, { "$ref": "#/components/schemas/AgentActivityThreadReasoning" }, { "$ref": "#/components/schemas/AgentActivityThreadSubAgentTrigger" }, { "$ref": "#/components/schemas/AgentActivityThreadAuth" }, { "$ref": "#/components/schemas/AgentActivityThreadPlanUpdate" }, { "$ref": "#/components/schemas/AgentActivityThreadTaskCompactizationEvent" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayCreateExecution" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayAskExecution" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayStopExecution" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayContinueExecution" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayGetExecutionsResult" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayAskUserQuestions" }, { "$ref": "#/components/schemas/AgentActivityThreadAskUserQuestionsAnswers" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewaySuggestTool" }, { "$ref": "#/components/schemas/AgentActivityThreadToolSuggestionResolved" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayInviteMember" }, { "$ref": "#/components/schemas/AgentActivityThreadInviteMemberResolved" }, { "$ref": "#/components/schemas/AgentActivityThreadGatewayAskForSecret" }, { "$ref": "#/components/schemas/AgentActivityThreadAskForSecretResolved" }, { "$ref": "#/components/schemas/AgentActivityThreadLiveSurface" }, { "$ref": "#/components/schemas/AgentActivityThreadInlineCard" } ] }, "type": "array", "title": "Messages" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] }, "context_status": { "anyOf": [ { "$ref": "#/components/schemas/ContextStatus" }, { "type": "null" } ] }, "state": { "$ref": "#/components/schemas/ConversationState", "default": "regular" } }, "type": "object", "required": [ "id", "created_at", "messages" ], "title": "AgentActivityThread" }, "AgentActivityThreadAskForSecretResolved": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "decision_id": { "type": "string", "title": "Decision Id" }, "names": { "items": { "type": "string" }, "type": "array", "title": "Names", "default": [] }, "declined": { "type": "boolean", "title": "Declined", "default": false }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "created_at", "decision_id" ], "title": "AgentActivityThreadAskForSecretResolved", "description": "The user's resolution of a prior ask_for_secret card (names only, no values).\n\nPersisted as its own activity entry (links via `decision_id`) so the card\nlocks on reload; the save itself happens in the chat-backend route." }, "AgentActivityThreadAskUserQuestionsAnswers": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "decision_id": { "type": "string", "title": "Decision Id" }, "answers": { "items": { "$ref": "#/components/schemas/GatewayAnswerItem" }, "type": "array", "title": "Answers", "default": [] }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "created_at", "decision_id" ], "title": "AgentActivityThreadAskUserQuestionsAnswers", "description": "User-submitted answers to a prior ask_user_questions card.\n\nPersisted as its own activity entry (links to the question via\n`decision_id`) and replayed into the gateway LLM context as a user message." }, "AgentActivityThreadAuth": { "properties": { "type": { "$ref": "#/components/schemas/MCPOAuthResponseType" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/MCPOAuthGetTokenTokenReadyResponse" }, { "$ref": "#/components/schemas/MCPOAuthGetTokenLoginRequiredResponse" }, { "$ref": "#/components/schemas/MCPOAuthGetTokenGenericResponse" } ], "title": "Data" }, "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "type", "data", "id", "created_at" ], "title": "AgentActivityThreadAuth" }, "AgentActivityThreadGatewayAskExecution": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "ask_execution", "title": "Action", "default": "ask_execution" }, "created_execution_id": { "type": "string", "title": "Created Execution Id" }, "new_input": { "type": "string", "title": "New Input" }, "rejected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rejected" } }, "type": "object", "required": [ "id", "created_at", "reasoning", "created_execution_id", "new_input" ], "title": "AgentActivityThreadGatewayAskExecution" }, "AgentActivityThreadGatewayAskForSecret": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "ask_for_secret", "title": "Action", "default": "ask_for_secret" }, "secrets": { "items": { "$ref": "#/components/schemas/RequiredSecret" }, "type": "array", "title": "Secrets", "default": [] } }, "type": "object", "required": [ "id", "created_at", "reasoning" ], "title": "AgentActivityThreadGatewayAskForSecret" }, "AgentActivityThreadGatewayAskUserQuestions": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "ask_user_questions", "title": "Action", "default": "ask_user_questions" }, "questions": { "items": { "$ref": "#/components/schemas/GatewayQuestion" }, "type": "array", "title": "Questions", "default": [] }, "folded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Folded" } }, "type": "object", "required": [ "id", "created_at", "reasoning" ], "title": "AgentActivityThreadGatewayAskUserQuestions" }, "AgentActivityThreadGatewayContinueExecution": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "continue_execution", "title": "Action", "default": "continue_execution" }, "created_execution_id": { "type": "string", "title": "Created Execution Id" }, "rejected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rejected" } }, "type": "object", "required": [ "id", "created_at", "reasoning", "created_execution_id" ], "title": "AgentActivityThreadGatewayContinueExecution" }, "AgentActivityThreadGatewayCreateExecution": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "create_execution", "title": "Action", "default": "create_execution" }, "created_execution_id": { "type": "string", "title": "Created Execution Id" }, "query": { "type": "string", "title": "Query", "default": "" }, "is_async": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Async", "default": false }, "ack_message": { "type": "string", "title": "Ack Message", "default": "" }, "target_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Agent Id" }, "target_agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Agent Name" } }, "type": "object", "required": [ "id", "created_at", "reasoning", "created_execution_id" ], "title": "AgentActivityThreadGatewayCreateExecution" }, "AgentActivityThreadGatewayExecutionResultEntry": { "properties": { "created_execution_id": { "type": "string", "title": "Created Execution Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" } }, "type": "object", "required": [ "created_execution_id" ], "title": "AgentActivityThreadGatewayExecutionResultEntry" }, "AgentActivityThreadGatewayGetExecutionsResult": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "get_executions_result", "title": "Action", "default": "get_executions_result" }, "executions": { "items": { "$ref": "#/components/schemas/AgentActivityThreadGatewayExecutionResultEntry" }, "type": "array", "title": "Executions", "default": [] } }, "type": "object", "required": [ "id", "created_at", "reasoning" ], "title": "AgentActivityThreadGatewayGetExecutionsResult" }, "AgentActivityThreadGatewayInviteMember": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "invite_member", "title": "Action", "default": "invite_member" }, "email": { "type": "string", "title": "Email", "default": "" }, "role": { "$ref": "#/components/schemas/GatewayInviteRole", "default": "member" }, "editable": { "type": "boolean", "title": "Editable", "default": true } }, "type": "object", "required": [ "id", "created_at", "reasoning" ], "title": "AgentActivityThreadGatewayInviteMember" }, "AgentActivityThreadGatewayStopExecution": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "stop_execution", "title": "Action", "default": "stop_execution" }, "created_execution_id": { "type": "string", "title": "Created Execution Id" } }, "type": "object", "required": [ "id", "created_at", "reasoning", "created_execution_id" ], "title": "AgentActivityThreadGatewayStopExecution" }, "AgentActivityThreadGatewaySuggestTool": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "reasoning": { "type": "string", "title": "Reasoning" }, "title": { "type": "string", "title": "Title", "default": "" }, "description": { "type": "string", "title": "Description", "default": "" }, "action": { "type": "string", "const": "suggest_tool", "title": "Action", "default": "suggest_tool" }, "suggestions": { "items": { "$ref": "#/components/schemas/GatewaySuggestedTool" }, "type": "array", "title": "Suggestions", "default": [] }, "allow_custom_mcp": { "type": "boolean", "title": "Allow Custom Mcp", "default": false }, "folded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Folded" } }, "type": "object", "required": [ "id", "created_at", "reasoning" ], "title": "AgentActivityThreadGatewaySuggestTool" }, "AgentActivityThreadInlineCard": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "card_id": { "type": "string", "title": "Card Id" }, "kind": { "type": "string", "title": "Kind", "default": "" }, "title": { "type": "string", "title": "Title", "default": "" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "manifest": { "additionalProperties": true, "type": "object", "title": "Manifest" }, "interaction": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Interaction" } }, "type": "object", "required": [ "id", "created_at", "card_id", "manifest" ], "title": "AgentActivityThreadInlineCard", "description": "An inline chat card (live-surface-styled manifest rendered in the message flow, not\nopenable). Upserted by card_id so a build's progress card updates in place and survives\nreload / conversation switches." }, "AgentActivityThreadInviteMemberResolved": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "decision_id": { "type": "string", "title": "Decision Id" }, "email": { "type": "string", "title": "Email" }, "role": { "$ref": "#/components/schemas/GatewayInviteRole", "default": "member" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "created_at", "decision_id", "email" ], "title": "AgentActivityThreadInviteMemberResolved", "description": "The user's resolved confirmation for a prior invite_member card.\n\nPersisted as its own activity entry (links via `decision_id`) so the card\nlocks on reload; the invite itself happens in the chat-backend route." }, "AgentActivityThreadLiveSurface": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "surface_id": { "type": "string", "title": "Surface Id" }, "title": { "type": "string", "title": "Title", "default": "" }, "surface_kind": { "type": "string", "title": "Surface Kind", "default": "manifest" }, "cdn_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cdn Url" }, "manifest": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Manifest" } }, "type": "object", "required": [ "id", "created_at", "surface_id" ], "title": "AgentActivityThreadLiveSurface", "description": "A Live Surface the agent generated; rendered as an in-chat preview (one-liner teaser) the user\nopens full screen. Persisted on the thread so it survives the closed async stream + reload, and so\nmultiple surfaces in one conversation each get their own preview." }, "AgentActivityThreadMessage": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "role": { "type": "string", "enum": [ "user", "agent" ], "title": "Role" }, "content": { "$ref": "#/components/schemas/AgentActivityThreadMessageContent" }, "sub_execution_result": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sub Execution Result", "default": false }, "is_steering": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Steering", "default": false }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] }, "identity": { "anyOf": [ { "$ref": "#/components/schemas/MessageIdentity" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "created_at", "role", "content" ], "title": "AgentActivityThreadMessage" }, "AgentActivityThreadMessageContent": { "properties": { "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" }, "files": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Files", "default": [] } }, "type": "object", "title": "AgentActivityThreadMessageContent" }, "AgentActivityThreadPlanUpdate": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "enforce": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce", "default": false }, "started": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Started", "default": false }, "question_raised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Question Raised", "default": false }, "tasks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DeepPlanningItem" }, "type": "array" }, { "type": "null" } ], "title": "Tasks", "default": [] }, "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } }, "type": "object", "required": [ "id", "created_at" ], "title": "AgentActivityThreadPlanUpdate" }, "AgentActivityThreadReasoning": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "type": { "$ref": "#/components/schemas/AgentActivityThreadReasoningType" }, "title": { "type": "string", "title": "Title" }, "confidence": { "type": "number", "title": "Confidence" }, "thought": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thought" }, "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "analysis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "plan_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Task Id" } }, "type": "object", "required": [ "id", "created_at", "type", "title", "confidence" ], "title": "AgentActivityThreadReasoning" }, "AgentActivityThreadReasoningType": { "type": "string", "enum": [ "think", "analyze" ], "title": "AgentActivityThreadReasoningType" }, "AgentActivityThreadSubAgentTrigger": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "type": "string", "title": "Agent Id" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "files": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Files", "default": [] }, "reasoning": { "$ref": "#/components/schemas/ToolCallRequestReasoning" }, "plan_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Task Id" } }, "type": "object", "required": [ "id", "created_at", "agent_id", "reasoning" ], "title": "AgentActivityThreadSubAgentTrigger" }, "AgentActivityThreadTaskCompactizationEvent": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "type": { "type": "string", "enum": [ "retry", "summarization", "compaction_started", "compaction_progress", "manual_compaction", "emergency_compaction", "pre_retry_compaction", "compaction_error" ], "title": "Type" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/TaskCompactizationOutput" }, { "$ref": "#/components/schemas/TaskCompactizationRetryEvent" }, { "$ref": "#/components/schemas/TaskCompactizationStarted" }, { "$ref": "#/components/schemas/TaskCompactizationProgress" }, { "$ref": "#/components/schemas/TaskCompactizationError" } ], "title": "Data" } }, "type": "object", "required": [ "id", "created_at", "type", "data" ], "title": "AgentActivityThreadTaskCompactizationEvent" }, "AgentActivityThreadToolCall": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "tool_name": { "type": "string", "title": "Tool Name" }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "payload": { "title": "Payload" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Error", "default": false }, "reasoning": { "anyOf": [ { "$ref": "#/components/schemas/ToolCallRequestReasoning" }, { "type": "null" } ] }, "result": { "anyOf": [ {}, { "type": "null" } ], "title": "Result" }, "plan_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Task Id" } }, "type": "object", "required": [ "id", "created_at", "tool_name", "payload" ], "title": "AgentActivityThreadToolCall" }, "AgentActivityThreadToolSuggestionResolved": { "properties": { "id": { "type": "string", "title": "Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "decision_id": { "type": "string", "title": "Decision Id" }, "choice": { "$ref": "#/components/schemas/ToolSuggestionChoice" }, "tool_name": { "type": "string", "title": "Tool Name", "default": "" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "created_at", "decision_id", "choice" ], "title": "AgentActivityThreadToolSuggestionResolved", "description": "The user's resolved choice for a prior suggest_tool card.\n\nPersisted as its own activity entry (links via `decision_id`) so the card\nlocks on reload; the attach itself happens in the chat-backend route." }, "AgentBudget-Input": { "properties": { "amount_usd": { "type": "number", "title": "Amount Usd" }, "period": { "$ref": "#/components/schemas/BudgetPeriod", "default": "monthly" }, "stop_mode": { "$ref": "#/components/schemas/BudgetStopMode", "default": "finish_inflight" }, "thresholds": { "items": { "$ref": "#/components/schemas/BudgetThreshold" }, "type": "array", "title": "Thresholds", "default": [] }, "notify": { "anyOf": [ { "$ref": "#/components/schemas/BudgetNotify-Input" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount_usd" ], "title": "AgentBudget", "description": "Recurring spend cap for an agent over a period. Multiple allowed (e.g. $5/day and $100/month)." }, "AgentBudget-Output": { "properties": { "amount_usd": { "type": "number", "title": "Amount Usd" }, "period": { "$ref": "#/components/schemas/BudgetPeriod", "default": "monthly" }, "stop_mode": { "$ref": "#/components/schemas/BudgetStopMode", "default": "finish_inflight" }, "thresholds": { "items": { "$ref": "#/components/schemas/BudgetThreshold" }, "type": "array", "title": "Thresholds", "default": [] }, "notify": { "anyOf": [ { "$ref": "#/components/schemas/BudgetNotify-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount_usd" ], "title": "AgentBudget", "description": "Recurring spend cap for an agent over a period. Multiple allowed (e.g. $5/day and $100/month)." }, "AgentDefinition": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "default": "" }, "unique_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unique Name", "default": "" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "default": "🚀" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "default": "male-avatar" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ] }, "prompts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompts", "default": [] }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "default": [] }, "attached_tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Connector" }, "type": "array" }, { "type": "null" } ], "title": "Attached Tools", "default": [] }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "default": "organizational" }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "default": { "role": [], "goal": [], "general": "" } }, "oas": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Oas", "default": {} }, "graph": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentGraphItem-Output" }, "type": "array" }, { "type": "null" } ], "title": "Graph", "default": [] }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "default": "ACTIVE" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "default": 1 }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "default": "openai" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "default": "gpt-5.2" }, "custom_functions": { "items": { "$ref": "#/components/schemas/CustomFunction" }, "type": "array", "title": "Custom Functions" }, "connectors": { "items": { "$ref": "#/components/schemas/ConnectedConnector" }, "type": "array", "title": "Connectors" }, "sub_agents": { "items": { "$ref": "#/components/schemas/AgentDefinition" }, "type": "array", "title": "Sub Agents", "default": [] }, "knowledge_bases": { "items": { "$ref": "#/components/schemas/ExportedKnowledgeBase" }, "type": "array", "title": "Knowledge Bases", "default": [] } }, "type": "object", "required": [ "id", "name", "custom_functions", "connectors" ], "title": "AgentDefinition" }, "AgentExecution": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "organization_id": { "type": "string", "title": "Organization Id" }, "input": { "$ref": "#/components/schemas/AgentExecutionInput-Output" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/xpander_dev_utils__models__executions__AgentExecutionStatus" }, { "type": "null" } ], "default": "pending" }, "internal_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Status" }, "last_executed_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Executed Node Id" }, "agent_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Version" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "paused_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Paused At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "parent_execution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Execution" }, "sub_executions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sub Executions", "default": [] }, "finished_sub_executions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Finished Sub Executions", "default": [] }, "should_update_parent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Update Parent", "default": false }, "is_manually_stopped": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Manually Stopped", "default": false }, "is_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Background", "default": false }, "payload_extension": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload Extension" }, "hitl_request": { "anyOf": [ { "$ref": "#/components/schemas/HumanInTheLoopRequest" }, { "type": "null" } ] }, "pending_eca_request": { "anyOf": [ { "$ref": "#/components/schemas/PendingECARequest" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "worker_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worker Id" }, "additional_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Additional Context" }, "instructions_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions Override" }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output" }, "test_run_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Test Run Node Id" }, "is_orchestration": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Orchestration", "default": false }, "is_gateway": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Gateway", "default": false }, "is_app": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is App", "default": false }, "sub_tasks_mode": { "anyOf": [ { "$ref": "#/components/schemas/SubTasksMode" }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "events_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Events Streaming", "default": false }, "used_mutating_tools": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Used Mutating Tools", "default": false }, "is_continuous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Continuous", "default": false }, "mcp_servers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers", "default": [] }, "triggering_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggering Agent Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "think_mode": { "anyOf": [ { "$ref": "#/components/schemas/ThinkMode" }, { "type": "null" } ], "default": "default" }, "disable_attachment_injection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Disable Attachment Injection", "default": false }, "deep_planning": { "anyOf": [ { "$ref": "#/components/schemas/DeepPlanning" }, { "type": "null" } ] }, "must_deep_plan": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Must Deep Plan", "default": false }, "execution_attempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Execution Attempts", "default": 1 }, "user_tokens": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Tokens" }, "user_oidc_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Oidc Token" }, "return_metrics": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Metrics", "default": false }, "tokens": { "anyOf": [ { "$ref": "#/components/schemas/LLMTokens" }, { "type": "null" } ] }, "llm_model_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Provider", "description": "Snapshot of the LLM provider used for this execution (request override or agent default at run time)." }, "llm_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Name", "description": "Snapshot of the LLM model name used for this execution (request override or agent default at run time)." }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Snapshot of the reasoning effort applied during this execution, when supported by the model." } }, "type": "object", "required": [ "id", "agent_id", "organization_id", "input", "created_at" ], "title": "AgentExecution" }, "AgentExecutionInput-Input": { "properties": { "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "default": "" }, "files": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Files", "default": [] }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Input" }, { "type": "null" } ] } }, "type": "object", "title": "AgentExecutionInput" }, "AgentExecutionInput-Output": { "properties": { "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "default": "" }, "files": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Files", "default": [] }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User-Output" }, { "type": "null" } ] } }, "type": "object", "title": "AgentExecutionInput" }, "AgentExecutionRequest": { "properties": { "input": { "$ref": "#/components/schemas/AgentExecutionInput-Input" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "payload_extension": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload Extension" }, "parent_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Execution Id" }, "worker_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worker Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ] }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "run_locally": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Run Locally", "default": false }, "additional_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Additional Context" }, "instructions_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions Override" }, "test_run_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Test Run Node Id" }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output" }, "events_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Events Streaming", "default": false }, "mcp_servers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers", "default": [] }, "triggering_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggering Agent Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "think_mode": { "anyOf": [ { "$ref": "#/components/schemas/ThinkMode" }, { "type": "null" } ], "default": "default" }, "disable_attachment_injection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Disable Attachment Injection", "default": false }, "user_tokens": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Tokens" }, "user_oidc_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Oidc Token" }, "return_metrics": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Metrics", "default": false }, "llm_model_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Provider", "description": "Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset." }, "llm_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Name", "description": "Per-execution override for the LLM model name. Falls back to the agent's configured model when unset." }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Per-execution override for reasoning effort on reasoning-capable models." }, "source_node_type": { "anyOf": [ { "$ref": "#/components/schemas/SourceNodeType" }, { "type": "null" } ], "description": "Surface that created this execution (mirrored to AgentExecutionHistory.source_node_type). Falls back to SourceNodeType.SDK at persist time when unset." }, "is_app": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is App", "default": false }, "is_steering": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Steering", "default": false }, "sub_tasks_mode": { "anyOf": [ { "$ref": "#/components/schemas/SubTasksMode" }, { "type": "null" } ], "description": "Forces gateway sub-task dispatch: 'sync' runs all downstream sub-tasks inline, 'async' queues them all, 'auto' restores the computed per-sub-task decision." } }, "type": "object", "required": [ "input" ], "title": "AgentExecutionRequest" }, "AgentExecutionStatus-Input": { "type": "string", "enum": [ "pending", "executing", "paused", "error", "failed", "completed", "stopped" ], "title": "AgentExecutionStatus" }, "AgentKnowledgeBase": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "strategy": { "$ref": "#/components/schemas/KnowledgeBaseStrategy" }, "rw": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Rw", "default": false }, "documents": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Documents", "default": [] } }, "type": "object", "required": [ "id", "strategy" ], "title": "AgentKnowledgeBase" }, "AgentStatus": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "INACTIVE" ], "title": "AgentStatus", "description": "Enumeration of possible agent statuses.\n\nAttributes:\n DRAFT: Agent is in a draft state.\n ACTIVE: Agent is active and operational.\n INACTIVE: Agent is inactive and not operational." }, "AgentTemplate": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "type": "string", "title": "Icon" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" }, "agent_definition": { "anyOf": [ { "$ref": "#/components/schemas/AgentDefinition" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "name", "icon" ], "title": "AgentTemplate" }, "AgentTool": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable handle for this attached tool. Pass it to DELETE to remove the tool." }, "type": { "$ref": "#/components/schemas/AgentToolType", "description": "The kind of attached tool." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable tool name." }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id", "description": "Connector connection id. Actions only." }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id", "description": "Operation catalog id. Actions only." }, "operation_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Name", "description": "OpenAPI operationId. Actions only." }, "use_mock": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Mock", "description": "Operation serves AI-generated mock data instead of the real API. Actions only." }, "custom_function_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Function Id", "description": "Custom function id. Custom functions only." }, "mcp_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Id", "description": "MCP registry id. MCP only." }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "description": "Subset of MCP tools exposed. MCP only." }, "mcp_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Url", "description": "MCP server url. MCP only." }, "mcp_auth_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Auth Type", "description": "MCP auth type (api_key/oauth2/custom_headers/none). MCP only." }, "mcp_registry_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Registry Id", "description": "Registry entry id when this MCP is attached from the shared org registry (editing it affects every agent). Absent for inline MCPs. MCP only." }, "mcp_transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Transport", "description": "MCP transport (streamable-http/sse/stdio). MCP only." }, "mcp_headers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Headers", "description": "Custom header names configured on the MCP (keys only; values are never returned). MCP only." }, "mcp_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Client Id", "description": "OAuth2 client id for the MCP, if set. MCP only." }, "mcp_additional_scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Additional Scopes", "description": "Extra OAuth2 scopes for the MCP. MCP only." }, "mcp_share_user_token": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mcp Share User Token", "description": "Whether the authorized MCP token is shared across the org's other agents. MCP only." }, "mcp_has_api_key": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mcp Has Api Key", "description": "Whether an API key is stored for the MCP (the value is never returned). MCP only." }, "mcp_has_client_secret": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mcp Has Client Secret", "description": "Whether an OAuth2 client secret is stored for the MCP (the value is never returned). MCP only." }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id", "description": "Referenced sub-agent or workflow id." }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name", "description": "Skill name from the xpander skills catalog. Skills only." } }, "type": "object", "required": [ "id", "type" ], "title": "AgentTool", "description": "A tool attached to an agent — the simplified, unified view of one graph entry." }, "AgentToolType": { "type": "string", "enum": [ "action", "custom_function", "mcp", "agent", "workflow", "skill" ], "title": "AgentToolType", "description": "Type of a tool attached to an agent." }, "AgentType": { "type": "string", "enum": [ "manager", "regular", "a2a", "curl", "orchestration" ], "title": "AgentType", "description": "Enumeration of the agent types.\n\nAttributes:\n Manager: marks the agent as a Managing agent.\n Regular: marks the agent as a regular agent.\n A2A: marks the agent as an external agent used via A2A protocol.\n Curl: marks the agent as an external agent used via a CURL.\n Orchestration: marks the agent as an Orchestration object." }, "AgnoSettings": { "properties": { "session_storage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Session Storage", "default": true }, "learning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Learning", "default": false }, "agent_memories": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agent Memories", "default": false }, "agentic_culture": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agentic Culture", "default": false }, "user_memories": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "User Memories", "default": false }, "agentic_memory": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agentic Memory", "default": false }, "session_summaries": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Session Summaries", "default": false }, "num_history_runs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num History Runs", "default": 50 }, "max_tool_calls_from_history": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tool Calls From History", "default": 0 }, "tool_call_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tool Call Limit", "default": 0 }, "coordinate_mode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Coordinate Mode", "default": true }, "pii_detection_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pii Detection Enabled", "default": false }, "pii_detection_mask": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Pii Detection Mask", "default": true }, "prompt_injection_detection_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Prompt Injection Detection Enabled", "default": false }, "openai_moderation_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Openai Moderation Enabled", "default": false }, "openai_moderation_categories": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Openai Moderation Categories" }, "reasoning_tools_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Reasoning Tools Enabled", "default": true }, "max_plan_retries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Plan Retries", "default": 15 } }, "type": "object", "title": "AgnoSettings" }, "AskUserQuestionAnswer": { "properties": { "question_id": { "type": "string", "title": "Question Id" }, "selected_option_ids": { "items": { "type": "string" }, "type": "array", "title": "Selected Option Ids" }, "free_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Free Text" } }, "type": "object", "required": [ "question_id" ], "title": "AskUserQuestionAnswer", "description": "The user's answer to one question." }, "AskUserQuestionsSubmission": { "properties": { "decision_id": { "type": "string", "title": "Decision Id", "description": "Id of the AskUserQuestions activity entry being answered." }, "answers": { "items": { "$ref": "#/components/schemas/AskUserQuestionAnswer" }, "type": "array", "title": "Answers" }, "user": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User" } }, "type": "object", "required": [ "decision_id", "answers" ], "title": "AskUserQuestionsSubmission", "description": "Body of the chat-backend answers endpoint." }, "BashRequest": { "properties": { "command": { "type": "string", "title": "Command", "description": "Shell command to execute inside the workspace. Supports installing packages (apt-get, pip, npm), running scripts, and general shell operations.", "examples": [ "pip install pandas && python -c 'import pandas; print(pandas.__version__)'" ] }, "timeout": { "type": "integer", "maximum": 1800.0, "minimum": 1.0, "title": "Timeout", "description": "Maximum execution time in seconds. The command is killed if it exceeds this limit.", "default": 300, "examples": [ 60 ] }, "working_dir": { "type": "string", "title": "Working Dir", "description": "Working directory for the command, relative to workspace root. Defaults to the workspace root.", "default": "", "examples": [ "my_project" ] } }, "type": "object", "required": [ "command" ], "title": "BashRequest" }, "BashResponse": { "properties": { "stdout": { "type": "string", "title": "Stdout", "description": "Standard output captured from the command", "default": "", "examples": [ "2.2.0\n" ] }, "stderr": { "type": "string", "title": "Stderr", "description": "Standard error captured from the command", "default": "", "examples": [ "" ] }, "exit_code": { "type": "integer", "title": "Exit Code", "description": "Process exit code. 0 indicates success, non-zero indicates failure.", "default": 0, "examples": [ 0 ] }, "duration": { "type": "number", "title": "Duration", "description": "Execution duration in seconds", "default": 0.0, "examples": [ 3.21 ] } }, "type": "object", "title": "BashResponse" }, "BudgetAction": { "type": "string", "enum": [ "warn", "stop" ], "title": "BudgetAction", "description": "What happens when a threshold is crossed. Open set — V2 may add approve/throttle/downgrade." }, "BudgetNotify-Input": { "properties": { "channels": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "Channels" }, "max_notifications_per_period": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Notifications Per Period", "default": 3 } }, "type": "object", "title": "BudgetNotify", "description": "Per-budget notification overrides; unset falls back to the agent's on_budget settings." }, "BudgetNotify-Output": { "properties": { "channels": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "Channels" }, "max_notifications_per_period": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Notifications Per Period", "default": 3 } }, "type": "object", "title": "BudgetNotify", "description": "Per-budget notification overrides; unset falls back to the agent's on_budget settings." }, "BudgetPeriod": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "title": "BudgetPeriod", "description": "Recurring window an agent budget resets over." }, "BudgetSettings-Input": { "properties": { "agent_budgets": { "items": { "$ref": "#/components/schemas/AgentBudget-Input" }, "type": "array", "title": "Agent Budgets", "default": [] }, "task_budget": { "anyOf": [ { "$ref": "#/components/schemas/TaskBudget-Input" }, { "type": "null" } ] } }, "type": "object", "title": "BudgetSettings", "description": "Budget configuration embedded in an agent's task_level_strategies." }, "BudgetSettings-Output": { "properties": { "agent_budgets": { "items": { "$ref": "#/components/schemas/AgentBudget-Output" }, "type": "array", "title": "Agent Budgets", "default": [] }, "task_budget": { "anyOf": [ { "$ref": "#/components/schemas/TaskBudget-Output" }, { "type": "null" } ] } }, "type": "object", "title": "BudgetSettings", "description": "Budget configuration embedded in an agent's task_level_strategies." }, "BudgetStopMode": { "type": "string", "enum": [ "finish_inflight", "kill_inflight" ], "title": "BudgetStopMode", "description": "How a stop applies to a task that is already running." }, "BudgetThreshold": { "properties": { "percent": { "type": "number", "maximum": 100.0, "exclusiveMinimum": 0.0, "title": "Percent" }, "action": { "$ref": "#/components/schemas/BudgetAction", "default": "warn" } }, "type": "object", "required": [ "percent" ], "title": "BudgetThreshold", "description": "A spend percentage that triggers an action when first crossed in a period." }, "ClassificationGroup": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "evaluation_criteria": { "type": "string", "title": "Evaluation Criteria" }, "auto_extract_relevant_data": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Extract Relevant Data", "default": false }, "data_extraction_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Data Extraction Keys" } }, "type": "object", "required": [ "name", "evaluation_criteria" ], "title": "ClassificationGroup", "description": "A classification group with evaluation criteria and data extraction settings.\n\nAttributes:\n id: Unique identifier for the group (UUID).\n name: Human-readable name for the group.\n evaluation_criteria: Instructions for when this group should match.\n auto_extract_relevant_data: Whether to automatically extract relevant data for this group.\n data_extraction_keys: Specific JSON paths/keys to extract from input (alternative to auto_extract)." }, "ConnectConnectorRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for this connection. Must be descriptive enough to distinguish from other connections to the same connector (e.g., 'Production Slack', 'Staging Jira')." }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "Pin this connection to a specific connector version. Leave None to use the connector's latest version." }, "security": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Security", "description": "Authentication credentials for this connection (WRITE-ONLY — never returned in responses). Structure depends on the connector's auth type: API key auth: {'authMethod': 'apiKey', 'apiKey': '...', 'headerName': 'X-API-Key'}. OAuth2: {'authMethod': 'oauth2', 'oauth2Token': {...}}." }, "general_params": { "anyOf": [ { "items": { "$ref": "#/components/schemas/GeneralParam" }, "type": "array" }, { "type": "null" } ], "title": "General Params", "description": "Pre-filled parameters applied to all operations through this connection. Useful for setting common path/query/header params like workspace IDs or API versions.", "default": [] }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Custom HTTP headers to include in all API calls through this connection (WRITE-ONLY — never returned in responses). Used for additional authentication or routing headers." }, "target_system_servers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Target System Servers", "description": "Override the connector's default server URLs. Each entry should have a 'url' field and optional 'description'. Use this to point the connection at a different environment (e.g., staging vs production).", "default": [] }, "access_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Scope", "description": "Who can use this connection. 'personal' (default) restricts to the creating user. 'organizational' makes it available to all org members.", "default": "personal" }, "is_service_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Service Account", "description": "Set to True if this connection uses shared service account credentials rather than personal user credentials. Only meaningful with 'organizational' access scope.", "default": false }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner", "description": "User id that owns a personal connection. Set for personal scope; omit (None) for organizational connections." } }, "type": "object", "required": [ "name" ], "title": "ConnectConnectorRequest", "description": "Request model for creating a new connection to a connector.\n\nA connection binds a connector to your organization with specific\nauthentication credentials and settings. The `security` and `headers`\nfields are write-only — they are accepted on create but never returned\nin any response for security reasons.\n\nFor OAuth2 connectors, the API may return an oauth2_required response\nwith a URL to complete browser-based authentication." }, "ConnectedConnector": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "default": "" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "default": "" }, "open_api_spec_id": { "type": "string", "title": "Open Api Spec Id" }, "general_params": { "anyOf": [ { "items": { "$ref": "#/components/schemas/GeneralParam" }, "type": "array" }, { "type": "null" } ], "title": "General Params", "default": [] }, "operation_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Operation Ids", "default": [] }, "operations_with_details": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Operations With Details", "default": [] }, "cc_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cc Id" }, "root_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Id" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "openapi_spec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Openapi Spec" }, "is_custom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Custom", "default": false }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "version": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Version" }, "total_operations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Operations" }, "operations_map": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/ConnectorOperation" }, "type": "object" }, { "type": "null" } ], "title": "Operations Map" } }, "type": "object", "required": [ "id", "open_api_spec_id" ], "title": "ConnectedConnector" }, "ConnectionSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of this connection. Use this ID when referencing the connection in operations or agent tool configuration." }, "name": { "type": "string", "title": "Name", "description": "Human-readable name for this connection instance (e.g., 'Production Slack', 'Dev Jira')." }, "access_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Scope", "description": "Who can use this connection. 'organizational' is visible to all org members. 'personal' is only visible to the connection owner." }, "is_service_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Service Account", "description": "Whether this connection uses a service account (shared org-level credentials) rather than personal user credentials.", "default": false }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner", "description": "User ID of the connection owner. Only relevant for personal connections." }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "The connector version this connection is pinned to. May differ from the connector's latest version." }, "open_api_spec_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Open Api Spec Id", "description": "OpenAPI spec ID this connection uses. May differ from the connector's default spec if the connection is pinned to a specific version." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Connection status ('ready' means authorized/usable)." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Optional creation date of the connection." } }, "type": "object", "required": [ "id", "name" ], "title": "ConnectionSummary", "description": "Lightweight summary of a connector connection (org↔connector binding).\n\nReturned as part of ConnectorItem.connections when listing connectors.\nEach connection represents a configured instance of a connector within\nan organization, with its own authentication and settings." }, "Connector": { "properties": { "id": { "type": "string", "title": "Id" }, "operation_ids": { "items": { "type": "string" }, "type": "array", "title": "Operation Ids" } }, "type": "object", "required": [ "id", "operation_ids" ], "title": "Connector", "description": "Connector model representing the structure of a connector with an ID and associated operation IDs.\n\nAttributes:\n id (str): The unique identifier for the connector.\n operation_ids (list[str]): A list of operation IDs associated with the connector." }, "ConnectorOperation": { "properties": { "path": { "type": "string", "title": "Path" }, "method": { "type": "string", "title": "Method" } }, "type": "object", "required": [ "path", "method" ], "title": "ConnectorOperation" }, "ConnectorOperationItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for this operation. Use this as item_id when adding the operation to an agent's tool graph." }, "operationId": { "type": "string", "title": "Operationid", "description": "The OpenAPI operationId — a stable, human-readable identifier for this endpoint (e.g., 'sendMessage', 'createIssue')." }, "path": { "type": "string", "title": "Path", "description": "API endpoint path (e.g., '/api/v1/messages', '/rest/api/3/issue'). May contain path parameters in {brackets}." }, "method": { "type": "string", "title": "Method", "description": "HTTP method for this operation (GET, POST, PUT, DELETE, PATCH)." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Brief one-line summary of what this operation does." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Detailed description of the operation, including parameters, behavior, and response format." }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Categorization tags for grouping related operations (e.g., 'Messages', 'Users', 'Issues').", "default": [] }, "pretty_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pretty Name", "description": "Human-friendly name for the operation (e.g., 'Send Message', 'Create Issue'). More readable than the operationId." }, "pretty_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pretty Description", "description": "Enhanced description of the operation, potentially AI-generated for better clarity." } }, "type": "object", "required": [ "id", "operationId", "path", "method" ], "title": "ConnectorOperationItem", "description": "An available API operation (endpoint) within a connector.\n\nOperations are the individual API actions you can perform through a\nconnector (e.g., 'Send Slack message', 'Create Jira issue'). Each\noperation maps to an endpoint in the connector's OpenAPI specification.\n\nTo add an operation to an agent's tool graph, use the operation's `id`\nas the `item_id` in an AIAgentGraphItem." }, "ContextStatus": { "properties": { "estimated_tokens": { "type": "integer", "title": "Estimated Tokens", "description": "Rough token count of the current message list (post-Layer-1 microcompaction)." }, "context_window": { "type": "integer", "title": "Context Window", "description": "Model context window size in tokens." }, "percent": { "type": "number", "title": "Percent", "description": "estimated_tokens / context_window * 100, clamped to [0, 100]." }, "auto_compact_threshold": { "type": "integer", "title": "Auto Compact Threshold", "description": "Token level at which Layer 2 auto-compaction fires." }, "emergency_threshold": { "type": "integer", "title": "Emergency Threshold", "description": "Token level at which the emergency safety net (88%) fires." }, "compacting": { "type": "boolean", "title": "Compacting", "description": "True while a Layer 2 compaction is in flight on the current turn.", "default": false } }, "type": "object", "required": [ "estimated_tokens", "context_window", "percent", "auto_compact_threshold", "emergency_threshold" ], "title": "ContextStatus", "description": "Per-turn snapshot of the LLM context window for the chat UI indicator." }, "ConversationResponse": { "properties": { "conversation_id": { "type": "string", "title": "Conversation Id" }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/AgentExecution" }, { "type": "null" } ], "description": "Parent gateway execution row (status, result, sub_executions, deep_planning, …)." }, "activity": { "anyOf": [ { "$ref": "#/components/schemas/AgentActivityThread" }, { "type": "null" } ], "description": "Ordered message list (user, agent, tool calls, reasoning, …)." }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ConversationUsage" }, { "type": "null" } ], "description": "Aggregate cost + token usage over parent + every sub-execution. Best-effort." }, "sub_executions": { "items": { "$ref": "#/components/schemas/SubExecutionResponse" }, "type": "array", "title": "Sub Executions", "description": "Triple-shape entry for every sub-execution spawned by this conversation." }, "feedbacks": { "items": { "$ref": "#/components/schemas/MessageFeedbackItem" }, "type": "array", "title": "Feedbacks", "description": "Per-message feedback rows recorded against the parent execution." } }, "type": "object", "required": [ "conversation_id" ], "title": "ConversationResponse", "description": "Combined view of one chat conversation.\n\n`conversation_id` is the parent gateway execution id, which is also the\nactivity-thread id. `execution`, `activity`, and `usage` can each be\nindependently `None` when the upstream is unavailable — the route returns\n404 only when BOTH `execution` AND `activity` are missing.\n\n`usage` at this root level is aggregated across the parent execution\nAND every entry in `sub_executions` (single upstream call to the\n`llm_usage:aggregate` endpoint). Per-sub usage is mirrored on each\n`SubExecutionResponse.usage` so clients don't have to fan-out." }, "ConversationState": { "type": "string", "enum": [ "regular", "agent_building", "agent_updating" ], "title": "ConversationState", "description": "Lifecycle phase of a gateway conversation; drives UI affordance + gateway model selection." }, "ConversationTokens": { "properties": { "input": { "type": "integer", "title": "Input", "default": 0 }, "output": { "type": "integer", "title": "Output", "default": 0 }, "cache_read": { "type": "integer", "title": "Cache Read", "default": 0 }, "cache_write": { "type": "integer", "title": "Cache Write", "default": 0 }, "total": { "type": "integer", "title": "Total", "default": 0 } }, "type": "object", "title": "ConversationTokens", "description": "Aggregated token counts across every execution in the thread.\n\n`input` excludes every cache bucket (raw uncached prompt volume);\n`total` = input + cache_read + cache_write + output, i.e. real volume,\nnot the billable cache-weighted figure (that lives in `usage.cost`)." }, "ConversationUsage": { "properties": { "cost": { "type": "number", "title": "Cost", "description": "Estimated USD cost for non-BYOK executions in this thread, rounded to 5 decimals. Excludes BYOK executions (the customer is billed by their own LLM provider for those).", "default": 0.0 }, "is_byok": { "type": "boolean", "title": "Is Byok", "description": "True if any execution in the thread used BYOK credentials.", "default": false }, "actions": { "type": "integer", "title": "Actions", "description": "Total number of agent actions (tool calls) across the thread.", "default": 0 }, "ai_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Model", "description": "Dominant LLM model id used in the thread (the model that produced the most tokens). `None` when no executions have been recorded yet." }, "tokens": { "$ref": "#/components/schemas/ConversationTokens" } }, "type": "object", "title": "ConversationUsage", "description": "Cost + token usage for a conversation (or a single sub-execution).\n\nSourced from the same monitoring rollup the api service exposes at\n`/v1/tasks/{task_id}/llm_usage`. Flow:\n\n chat-backend → agent-controller (in-process call)\n → deployment-manager (`agents_activity_proxy`)\n → agents service (`/{agent_id}/activity/threads/llm_usage:aggregate`)\n → MongoDB monitoring docs + LLM tier table\n\nReturned with the conversation as a convenience so the UI doesn't\nhave to issue a second roundtrip per render." }, "CreateAgentRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for the agent. Must be unique within the organization. Examples: 'Customer Support Agent', 'Research Assistant'." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A brief description of what the agent does. Shown in agent listings and used by other agents when deciding delegation. Keep it concise and action-oriented.", "default": "" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Icon shown next to the agent name: the platform icon id (default 'xpi:workflow:dusk') or a single emoji character.", "default": "xpi:workflow:dusk" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "description": "Avatar identifier for the agent's visual representation in chat interfaces.", "default": "male-avatar" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ], "description": "The agent type. 'manager' is the standard type that supports tools, sub-agents, and multi-step execution. 'regular' is a simpler agent without orchestration capabilities. 'a2a' and 'curl' are for external agent integrations. 'orchestration' marks a workflow: create those through the Workflows API instead of setting it here.", "default": "manager" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "User ID of the creator. Auto-populated from the API key if not provided." }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "description": "The LLM provider for this agent's reasoning. Must match an available provider from GET /llm_providers. Common values: 'anthropic' (default), 'openai', 'gemini'. Omit it together with model_name to follow the organization's default LLM.", "default": "anthropic" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "The specific model identifier within the chosen provider. Must match a model from GET /llm_providers/{provider}/models. Examples: 'claude-sonnet-5', 'gpt-4o', 'gemini-2.0-flash'.", "default": "claude-sonnet-5" }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Controls the depth of reasoning the LLM applies. 'low' for simple tasks, 'medium' for balanced performance, 'high' for complex reasoning, 'xhigh' for maximum reasoning depth (slower, more expensive).", "default": "medium" }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base", "description": "Custom API base URL for the LLM provider. Use this when connecting to a self-hosted or proxied LLM endpoint instead of the provider's default URL. Leave None to use the provider's standard endpoint." }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key", "description": "Reference key to stored LLM API credentials in the xpander.ai vault. When set, the agent uses these credentials instead of the organization's default. Create credentials via the platform settings." }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "description": "Type of credential storage. 'xpander' uses xpander.ai's built-in credential vault. 'custom' indicates externally managed credentials.", "default": "xpander" }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ], "description": "Direct LLM credentials object. Prefer using llm_credentials_key for secure credential management. Only use this for testing or when vault access is unavailable." }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "description": "Additional HTTP headers to include in every LLM API request. Useful for custom authentication, routing through gateways (e.g., Helicone, Cloudflare AI Gateway), or passing metadata.", "default": {} }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "description": "Structured instructions that define the agent's behavior. Contains 'role' (list of role descriptions), 'goal' (list of objectives), and 'general' (free-form instructions text). These are injected into the agent's system prompt." }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "description": "Description of the expected output format and content. Guides the agent on what the final response should look like. Used in the system prompt to set output expectations.", "default": "" }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "description": "The format for the agent's final response. 'markdown' for rich text, 'text' for plain text, 'json' for structured JSON output (pair with output_schema), 'voice' for speech synthesis.", "default": "markdown" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema defining the structure of the agent's output when output_format is 'json'. The agent will conform its response to match this schema. Must be a valid JSON Schema object." }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "description": "How the agent runs. 'external-harness' (default): a coding CLI (claude-code, codex or opencode, chosen by harness_settings.default_cli). 'agno': the built-in xpander loop. Legacy 'claude-code' / 'codex' values read as 'external-harness' with that CLI.", "default": "external-harness" }, "deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deep Planning", "description": "Enable deep planning mode where the agent creates a detailed execution plan before taking actions. Useful for complex multi-step tasks. Increases latency but improves accuracy on complex workflows.", "default": false }, "enforce_deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce Deep Planning", "description": "When True, forces the agent to always use deep planning regardless of task complexity. When False (default), the agent decides when to plan based on the task.", "default": false }, "tools": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/AddActionTool" }, { "$ref": "#/components/schemas/AddCustomFunctionTool" }, { "$ref": "#/components/schemas/AddMcpTool" }, { "$ref": "#/components/schemas/AddSubAgentTool" }, { "$ref": "#/components/schemas/AddWorkflowTool" }, { "$ref": "#/components/schemas/AddSkillTool" } ], "discriminator": { "propertyName": "type", "mapping": { "action": "#/components/schemas/AddActionTool", "agent": "#/components/schemas/AddSubAgentTool", "custom_function": "#/components/schemas/AddCustomFunctionTool", "mcp": "#/components/schemas/AddMcpTool", "skill": "#/components/schemas/AddSkillTool", "workflow": "#/components/schemas/AddWorkflowTool" } } }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "Tools to attach to the agent, in the unified simplified shape (the same payload as POST /v1/agents/{agent_id}/tools).\nThis is the preferred way to attach tools — the API resolves catalog ids and wires the graph for you.\n\nEach entry is one of (discriminated on `type`):\n- {\"type\": \"action\", \"connection_id\": \"\", \"operation_ids\": [\"\", ...]}\n- {\"type\": \"custom_function\", \"custom_function_id\": \"\"}\n- {\"type\": \"mcp\", \"mcp_id\": \"\"} OR {\"type\": \"mcp\", \"url\": \"https://...\", \"name\": \"...\", \"transport\": \"...\", \"auth_type\": \"...\", \"allowed_tools\": [...]}\n- {\"type\": \"agent\", \"agent_id\": \"\"}\n- {\"type\": \"workflow\", \"workflow_id\": \"\"}\n- {\"type\": \"skill\", \"skill_name\": \"\"}\n\nResolves into `attached_tools` + `graph` server-side, so you don't need to construct those by hand.\nFor advanced control you may still pass `attached_tools`/`graph` directly; when both are provided, `tools` are resolved and merged on top." }, "attached_tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Connector" }, "type": "array" }, { "type": "null" } ], "title": "Attached Tools", "description": "Advanced/low-level: list of connector connections with their operation IDs that this agent can use as tools. Prefer `tools` for the simplified shape.\nEach entry binds a connection (connector_organization) to specific operations the agent is allowed to invoke.\n\nStructure: [{\"id\": \"\", \"operation_ids\": [\"\", \"\"]}]\n- 'id' is the connection ID (connector_organization.id) from POST /connectors/{connector_id}/connect\n- 'operation_ids' are the catalog operation _id values from GET /connectors/{connector_id}/{connection_id}/operations\n\nIf you provide attached_tools without corresponding graph entries, the API will automatically create\ngraph items of type 'tool' for each operation, resolving catalog _id to operationId.\n\nSpecial cases:\n- Custom functions: use id=\"xpander-custom-functions\" and operation_ids=[\"\", ...]\n Custom function IDs are the function UUIDs, not catalog operation IDs.\n- Sub-agents: do NOT use attached_tools. Add sub-agents directly to the 'graph' field with type='agent'.\n- MCP servers: do NOT use attached_tools. Add MCP servers directly to the 'graph' field with type='mcp'.\n\nExample (connector operations):\n[{\"id\": \"770832b8-c32b-4e4c-9ca2-232fec8099a7\", \"operation_ids\": [\"694bddfcd72d937c39875cf7\"]}]\n\nExample (custom functions):\n[{\"id\": \"xpander-custom-functions\", \"operation_ids\": [\"my-function-uuid-1\", \"my-function-uuid-2\"]}]", "default": [] }, "graph": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentGraphItem-Input" }, "type": "array" }, { "type": "null" } ], "title": "Graph", "description": "The agent's tool graph — defines which tools are available to the LLM and their execution flow.\nEach graph item represents a tool the agent can call during task execution.\n\nFor connector operations (type='tool'):\n- item_id: the operationId string (e.g., 'XpanderEmailServiceSendEmailWithHtmlOrTextContent')\n- name: human-readable name shown to the LLM (e.g., 'Send Email')\n- type: 'tool'\n- targets: list of graph item IDs that should execute after this tool (empty [] for no chaining)\n- NOTE: auto-created from attached_tools if not provided\n\nFor sub-agents (type='agent'):\n- item_id: the agent ID (UUID) to delegate work to\n- name: display name of the sub-agent\n- type: 'agent'\n- NO attached_tools entry needed — sub-agents are graph-only\n\nFor custom functions (type='tool', sub_type='custom_function'):\n- item_id: the custom function UUID\n- name: function name\n- type: 'tool'\n- Requires attached_tools entry with id='xpander-custom-functions'\n\nFor MCP servers (type='mcp'):\n- item_id: a unique ID for this MCP server instance\n- name: display name of the MCP server\n- type: 'mcp'\n- settings.mcp_settings: {url, transport, auth_type, name, allowed_tools, ...}\n- NO attached_tools entry needed — MCP servers are graph-only\n\nNOTE: If you provide attached_tools with operation_ids but no corresponding graph items,\nthe API will auto-create graph items with resolved operationId and pretty_name from catalog.\n\nExamples:\nConnector tool: {\"item_id\": \"SlackPostMessage\", \"name\": \"Send Slack Message\", \"type\": \"tool\", \"targets\": []}\nSub-agent: {\"item_id\": \"agent-uuid-here\", \"name\": \"Research Agent\", \"type\": \"agent\", \"targets\": []}\nMCP server: {\"item_id\": \"mcp-uuid\", \"name\": \"Notion\", \"type\": \"mcp\", \"targets\": [], \"settings\": {\"mcp_settings\": {\"url\": \"https://mcp.notion.com/sse\", \"transport\": \"sse\", \"name\": \"Notion\"}}}", "default": [] }, "knowledge_bases": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentKnowledgeBase" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Bases", "description": "Knowledge bases attached to this agent for RAG (Retrieval-Augmented Generation). Each entry references a knowledge base by ID and specifies the retrieval strategy ('vanilla' for simple retrieval, 'agentic_rag' for agent-driven retrieval).", "default": [] }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "description": "Entry points that can trigger this agent. Defines how the agent can be invoked — via SDK, scheduled tasks, webhooks, assistant UI, MCP, A2A protocol, Telegram, or Slack.", "default": [] }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "description": "Where the agent runs. 'serverless' runs on xpander.ai's managed infrastructure (recommended). 'container' runs on your own infrastructure as a Docker container.", "default": "serverless" }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "description": "Who can access this agent. 'personal' restricts access to the creating user. 'organizational' makes it available to all organization members.", "default": "personal" }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id", "description": "Target deployment environment ID. Leave None for the organization's default environment. Use this to deploy agents to specific on-premise or regional environments." }, "connectivity_details": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2A" }, { "$ref": "#/components/schemas/AIAgentConnectivityDetailsCurl" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Connectivity Details", "description": "Connection details for external agent integrations (A2A protocol or CURL-based). Only relevant when type is 'a2a' or 'curl'. For standard agents, leave as empty dict.", "default": {} }, "agno_settings": { "anyOf": [ { "$ref": "#/components/schemas/AgnoSettings" }, { "type": "null" } ], "description": "Configuration specific to the Agno framework. Controls session storage, coordinate mode (multi-agent), learning, memory strategies, guardrails (PII detection, prompt injection), tool call limits, and plan retry strategies. Only applies when framework is 'agno'." }, "harness_settings": { "anyOf": [ { "$ref": "#/components/schemas/HarnessSettings" }, { "type": "null" } ], "description": "Runtime settings for an 'external-harness' agent: default CLI, per-CLI models, permission mode, parallel task limit, working-directory retention, approval hold, image tag and per-turn sandbox ceilings (resources). Ignored for 'agno'." }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Input" }, { "type": "null" } ], "description": "Execution strategies applied at the task level. Configure retry behavior (max retries), iterative execution (max iterations with stop conditions), stop strategies, daily run limits, and agentic context (persistent memory across runs)." }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Input" }, { "type": "null" } ], "description": "Notification configuration for task completion events. Define notifications to send on success or error via email, Slack, or webhook. Each channel supports custom subject, body, and branding." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice ID for text-to-speech output when output_format is 'voice'. References a voice profile in the platform's TTS service." }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "description": "Enable NVIDIA NeMo guardrails integration for this agent. Provides additional safety and content filtering capabilities.", "default": false }, "is_supervised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Supervised", "description": "Enable supervised mode where the agent requires human approval before executing mutating operations (write/update/delete). Non-mutating operations (read/search) execute automatically.", "default": false }, "is_autonomous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Autonomous", "description": "Run the agent in autonomous mode.", "default": false }, "discoverable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Discoverable", "description": "When True, the agent is exposed to agent-discovery surfaces (e.g. omni). When False, it is hidden from discovery and can only be invoked directly.", "default": true }, "with_auto_context_management": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "With Auto Context Management", "description": "When True, the SDK runs its automatic context optimizer (compaction). When False, context management is skipped.", "default": true }, "developer_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Developer Access", "description": "When True, the agent is reachable from the developer API and webhook entry points. When False, external API/webhook invocation is rejected.", "default": true }, "should_stage_before_publish": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Stage Before Publish", "description": "When True, edits are staged as a draft version before being published. When False, edits publish directly.", "default": true }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "description": "Enable real-time event streaming for on-premise deployments. When True, task progress events are streamed to connected clients.", "default": true }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "description": "Enable OIDC pre-authentication for this agent. When enabled, the agent requires a valid OIDC token from the invoking user before execution. Used for user-context-aware operations.", "default": false }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "description": "List of allowed OIDC token audiences for pre-authentication validation. Only tokens with matching audience claims are accepted.", "default": [] }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "description": "When True, the user's OIDC token is forwarded to the LLM provider for authenticated LLM calls. Requires use_oidc_pre_auth to be enabled.", "default": false }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience", "description": "The audience claim to request when exchanging the user's OIDC token for LLM provider access. Only used when use_oidc_pre_auth_token_for_llm is True." }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience", "description": "The audience claim to request when exchanging the user's OIDC token for MCP server access. Enables user-context-aware MCP tool execution." } }, "type": "object", "required": [ "name" ], "title": "CreateAgentRequest", "description": "Request model for creating a new AI agent on the xpander.ai platform.\n\nOnly `name` is required. All other fields have sensible defaults matching\nthe platform's standard agent configuration. The agent will be created\nwith type 'manager' by default, which supports tool use, sub-agent\ndelegation, and multi-step task execution.\n\nFields like `organization_id`, `id`, `status`, `version`, and other\nsystem-managed properties are set automatically by the platform and\nshould not be provided." }, "CreateCustomFunctionRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for the custom function. Used as the display name in the agent's tool list. Examples: 'Calculate Tax', 'Parse CSV Data'." }, "function_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Function Name", "description": "Optional programmatic function name. If not provided, defaults to 'xpander_run_action'. The source_code must define a function with this name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of what the function does. This is shown to the LLM when the function is used as an agent tool, so make it clear and action-oriented.", "default": "" }, "source_code": { "type": "string", "title": "Source Code", "description": "Python source code for the custom function. Must define a function called `xpander_run_action(...)` (or the name specified in function_name).\n\nThe function receives keyword arguments matching its parameter signature. It should return a dict or string result.\n\nExample:\n```python\ndef xpander_run_action(text: str, max_words: int = 100) -> dict:\n words = text.split()[:max_words]\n return {\"word_count\": len(words), \"truncated_text\": \" \".join(words)}\n```\n\nThe function runs in a secure Python 3.12 sandbox with common libraries available (requests, json, re, datetime, etc.).\nDo NOT use: file system access, subprocess, os.system, eval/exec, or network access to internal services." }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/CustomFunctionLimitsModel" }, { "type": "null" } ], "description": "Resource limits for the function execution. Currently only max_run_time (seconds) is supported." } }, "type": "object", "required": [ "name", "source_code" ], "title": "CreateCustomFunctionRequest", "description": "Request model for creating a new custom function.\n\nThe source code must define a function called `xpander_run_action(...)`.\nThis is the entry point that will be called when the function is invoked\nby an agent or via the execute endpoint.\n\nAfter creation, the function is automatically analyzed for:\n- Safety (no malicious patterns)\n- Input schema extraction (parameters are auto-detected)\n- Runnability (syntax validation)\n\nThe function status starts as 'analysing' and transitions to 'ready'\nonce analysis completes successfully." }, "CreateManagedKnowledgeBaseRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "KB name specified by the user" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "KB description specified by the user" } }, "type": "object", "required": [ "name" ], "title": "CreateManagedKnowledgeBaseRequest" }, "CreateScheduledTaskRequest": { "properties": { "cron": { "type": "string", "title": "Cron", "description": "Cron expression (5-field crontab, UTC), e.g. '0 9 * * *'." }, "prompt": { "type": "string", "title": "Prompt", "description": "Instruction the agent runs on each fire." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Optional human-readable label. Auto-generated from the prompt when omitted." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Create the task active (default) or paused.", "default": true }, "type": { "$ref": "#/components/schemas/ScheduledTaskType", "description": "Job kind — scheduled-job or live-surface.", "default": "scheduled-job" } }, "type": "object", "required": [ "cron", "prompt" ], "title": "CreateScheduledTaskRequest", "description": "Create a recurring scheduled task for an agent." }, "CreatedByDetails": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "id", "name", "email" ], "title": "CreatedByDetails" }, "CreatedTask": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "organization_id": { "type": "string", "title": "Organization Id" }, "input": { "$ref": "#/components/schemas/AgentExecutionInput-Output" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/xpander_dev_utils__models__executions__AgentExecutionStatus" }, { "type": "null" } ], "default": "pending" }, "internal_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Status" }, "last_executed_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Executed Node Id" }, "agent_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Version" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Started At" }, "paused_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Paused At" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "parent_execution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Execution" }, "sub_executions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sub Executions", "default": [] }, "finished_sub_executions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Finished Sub Executions", "default": [] }, "should_update_parent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Update Parent", "default": false }, "is_manually_stopped": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Manually Stopped", "default": false }, "is_background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Background", "default": false }, "payload_extension": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload Extension" }, "hitl_request": { "anyOf": [ { "$ref": "#/components/schemas/HumanInTheLoopRequest" }, { "type": "null" } ] }, "pending_eca_request": { "anyOf": [ { "$ref": "#/components/schemas/PendingECARequest" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "worker_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worker Id" }, "additional_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Additional Context" }, "instructions_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions Override" }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output" }, "test_run_node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Test Run Node Id" }, "is_orchestration": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Orchestration", "default": false }, "is_gateway": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Gateway", "default": false }, "is_app": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is App", "default": false }, "sub_tasks_mode": { "anyOf": [ { "$ref": "#/components/schemas/SubTasksMode" }, { "type": "null" } ] }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "events_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Events Streaming", "default": false }, "used_mutating_tools": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Used Mutating Tools", "default": false }, "is_continuous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Continuous", "default": false }, "mcp_servers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers", "default": [] }, "triggering_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggering Agent Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "think_mode": { "anyOf": [ { "$ref": "#/components/schemas/ThinkMode" }, { "type": "null" } ], "default": "default" }, "disable_attachment_injection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Disable Attachment Injection", "default": false }, "deep_planning": { "anyOf": [ { "$ref": "#/components/schemas/DeepPlanning" }, { "type": "null" } ] }, "must_deep_plan": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Must Deep Plan", "default": false }, "execution_attempts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Execution Attempts", "default": 1 }, "user_tokens": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Tokens" }, "user_oidc_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Oidc Token" }, "return_metrics": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Metrics", "default": false }, "tokens": { "anyOf": [ { "$ref": "#/components/schemas/LLMTokens" }, { "type": "null" } ] }, "llm_model_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Provider", "description": "Snapshot of the LLM provider used for this execution (request override or agent default at run time)." }, "llm_model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Model Name", "description": "Snapshot of the LLM model name used for this execution (request override or agent default at run time)." }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Snapshot of the reasoning effort applied during this execution, when supported by the model." } }, "type": "object", "required": [ "id", "agent_id", "organization_id", "input", "created_at" ], "title": "CreatedTask", "description": "Task creation response model.\n\nExtends AgentExecution with additional agent_id field." }, "CustomFunction": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema" }, "technical_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technical Description" }, "status": { "$ref": "#/components/schemas/CustomFunctionStatus" }, "limits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Limits", "default": {} }, "source_code": { "type": "string", "title": "Source Code" } }, "type": "object", "required": [ "id", "name", "input_schema", "status", "source_code" ], "title": "CustomFunction" }, "CustomFunctionItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier of the custom function." }, "name": { "type": "string", "title": "Name", "description": "Human-readable name of the function." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of what the function does." }, "technical_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technical Description", "description": "Auto-generated technical description from code analysis. Explains the function's logic, inputs, and outputs." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Current function status. 'analysing' = being analyzed after create/update, 'ready' = available for execution, 'error' = analysis failed (check analysis_error_details), 'draft' = not yet analyzed." }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/CustomFunctionLimitsModel" }, { "type": "null" } ], "description": "Resource limits for execution." }, "input_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Schema", "description": "Auto-detected JSON schema of the function's input parameters. Generated during analysis from the function signature and type hints." }, "source_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Code", "description": "Python source code of the function. Only included in get-by-id responses, not in list." }, "analysis_error_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis Error Details", "description": "Error details if the function analysis failed. Only present when status is 'error'." }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization that owns this function." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "ISO timestamp of when the function was created." } }, "type": "object", "required": [ "id", "name" ], "title": "CustomFunctionItem", "description": "Public-facing custom function response model.\n\nReturned by list and get endpoints. Contains function metadata,\nstatus, auto-detected input schema, and source code.\n\nTo use a custom function as an agent tool:\n1. Add to attached_tools: {\"id\": \"xpander-custom-functions\", \"operation_ids\": [\"\"]}\n2. Add to graph: {\"item_id\": \"\", \"name\": \"\", \"type\": \"tool\", \"targets\": []}" }, "CustomFunctionLimitsModel": { "properties": { "max_run_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Run Time", "description": "Maximum execution time in seconds. The function will be terminated if it exceeds this limit. Default: 15 seconds.", "default": 15 } }, "type": "object", "title": "CustomFunctionLimitsModel", "description": "Resource limits for custom function execution." }, "CustomFunctionStatus": { "type": "string", "enum": [ "draft", "analysing", "ready", "error" ], "title": "CustomFunctionStatus" }, "DeepPlanning": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "enforce": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce", "default": false }, "started": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Started", "default": false }, "question_raised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Question Raised", "default": false }, "tasks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DeepPlanningItem" }, "type": "array" }, { "type": "null" } ], "title": "Tasks", "default": [] } }, "type": "object", "title": "DeepPlanning" }, "DeepPlanningItem": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "input": { "anyOf": [ {}, { "type": "null" } ], "title": "Input" }, "output": { "anyOf": [ {}, { "type": "null" } ], "title": "Output" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name" }, "completed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Completed", "default": false } }, "type": "object", "required": [ "id", "title" ], "title": "DeepPlanningItem" }, "DuplicationPreventionSettings": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "ttl_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ttl Minutes", "default": 10 }, "selectors": { "items": { "type": "string" }, "type": "array", "title": "Selectors" } }, "type": "object", "required": [ "selectors" ], "title": "DuplicationPreventionSettings", "description": "Settings for preventing duplicate event processing in workflows.\n\nWhen enabled, this prevents the same event from triggering a workflow multiple times\nwithin a configured time window. Useful for webhooks from services like Stigg or Cal.com\nthat may fire the same event multiple times.\n\nAttributes:\n enabled: Whether duplication prevention is active.\n ttl_minutes: Time window to consider events as duplicates (default: 10 minutes).\n selectors: List of dot-notation paths to extract unique ID components from input.\n Multiple selectors are combined to form a composite key.\n Examples:\n - [\"messageId\"] - single field\n - [\"input.event_id\", \"input.user_id\"] - composite key\n - [\"triggerEvent\", \"payload.uid\"] - Cal.com style" }, "EmailNotificationSettings": { "properties": { "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "approve_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approve Button Text", "default": "Approve" }, "deny_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deny Button Text", "default": "Deny" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "default": "https://assets.xpanderai.io/xpander-logo.png" }, "to": { "items": { "type": "string" }, "type": "array", "title": "To" } }, "type": "object", "required": [ "to" ], "title": "EmailNotificationSettings", "description": "Configuration for email notifications.\n\nAttributes:\n to: List of recipient email addresses." }, "ExportAgentRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "with_knowledge_bases": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "With Knowledge Bases", "default": true } }, "type": "object", "required": [ "name" ], "title": "ExportAgentRequest" }, "ExportedKnowledgeBase": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "documents": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ExportedKnowledgeBaseDocument" }, "type": "array" }, { "type": "null" } ], "title": "Documents", "default": [] } }, "type": "object", "required": [ "name" ], "title": "ExportedKnowledgeBase" }, "ExportedKnowledgeBaseDocument": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "title": "ExportedKnowledgeBaseDocument" }, "FileEditRequest": { "properties": { "path": { "type": "string", "title": "Path", "description": "Relative path to the file to edit.", "examples": [ "app.py" ] }, "old_text": { "type": "string", "title": "Old Text", "description": "The exact text to find and replace. Must match the file content exactly (whitespace-sensitive).", "examples": [ "DEBUG = True" ] }, "new_text": { "type": "string", "title": "New Text", "description": "The replacement text that will substitute old_text.", "examples": [ "DEBUG = False" ] } }, "type": "object", "required": [ "path", "old_text", "new_text" ], "title": "FileEditRequest" }, "FileEditResponse": { "properties": { "path": { "type": "string", "title": "Path", "description": "The path of the edited file" }, "replacements_made": { "type": "integer", "title": "Replacements Made", "description": "Number of replacements made", "default": 0, "examples": [ 1 ] } }, "type": "object", "required": [ "path" ], "title": "FileEditResponse" }, "FileReadRequest": { "properties": { "path": { "type": "string", "title": "Path", "description": "Relative path to the file to read from the workspace filesystem.", "examples": [ "config.yaml" ] }, "start_line": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Start Line", "description": "1-indexed starting line number for partial reads. Omit to read from the beginning.", "examples": [ 1 ] }, "end_line": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "End Line", "description": "1-indexed ending line number (inclusive) for partial reads. Omit to read to the end.", "examples": [ 50 ] }, "encoding": { "type": "string", "title": "Encoding", "description": "File encoding to use when reading. Falls back to detected encoding if decoding fails.", "default": "utf-8", "examples": [ "utf-8" ] } }, "type": "object", "required": [ "path" ], "title": "FileReadRequest" }, "FileReadResponse": { "properties": { "content": { "type": "string", "title": "Content", "description": "File content (full or partial based on line range)", "default": "" }, "lines_count": { "type": "integer", "title": "Lines Count", "description": "Total number of lines in the returned content", "default": 0 }, "encoding_detected": { "type": "string", "title": "Encoding Detected", "description": "The encoding used to decode the file", "default": "utf-8" } }, "type": "object", "title": "FileReadResponse" }, "FileShareRequest": { "properties": { "path": { "type": "string", "title": "Path", "description": "Relative path to the file in the workspace to share publicly.", "examples": [ "output/report.csv" ] } }, "type": "object", "required": [ "path" ], "title": "FileShareRequest" }, "FileShareResponse": { "properties": { "url": { "type": "string", "title": "Url", "description": "Public CDN URL for the shared file" } }, "type": "object", "required": [ "url" ], "title": "FileShareResponse" }, "FileWriteRequest": { "properties": { "path": { "type": "string", "title": "Path", "description": "Relative path where the file should be written. Creates or overwrites the file.", "examples": [ "output/report.txt" ] }, "content": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" } ], "title": "Content", "description": "Complete content to write. A string is written verbatim; a JSON object/array is auto-serialized to pretty JSON.", "examples": [ "Hello World\n" ] }, "create_dirs": { "type": "boolean", "title": "Create Dirs", "description": "If true, creates parent directories automatically if they don't exist.", "default": true } }, "type": "object", "required": [ "path", "content" ], "title": "FileWriteRequest" }, "FileWriteResponse": { "properties": { "path": { "type": "string", "title": "Path", "description": "The path where the file was written" }, "bytes_written": { "type": "integer", "title": "Bytes Written", "description": "Number of bytes written to the file", "default": 0, "examples": [ 12 ] }, "created": { "type": "boolean", "title": "Created", "description": "True if this was a new file, False if overwritten", "default": false } }, "type": "object", "required": [ "path" ], "title": "FileWriteResponse" }, "GatewayAnswerItem": { "properties": { "question_id": { "type": "string", "title": "Question Id" }, "question_text": { "type": "string", "title": "Question Text", "default": "" }, "header": { "type": "string", "title": "Header", "default": "" }, "selected_options": { "items": { "$ref": "#/components/schemas/GatewayQuestionOption" }, "type": "array", "title": "Selected Options" }, "free_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Free Text" } }, "type": "object", "required": [ "question_id" ], "title": "GatewayAnswerItem", "description": "One resolved answer, denormalized for activity-log rendering." }, "GatewayConnectorConnection": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name", "default": "" }, "access_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Scope" }, "is_service_account": { "type": "boolean", "title": "Is Service Account", "default": false }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id" ], "title": "GatewayConnectorConnection", "description": "An existing connection the user can pick for a connector suggestion." }, "GatewayInviteRole": { "type": "string", "enum": [ "member", "admin", "super_admin", "viewer" ], "title": "GatewayInviteRole", "description": "Role for the invited teammate (maps to the invite-members edge fn payload)." }, "GatewayMessageAccepted": { "properties": { "action": { "type": "string", "title": "Action" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Id" }, "queue_depth": { "type": "integer", "title": "Queue Depth", "default": 0 }, "steer_target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Steer Target" } }, "type": "object", "required": [ "action" ], "title": "GatewayMessageAccepted", "description": "Result of accepting an inbound message for a running conversation." }, "GatewayMessageMode": { "type": "string", "enum": [ "auto", "queue", "steer" ], "title": "GatewayMessageMode", "description": "How an inbound message to a (possibly running) conversation is handled." }, "GatewayMessageRequest": { "properties": { "text": { "type": "string", "title": "Text", "default": "" }, "files": { "items": { "type": "string" }, "type": "array", "title": "Files" }, "mode": { "$ref": "#/components/schemas/GatewayMessageMode", "default": "auto" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency Key" }, "user": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User" } }, "type": "object", "title": "GatewayMessageRequest", "description": "Body of the chat-backend `messages` / `steer` endpoints." }, "GatewayQuestion": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable id used to correlate the user's answer." }, "text": { "type": "string", "title": "Text", "description": "The question itself, in the user's language." }, "header": { "type": "string", "title": "Header", "description": "Short chip/label for the question card.", "default": "" }, "options": { "items": { "$ref": "#/components/schemas/GatewayQuestionOption" }, "type": "array", "title": "Options" }, "allow_free_text": { "type": "boolean", "title": "Allow Free Text", "description": "True → the user may type a custom answer (free-text or 'Other').", "default": false }, "multi_select": { "type": "boolean", "title": "Multi Select", "description": "True → more than one option may be selected.", "default": false } }, "type": "object", "required": [ "id", "text" ], "title": "GatewayQuestion", "description": "A single question surfaced to the user." }, "GatewayQuestionOption": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable id used to correlate the user's selection." }, "label": { "type": "string", "title": "Label", "description": "User-facing choice text." }, "description": { "type": "string", "title": "Description", "description": "Optional one-line elaboration.", "default": "" } }, "type": "object", "required": [ "id", "label" ], "title": "GatewayQuestionOption", "description": "One selectable choice on a question." }, "GatewayQueuedMessage": { "properties": { "id": { "type": "string", "title": "Id" }, "text": { "type": "string", "title": "Text", "default": "" }, "files": { "items": { "type": "string" }, "type": "array", "title": "Files" }, "user": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User" }, "enqueued_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enqueued At" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency Key" } }, "type": "object", "required": [ "id" ], "title": "GatewayQueuedMessage", "description": "One user message held in the per-conversation queue." }, "GatewayRunState": { "properties": { "conversation_id": { "type": "string", "title": "Conversation Id" }, "is_running": { "type": "boolean", "title": "Is Running", "default": false }, "is_steerable": { "type": "boolean", "title": "Is Steerable", "default": false }, "steer_target": { "type": "string", "title": "Steer Target", "default": "none" }, "active_child_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Child Id" }, "queue_depth": { "type": "integer", "title": "Queue Depth", "default": 0 }, "queued_messages": { "items": { "$ref": "#/components/schemas/GatewayQueuedMessage" }, "type": "array", "title": "Queued Messages" }, "execution_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Status" }, "conversation_state": { "type": "string", "title": "Conversation State", "default": "regular" } }, "type": "object", "required": [ "conversation_id" ], "title": "GatewayRunState", "description": "Snapshot the UI uses to render run/queue/steer affordances." }, "GatewayStopRequest": { "properties": { "clear_queue": { "type": "boolean", "title": "Clear Queue", "default": false } }, "type": "object", "title": "GatewayStopRequest", "description": "Body of the chat-backend `stop` endpoint." }, "GatewaySuggestedTool": { "properties": { "kind": { "$ref": "#/components/schemas/GatewayToolKind" }, "name": { "type": "string", "title": "Name", "description": "User-facing tool / connector name." }, "description": { "type": "string", "title": "Description", "default": "" }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo" }, "connector_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connector Id" }, "using_built_in_auth": { "type": "boolean", "title": "Using Built In Auth", "default": false }, "connections": { "items": { "$ref": "#/components/schemas/GatewayConnectorConnection" }, "type": "array", "title": "Connections" }, "mcp_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Id" }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transport" }, "auth_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Type" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "type": "object", "required": [ "kind", "name" ], "title": "GatewaySuggestedTool", "description": "One candidate tool surfaced in a SuggestTool card." }, "GatewayToolKind": { "type": "string", "enum": [ "action", "custom_function", "mcp", "agent", "workflow", "skill" ], "title": "GatewayToolKind", "description": "Tool kind the suggestion / choice refers to (mirrors AddAgentToolRequest)." }, "GeneralParam": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "location": { "type": "string", "enum": [ "path", "query", "header", "cookie" ], "title": "Location" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" } }, "type": "object", "required": [ "name", "description", "location" ], "title": "GeneralParam" }, "GenerateCustomFunctionRequest": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Natural language description of what the function should do. Examples: 'Calculate compound interest given principal, rate, and years', 'Parse a CSV string and return the headers and first 5 rows'.", "default": "" }, "user_function": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Function", "description": "Optional existing source code to improve or modify. The AI will use this as a starting point.", "default": "" }, "import_curl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Import Curl", "description": "Optional cURL command to convert into a custom function. The AI will parse the cURL and generate a function that makes the equivalent HTTP request.", "default": "" } }, "type": "object", "title": "GenerateCustomFunctionRequest", "description": "Request model for AI-generating a custom function from a description.\n\nProvide a natural language description of what you need, and the AI will\ngenerate the Python source code with proper xpander_run_action signature." }, "GenerateCustomFunctionResponse": { "properties": { "custom_function": { "type": "string", "title": "Custom Function", "description": "Generated Python source code defining xpander_run_action(...)." } }, "type": "object", "required": [ "custom_function" ], "title": "GenerateCustomFunctionResponse", "description": "Response from the AI custom function generator." }, "GlobRequest": { "properties": { "pattern": { "type": "string", "title": "Pattern", "description": "Glob pattern for file matching. Supports ** for recursive matching, * for wildcards.", "examples": [ "**/*.py" ] }, "root_dir": { "type": "string", "title": "Root Dir", "description": "Root directory to search from, relative to workspace root.", "default": "", "examples": [ "src" ] }, "max_results": { "type": "integer", "maximum": 50000.0, "minimum": 1.0, "title": "Max Results", "description": "Maximum number of results to return. Prevents excessive output for broad patterns.", "default": 1000 } }, "type": "object", "required": [ "pattern" ], "title": "GlobRequest" }, "GlobResponse": { "properties": { "matches": { "items": { "type": "string" }, "type": "array", "title": "Matches", "description": "List of matched file paths" }, "total_found": { "type": "integer", "title": "Total Found", "description": "Total number of files matching the pattern", "default": 0 }, "truncated": { "type": "boolean", "title": "Truncated", "description": "True if results were truncated due to max_results limit", "default": false } }, "type": "object", "title": "GlobResponse" }, "GrepMatch": { "properties": { "file": { "type": "string", "title": "File", "description": "Path of the file containing the match" }, "line": { "type": "integer", "title": "Line", "description": "1-indexed line number of the match" }, "content": { "type": "string", "title": "Content", "description": "The matched line content" }, "context": { "type": "string", "title": "Context", "description": "Surrounding lines of context", "default": "" } }, "type": "object", "required": [ "file", "line", "content" ], "title": "GrepMatch" }, "GrepRequest": { "properties": { "pattern": { "type": "string", "title": "Pattern", "description": "Regex pattern to search for (Extended Regular Expressions).", "examples": [ "def main" ] }, "path": { "type": "string", "title": "Path", "description": "Directory or file path to search in, relative to workspace root. Directories are searched recursively.", "default": "", "examples": [ "src" ] }, "include": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include", "description": "Glob pattern to filter which files to search (e.g. '*.py' to only search Python files).", "examples": [ "*.py" ] }, "context_lines": { "type": "integer", "maximum": 20.0, "minimum": 0.0, "title": "Context Lines", "description": "Number of lines of context to show before and after each match.", "default": 2 } }, "type": "object", "required": [ "pattern" ], "title": "GrepRequest" }, "GrepResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/GrepMatch" }, "type": "array", "title": "Matches", "description": "List of matched results with context" }, "total_matches": { "type": "integer", "title": "Total Matches", "description": "Total number of matching lines found", "default": 0 }, "files_with_matches": { "type": "integer", "title": "Files With Matches", "description": "Number of distinct files that contained at least one match", "default": 0 }, "summary": { "type": "string", "title": "Summary", "description": "Human-readable one-line summary of the search result", "default": "" } }, "type": "object", "title": "GrepResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HumanInTheLoopRequest": { "properties": { "wait_node_id": { "type": "string", "title": "Wait Node Id" } }, "type": "object", "required": [ "wait_node_id" ], "title": "HumanInTheLoopRequest", "description": "Model representing human-in-the-loop approval records for tasks.\n\nAttributes:\n wait_node_id (str): The id of the node that triggered this HITL." }, "KnowledgeBaseItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "KB unique identifier" }, "name": { "type": "string", "title": "Name", "description": "KB name specified by the user" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "KB description specified by the user" }, "type": { "$ref": "#/components/schemas/KnowledgeBaseType", "description": "KB type, managed / external" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "Organization ID" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Agent ID" }, "total_documents": { "type": "integer", "title": "Total Documents", "description": "Total count of embedded documents", "default": 0 } }, "type": "object", "required": [ "id", "name", "type", "organization_id" ], "title": "KnowledgeBaseItem", "description": "Represents a Knowledge Base item.\n\nAttributes:\n id (str): KB unique identifier.\n name (str): KB name specified by the user.\n description (str): KB description specified by the user.\n type (KnowledgeBaseType): KB type, either managed or external.\n organization_id (str): Organization ID associated with the KB.\n total_documents (int): Total count of embedded documents. Defaults to 0." }, "KnowledgeBaseStrategy": { "type": "string", "enum": [ "vanilla", "agentic_rag" ], "title": "KnowledgeBaseStrategy" }, "KnowledgeBaseType": { "type": "string", "enum": [ "managed", "external" ], "title": "KnowledgeBaseType" }, "LLMCredentials": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "name", "value" ], "title": "LLMCredentials" }, "LLMCredentialsKeyType": { "type": "string", "enum": [ "xpander", "custom" ], "title": "LLMCredentialsKeyType" }, "LLMModelItem": { "properties": { "model_id": { "type": "string", "title": "Model Id", "description": "The model identifier to use in agent configuration. Set this as the agent's model_name field (e.g., 'claude-sonnet-5', 'gpt-4o')." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Human-readable name of the model for display purposes." }, "tier": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tier", "description": "Model capability tier. Higher tiers indicate more capable (and typically more expensive) models. Tier 1 is standard, higher tiers are premium.", "default": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Brief description of the model's capabilities and recommended use cases." } }, "type": "object", "required": [ "model_id" ], "title": "LLMModelItem", "description": "Public-facing LLM model summary.\n\nReturned by GET /llm_providers/{provider_identifier}/models.\nUse the model_id value for the agent's model_name field." }, "LLMModelProvider": { "type": "string", "enum": [ "openai", "nim", "amazon_bedrock", "azure_ai_foundary", "huggingFace", "friendlyAI", "anthropic", "gemini", "fireworks", "google_ai_studio", "helicone", "bytedance", "tzafon_lightcone", "cerebras", "open_router", "nebius", "cloudflare_ai_gw", "z_ai" ], "title": "LLMModelProvider" }, "LLMProviderItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for this LLM provider." }, "name": { "type": "string", "title": "Name", "description": "Human-readable display name of the provider (e.g., 'Anthropic', 'OpenAI')." }, "internal_identifier": { "type": "string", "title": "Internal Identifier", "description": "The provider key used in agent configuration. Use this value for the agent's model_provider field (e.g., 'anthropic', 'openai', 'gemini')." }, "logo": { "type": "string", "title": "Logo", "description": "Logo identifier for the provider's icon." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Brief description of the provider." } }, "type": "object", "required": [ "id", "name", "internal_identifier", "logo" ], "title": "LLMProviderItem", "description": "Public-facing LLM provider summary (without models).\n\nUse GET /llm_providers to retrieve this list. To get models for a specific\nprovider, use GET /llm_providers/{internal_identifier}/models." }, "LLMReasoningEffort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ], "title": "LLMReasoningEffort" }, "LLMTokens": { "properties": { "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completion Tokens", "default": 0 }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Prompt Tokens", "default": 0 }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Tokens", "default": 0 }, "cache_read_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cache Read Tokens", "default": 0 }, "cache_write_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cache Write Tokens", "default": 0 } }, "type": "object", "title": "LLMTokens" }, "MCPOAuthGetTokenGenericResponse": { "properties": { "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "MCPOAuthGetTokenGenericResponse" }, "MCPOAuthGetTokenLoginRequiredResponse": { "properties": { "url": { "type": "string", "title": "Url" }, "server_url": { "type": "string", "title": "Server Url" }, "server_name": { "type": "string", "title": "Server Name" } }, "type": "object", "required": [ "url", "server_url", "server_name" ], "title": "MCPOAuthGetTokenLoginRequiredResponse" }, "MCPOAuthGetTokenTokenReadyResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" } }, "type": "object", "required": [ "access_token" ], "title": "MCPOAuthGetTokenTokenReadyResponse" }, "MCPOAuthResponseType": { "type": "string", "enum": [ "not_supported", "login_required", "token_issue", "token_ready" ], "title": "MCPOAuthResponseType" }, "MCPServerAuthType": { "type": "string", "enum": [ "api_key", "oauth2", "custom_headers", "none" ], "title": "MCPServerAuthType" }, "MCPServerTransport": { "type": "string", "enum": [ "stdio", "sse", "streamable-http" ], "title": "MCPServerTransport" }, "MCPServerType": { "type": "string", "enum": [ "local", "remote" ], "title": "MCPServerType" }, "MessageFeedbackItem": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Task/thread id this feedback belongs to." }, "message_id": { "type": "string", "title": "Message Id", "description": "The feedbacked activity message id." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id" }, "is_positive": { "type": "boolean", "title": "Is Positive", "description": "True for thumbs-up, false for thumbs-down." }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "message_id", "is_positive" ], "title": "MessageFeedbackItem", "description": "A persisted thumbs up/down feedback row for one message in a conversation." }, "MessageIdentity": { "properties": { "name": { "type": "string", "title": "Name", "description": "Display name shown on the bubble, e.g. Skill Builder." }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Emoji or icon URL shown as the avatar." } }, "type": "object", "required": [ "name" ], "title": "MessageIdentity", "description": "Display identity stamped on events/messages produced under a skill." }, "MinimalAIAgentWithCreatedByDetails": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ] }, "organization_id": { "type": "string", "title": "Organization Id" }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ] }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ] }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name" }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework" }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo" }, "is_coordinate_mode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Coordinate Mode" }, "has_pending_changes": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Pending Changes" }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "default": false }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "default": [] }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "default": false }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience" }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ] }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "created_by_details": { "anyOf": [ { "$ref": "#/components/schemas/CreatedByDetails" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "organization_id", "type" ], "title": "MinimalAIAgentWithCreatedByDetails" }, "MultiEditRequest": { "properties": { "edits": { "items": { "$ref": "#/components/schemas/SingleEdit" }, "type": "array", "title": "Edits", "description": "List of edits to apply atomically. If any edit fails, all changes are rolled back." } }, "type": "object", "required": [ "edits" ], "title": "MultiEditRequest" }, "MultiEditResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/SingleEditResult" }, "type": "array", "title": "Results", "description": "Results for each edit operation" } }, "type": "object", "title": "MultiEditResponse" }, "NotificationSettings-Input": { "properties": { "on_success": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Success", "default": {} }, "on_error": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Error", "default": {} }, "on_budget": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Budget", "default": {} } }, "type": "object", "title": "NotificationSettings", "description": "Configuration for event-based notifications.\n\nAttributes:\n on_success: Notifications to send when an operation succeeds.\n Maps notification types to a list of notification configurations.\n on_error: Notifications to send when an operation fails.\n Maps notification types to a list of notification configurations.\n on_budget: Notifications to send on budget threshold crossings.\n A dedicated category — budget alerts are not errors." }, "NotificationSettings-Output": { "properties": { "on_success": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Success", "default": {} }, "on_error": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Error", "default": {} }, "on_budget": { "anyOf": [ { "additionalProperties": { "items": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ] }, "type": "array" }, "propertyNames": { "enum": [ "email", "slack", "webhook" ] }, "type": "object" }, { "type": "null" } ], "title": "On Budget", "default": {} } }, "type": "object", "title": "NotificationSettings", "description": "Configuration for event-based notifications.\n\nAttributes:\n on_success: Notifications to send when an operation succeeds.\n Maps notification types to a list of notification configurations.\n on_error: Notifications to send when an operation fails.\n Maps notification types to a list of notification configurations.\n on_budget: Notifications to send on budget threshold crossings.\n A dedicated category — budget alerts are not errors." }, "OrchestrationClassifierNode-Input": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/ClassificationGroup" }, "type": "array", "title": "Groups" }, "output_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "groups", "settings" ], "title": "OrchestrationClassifierNode", "description": "Node that uses LLM to classify inputs into groups.\n\nAttributes:\n groups: List of classification groups to evaluate against.\n output_type: Expected output format. Defaults to Text.\n output_schema: JSON schema for structured output validation.\n instructions: Classification or transformation instructions for the LLM.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationClassifierNode-Output": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/ClassificationGroup" }, "type": "array", "title": "Groups" }, "output_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "groups", "settings" ], "title": "OrchestrationClassifierNode", "description": "Node that uses LLM to classify inputs into groups.\n\nAttributes:\n groups: List of classification groups to evaluate against.\n output_type: Expected output format. Defaults to Text.\n output_schema: JSON schema for structured output validation.\n instructions: Classification or transformation instructions for the LLM.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationClassifierNodeLLMSettings": { "properties": { "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "default": "amazon_bedrock" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "default": "global.anthropic.claude-sonnet-5" }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key" }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "default": "xpander" }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ] }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base" }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "default": {} } }, "type": "object", "title": "OrchestrationClassifierNodeLLMSettings", "description": "LLM configuration for classifier nodes.\n\nAttributes:\n model_provider: The LLM provider to use. Defaults to AmazonBedrock.\n model_name: Specific model identifier. Defaults to \"global.anthropic.claude-sonnet-5\".\n llm_credentials_key: Key identifier for stored credentials.\n llm_credentials_key_type: Type of credential key storage. Defaults to XPander.\n llm_credentials: Direct credential object if not using stored credentials.\n llm_api_base: Alternative API Base for the LLM.\n llm_extra_headers: Extra headers to be set to LLM Requests." }, "OrchestrationCodeNode": { "properties": { "code": { "type": "string", "title": "Code" } }, "type": "object", "required": [ "code" ], "title": "OrchestrationCodeNode", "description": "Node that executes arbitrary code.\n\nAttributes:\n code: The code string to execute." }, "OrchestrationCondition": { "properties": { "type": { "$ref": "#/components/schemas/OrchestrationConditionType" }, "term": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Term" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Path" }, "value": { "anyOf": [ {}, { "type": "null" } ], "title": "Value" } }, "type": "object", "required": [ "type" ], "title": "OrchestrationCondition", "description": "Condition for controlling orchestration flow.\n\nAttributes:\n type: Type of condition (regex, contains, else, or comparison operators).\n term: The pattern or string to match against. Used for 'regex' and 'contains' types.\n group_id: Optional group ID for group-based classifier routing.\n When set, routing matches by group ID instead of term matching.\n path: Path to extract value from input data (e.g., \"input.client_id\" or \"client_id\").\n Used for comparison operators (equal, not_equal, gt, lt, gte, lte, not_empty).\n value: Value to compare against. Used with comparison operators.\n Not required for 'not_empty' type." }, "OrchestrationConditionType": { "type": "string", "enum": [ "regex", "contains", "else", "equal", "not_equal", "gt", "lt", "gte", "lte", "not_empty" ], "title": "OrchestrationConditionType", "description": "Types of conditions for orchestration control flow.\n\nAttributes:\n Regex: Condition based on regular expression matching.\n Contains: Condition based on substring containment.\n Else: Fallback condition that always matches (executed when no other conditions match).\n Equal: Condition based on equality comparison (path == value).\n NotEqual: Condition based on inequality comparison (path != value).\n GreaterThan: Condition based on greater than comparison (path > value).\n LessThan: Condition based on less than comparison (path < value).\n GreaterThanOrEqual: Condition based on greater than or equal comparison (path >= value).\n LessThanOrEqual: Condition based on less than or equal comparison (path <= value).\n NotEmpty: Condition that checks if a path value is not empty/null." }, "OrchestrationGuardrailNode-Input": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/ClassificationGroup" }, "type": "array", "title": "Groups" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "groups", "settings" ], "title": "OrchestrationGuardrailNode", "description": "Node that uses LLM to evaluate input against pass/fail criteria.\n\nThis node works like a classifier with exactly 2 groups: \"pass\" and \"fail\".\nThe user defines evaluation_criteria for each group.\n\nRouting behavior:\n- If guardrail passes: routes to downstream node with condition group_id=\"pass\"\n- If guardrail fails: routes to downstream node with condition group_id=\"fail\"\n- If no fail route exists: falls back to end nodes (end-summarizer or end-classifier)\n- A pass route is REQUIRED; fail route is optional.\n\nAttributes:\n groups: List of 2 ClassificationGroup objects with IDs \"pass\" and \"fail\".\n Each group has evaluation_criteria defined by the user.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationGuardrailNode-Output": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/ClassificationGroup" }, "type": "array", "title": "Groups" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "groups", "settings" ], "title": "OrchestrationGuardrailNode", "description": "Node that uses LLM to evaluate input against pass/fail criteria.\n\nThis node works like a classifier with exactly 2 groups: \"pass\" and \"fail\".\nThe user defines evaluation_criteria for each group.\n\nRouting behavior:\n- If guardrail passes: routes to downstream node with condition group_id=\"pass\"\n- If guardrail fails: routes to downstream node with condition group_id=\"fail\"\n- If no fail route exists: falls back to end nodes (end-summarizer or end-classifier)\n- A pass route is REQUIRED; fail route is optional.\n\nAttributes:\n groups: List of 2 ClassificationGroup objects with IDs \"pass\" and \"fail\".\n Each group has evaluation_criteria defined by the user.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationIterativeStrategy-Input": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "max_iterations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Iterations", "default": 3 }, "end_condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] } }, "type": "object", "title": "OrchestrationIterativeStrategy", "description": "Strategy for iteratively executing orchestration nodes.\n\nAttributes:\n enabled: Whether iterative execution is enabled.\n max_iterations: Maximum number of iterations. Defaults to 3.\n end_condition: Optional condition to stop iteration early." }, "OrchestrationIterativeStrategy-Output": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "max_iterations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Iterations", "default": 3 }, "end_condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] } }, "type": "object", "title": "OrchestrationIterativeStrategy", "description": "Strategy for iteratively executing orchestration nodes.\n\nAttributes:\n enabled: Whether iterative execution is enabled.\n max_iterations: Maximum number of iterations. Defaults to 3.\n end_condition: Optional condition to stop iteration early." }, "OrchestrationNode-Input": { "properties": { "type": { "$ref": "#/components/schemas/OrchestrationNodeType" }, "id": { "type": "string", "title": "Id" }, "next_node_ids": { "items": { "type": "string" }, "type": "array", "title": "Next Node Ids" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] }, "retry_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationRetryStrategy" }, { "type": "null" } ] }, "iterative_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationIterativeStrategy-Input" }, { "type": "null" } ] }, "stop_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationStopStrategy-Input" }, { "type": "null" } ] }, "definition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCodeNode" }, { "$ref": "#/components/schemas/OrchestrationClassifierNode-Input" }, { "$ref": "#/components/schemas/OrchestrationPointerNode" }, { "$ref": "#/components/schemas/OrchestrationWaitNode-Input" }, { "$ref": "#/components/schemas/OrchestrationGuardrailNode-Input" }, { "$ref": "#/components/schemas/OrchestrationSummarizerNode-Input" }, { "$ref": "#/components/schemas/OrchestrationSendToEndNode" }, { "$ref": "#/components/schemas/OrchestrationSelfScheduleNode" }, { "$ref": "#/components/schemas/OrchestrationNodePointerDefinition" }, { "$ref": "#/components/schemas/OrchestrationParallelNode-Input" } ], "title": "Definition" }, "input_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "input_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Schema" }, "input_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Instructions" }, "agentic_context_input_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentic Context Input Instructions" }, "agentic_context_output_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentic Context Output Instructions" }, "return_this": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return This", "default": false } }, "type": "object", "required": [ "type", "definition" ], "title": "OrchestrationNode", "description": "A node in an orchestration workflow.\n\nRepresents a single execution unit in an orchestration with control flow,\nexecution strategies, and a specific node type definition.\n\nAttributes:\n type: Type of the node (must match the definition type).\n id: Unique identifier for the node. Auto-generated if not provided.\n next_node_ids: List of IDs of the next nodes to execute.\n name: Human-readable name for the node.\n description: Detailed description of the node's purpose.\n condition: Conditional logic for executing this node.\n retry_strategy: Strategy for retrying failed executions.\n iterative_strategy: Strategy for iterative execution.\n stop_strategy: Strategy for stopping the workflow.\n definition: The actual node implementation (code, classifier, pointer, or wait).\n input_type: Expected input format. Defaults to Text.\n input_schema: JSON schema for structured input validation.\n input_instructions: Instructions to use for structured input.\n agentic_context_input_instructions: Instructions to use for agentic context injection.\n agentic_context_output_instructions: Instructions to use for agentic context update." }, "OrchestrationNode-Output": { "properties": { "type": { "$ref": "#/components/schemas/OrchestrationNodeType" }, "id": { "type": "string", "title": "Id" }, "next_node_ids": { "items": { "type": "string" }, "type": "array", "title": "Next Node Ids" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] }, "retry_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationRetryStrategy" }, { "type": "null" } ] }, "iterative_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationIterativeStrategy-Output" }, { "type": "null" } ] }, "stop_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationStopStrategy-Output" }, { "type": "null" } ] }, "definition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCodeNode" }, { "$ref": "#/components/schemas/OrchestrationClassifierNode-Output" }, { "$ref": "#/components/schemas/OrchestrationPointerNode" }, { "$ref": "#/components/schemas/OrchestrationWaitNode-Output" }, { "$ref": "#/components/schemas/OrchestrationGuardrailNode-Output" }, { "$ref": "#/components/schemas/OrchestrationSummarizerNode-Output" }, { "$ref": "#/components/schemas/OrchestrationSendToEndNode" }, { "$ref": "#/components/schemas/OrchestrationSelfScheduleNode" }, { "$ref": "#/components/schemas/OrchestrationNodePointerDefinition" }, { "$ref": "#/components/schemas/OrchestrationParallelNode-Output" } ], "title": "Definition" }, "input_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "input_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Schema" }, "input_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Instructions" }, "agentic_context_input_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentic Context Input Instructions" }, "agentic_context_output_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agentic Context Output Instructions" }, "return_this": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return This", "default": false } }, "type": "object", "required": [ "type", "definition" ], "title": "OrchestrationNode", "description": "A node in an orchestration workflow.\n\nRepresents a single execution unit in an orchestration with control flow,\nexecution strategies, and a specific node type definition.\n\nAttributes:\n type: Type of the node (must match the definition type).\n id: Unique identifier for the node. Auto-generated if not provided.\n next_node_ids: List of IDs of the next nodes to execute.\n name: Human-readable name for the node.\n description: Detailed description of the node's purpose.\n condition: Conditional logic for executing this node.\n retry_strategy: Strategy for retrying failed executions.\n iterative_strategy: Strategy for iterative execution.\n stop_strategy: Strategy for stopping the workflow.\n definition: The actual node implementation (code, classifier, pointer, or wait).\n input_type: Expected input format. Defaults to Text.\n input_schema: JSON schema for structured input validation.\n input_instructions: Instructions to use for structured input.\n agentic_context_input_instructions: Instructions to use for agentic context injection.\n agentic_context_output_instructions: Instructions to use for agentic context update." }, "OrchestrationNodePointerDefinition": { "properties": { "source_node_id": { "type": "string", "title": "Source Node Id" } }, "type": "object", "required": [ "source_node_id" ], "title": "OrchestrationNodePointerDefinition", "description": "Definition for a NodePointer node that acts as a graph-position jump.\n\nA NodePointer jumps execution to another node's position in the graph.\nAt resolution time, the pointer adopts the source node's definition, type,\nAND next_node_ids — so after executing the source's logic, the flow\ncontinues to the source's original downstream targets.\nThe pointer keeps its own id, name, condition, and strategies.\n\nAttributes:\n source_node_id: ID of the node to jump to." }, "OrchestrationNodeType": { "type": "string", "enum": [ "custom_function", "code", "agent", "orchestration", "classifier", "wait", "action", "guardrail", "summarizer", "send_to_end", "node_pointer", "parallel", "self_schedule" ], "title": "OrchestrationNodeType", "description": "Types of nodes available in an orchestration workflow.\n\nAttributes:\n CustomFunction: Node that executes a custom function.\n Code: Node that executes arbitrary code.\n Agent: Node that invokes an AI agent.\n Orchestration: Node that references another orchestration.\n Classifier: Node that classifies inputs using LLM.\n Wait: Node that pauses execution until a condition is met.\n Action: Node that triggers an action (api).\n Guardrail: Node that enforces guardrails on inputs using LLM.\n Summarizer: Node that summarizes or extracts information from inputs using LLM." }, "OrchestrationParallelNode-Input": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/OrchestrationNode-Input" }, "type": "array", "title": "Nodes" }, "output_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "output_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Instructions" } }, "type": "object", "required": [ "nodes" ], "title": "OrchestrationParallelNode", "description": "Node that executes multiple child nodes in parallel.\n\nAll child nodes receive the same input (the output of the preceding node).\nWhen all child nodes complete, their results are combined:\n- JSON outputs are merged into a single JSON object keyed by node name.\n- String outputs are concatenated with node name headers.\n\nAttributes:\n nodes: List of child OrchestrationNode objects to execute in parallel.\n output_type: Expected output format for the combined result. Defaults to Text.\n output_schema: JSON schema for structured output validation of the combined result.\n output_instructions: Instructions for transforming the combined output into the schema." }, "OrchestrationParallelNode-Output": { "properties": { "nodes": { "items": { "$ref": "#/components/schemas/OrchestrationNode-Output" }, "type": "array", "title": "Nodes" }, "output_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "output_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Instructions" } }, "type": "object", "required": [ "nodes" ], "title": "OrchestrationParallelNode", "description": "Node that executes multiple child nodes in parallel.\n\nAll child nodes receive the same input (the output of the preceding node).\nWhen all child nodes complete, their results are combined:\n- JSON outputs are merged into a single JSON object keyed by node name.\n- String outputs are concatenated with node name headers.\n\nAttributes:\n nodes: List of child OrchestrationNode objects to execute in parallel.\n output_type: Expected output format for the combined result. Defaults to Text.\n output_schema: JSON schema for structured output validation of the combined result.\n output_instructions: Instructions for transforming the combined output into the schema." }, "OrchestrationPointerNode": { "properties": { "asset_id": { "type": "string", "title": "Asset Id" }, "type": { "type": "string", "enum": [ "agent", "custom_function", "orchestration", "action" ], "title": "Type" }, "output_type": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "text" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "instructions_mode": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationPointerNodeInstructionsMode" }, { "type": "null" } ], "default": "append" }, "ignore_response": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ignore Response", "default": false }, "persist_thread_id": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Persist Thread Id", "default": true }, "schema_override": { "anyOf": [ { "$ref": "#/components/schemas/SchemaOverride" }, { "type": "null" } ] } }, "type": "object", "required": [ "asset_id", "type" ], "title": "OrchestrationPointerNode", "description": "Node that references an external asset (agent, function, or orchestration).\n\nAttributes:\n asset_id: Unique identifier of the asset to execute.\n type: Type of asset being referenced.\n output_type: Expected output format. Defaults to Text.\n output_schema: JSON schema for structured output validation.\n instructions: Optional instructions for the pointer node (Action only).\n instructions_mode: Mode to use for pointer node, specifically for agent nodes.\n ignore_response: Should ignore the node result and proceed with previous result?.\n persist_thread_id: Should persist the thread in agent nodes? default (True).\n schema_override: Optional schema override with permanentValue fields for fixed values." }, "OrchestrationPointerNodeInstructionsMode": { "type": "string", "enum": [ "replace", "append" ], "title": "OrchestrationPointerNodeInstructionsMode", "description": "Modes for instruction usage in pointer node.\n\nAttributes:\n Replace: Replaces the traget asset instructions.\n Append: Appends to the traget asset instructions." }, "OrchestrationRetryStrategy": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "max_retries": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Retries", "default": 3 } }, "type": "object", "title": "OrchestrationRetryStrategy", "description": "Strategy for retrying failed orchestration nodes.\n\nAttributes:\n enabled: Whether retry is enabled for this node.\n max_retries: Maximum number of retry attempts. Defaults to 3." }, "OrchestrationSelfScheduleNode": { "properties": { "when": { "type": "string", "title": "When" }, "target_node_id": { "type": "string", "title": "Target Node Id" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "max_reschedules": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Max Reschedules", "default": 1 } }, "type": "object", "required": [ "when", "target_node_id" ], "title": "OrchestrationSelfScheduleNode", "description": "Node that pauses the workflow and schedules itself to resume at a later time.\n\nAt runtime the worker's self-schedule executor:\n 1. LLM-parses ``when`` (free-text like \"in 1 hour\", \"next Monday 9am\") into an\n absolute ISO-8601 ``run_at`` using the current datetime / user timezone.\n 2. Creates a row in ``ai_agents_self_schedules`` with the current ``task_id``\n and ``workflow_next_node = target_node_id``.\n 3. Pauses the task.\n\nWhen APScheduler fires the row, the same task is re-invoked with\n``payload_extension={\"workflow_next_node\": target_node_id}`` and the worker\nresumes execution starting from the target node, re-running target + its\nforward cone and skipping everything outside that cone.\n\n``target_node_id`` may point to ANY node in the orchestration (forward,\nbackward, or sibling). Backward jumps are bounded by ``max_reschedules`` so\nloops cannot run away.\n\nAttributes:\n when: Free-text schedule expression, parsed by the worker via an LLM.\n target_node_id: The id of the node to resume at. Must exist in the\n orchestration; no topological constraint.\n prompt: Optional instruction appended to the upstream node's result\n before being sent as the scheduled run's prompt. If both the upstream\n result and this prompt are empty, the node fails rather than creating\n an empty row.\n max_reschedules: Maximum number of times this node may fire during a\n single task lifecycle. Once reached, the executor falls through and\n the graph proceeds via ``next_node_ids``. Defaults to 1." }, "OrchestrationSendToEndNode": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "title": "OrchestrationSendToEndNode", "description": "Node that routes execution to end nodes or finishes the workflow.\n\nWhen triggered, this node will:\n1. Route to end nodes (end-summarizer, end-classifier) if they exist\n2. Finish workflow execution immediately if no end nodes exist\n\nAttributes:\n message: Optional message or reason for finishing the workflow." }, "OrchestrationStopStrategy-Input": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "stop_on_failure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stop On Failure", "default": true }, "stop_on_condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] } }, "type": "object", "title": "OrchestrationStopStrategy", "description": "Strategy for stopping orchestration execution.\n\nAttributes:\n enabled: Whether the stop strategy is enabled.\n stop_on_failure: Whether to stop the entire orchestration on node failure.\n stop_on_condition: Optional condition that will stop execution if met." }, "OrchestrationStopStrategy-Output": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "default": false }, "stop_on_failure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stop On Failure", "default": true }, "stop_on_condition": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationCondition" }, { "type": "null" } ] } }, "type": "object", "title": "OrchestrationStopStrategy", "description": "Strategy for stopping orchestration execution.\n\nAttributes:\n enabled: Whether the stop strategy is enabled.\n stop_on_failure: Whether to stop the entire orchestration on node failure.\n stop_on_condition: Optional condition that will stop execution if met." }, "OrchestrationSummarizerNode-Input": { "properties": { "instructions": { "type": "string", "title": "Instructions" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "instructions", "settings" ], "title": "OrchestrationSummarizerNode", "description": "Node that processes large payloads and answers specific questions.\n\nThis node uses an LLM to summarize or extract information from large inputs.\n\nAttributes:\n instructions: Summarization or question-answering instructions for the LLM.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationSummarizerNode-Output": { "properties": { "instructions": { "type": "string", "title": "Instructions" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "default": [] }, "settings": { "$ref": "#/components/schemas/OrchestrationClassifierNodeLLMSettings" } }, "type": "object", "required": [ "instructions", "settings" ], "title": "OrchestrationSummarizerNode", "description": "Node that processes large payloads and answers specific questions.\n\nThis node uses an LLM to summarize or extract information from large inputs.\n\nAttributes:\n instructions: Summarization or question-answering instructions for the LLM.\n examples: Example inputs/outputs to guide the LLM behavior.\n settings: LLM configuration settings." }, "OrchestrationWaitNode-Input": { "properties": { "type": { "type": "string", "enum": [ "webhook", "hitl" ], "title": "Type" }, "definition": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ], "title": "Definition" } }, "type": "object", "required": [ "type", "definition" ], "title": "OrchestrationWaitNode", "description": "Node that pauses execution until an external event occurs.\n\nAttributes:\n type: Type of wait event (webhook or human-in-the-loop).\n definition: Notification configuration for triggering continuation." }, "OrchestrationWaitNode-Output": { "properties": { "type": { "type": "string", "enum": [ "webhook", "hitl" ], "title": "Type" }, "definition": { "anyOf": [ { "$ref": "#/components/schemas/EmailNotificationSettings" }, { "$ref": "#/components/schemas/SlackNotificationSettings" }, { "$ref": "#/components/schemas/WebhookNotificationSettings" } ], "title": "Definition" } }, "type": "object", "required": [ "type", "definition" ], "title": "OrchestrationWaitNode", "description": "Node that pauses execution until an external event occurs.\n\nAttributes:\n type: Type of wait event (webhook or human-in-the-loop).\n definition: Notification configuration for triggering continuation." }, "OutputFormat": { "type": "string", "enum": [ "text", "markdown", "json", "voice" ], "title": "OutputFormat" }, "PaginatedResponse_CustomFunctionItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CustomFunctionItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[CustomFunctionItem]" }, "PaginatedResponse_KnowledgeBaseDocumentItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/src__models__knowledge__documents__KnowledgeBaseDocumentItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[KnowledgeBaseDocumentItem]" }, "PaginatedResponse_KnowledgeBaseItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/KnowledgeBaseItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[KnowledgeBaseItem]" }, "PaginatedResponse_MinimalAIAgentWithCreatedByDetails_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MinimalAIAgentWithCreatedByDetails" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[MinimalAIAgentWithCreatedByDetails]" }, "PaginatedResponse_SimplifiedAIAgent_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SimplifiedAIAgent" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[SimplifiedAIAgent]" }, "PaginatedResponse_TasksListItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TasksListItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[TasksListItem]" }, "PaginatedResponse_ToolCatalogItem_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ToolCatalogItem" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[ToolCatalogItem]" }, "PaginatedResponse_WorkflowResponse_": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WorkflowResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "per_page": { "type": "integer", "title": "Per Page" }, "total_pages": { "type": "integer", "title": "Total Pages" } }, "type": "object", "required": [ "items", "total", "page", "per_page", "total_pages" ], "title": "PaginatedResponse[WorkflowResponse]" }, "PendingECARequest": { "properties": { "connector_name": { "type": "string", "title": "Connector Name" }, "auth_url": { "type": "string", "title": "Auth Url" } }, "type": "object", "required": [ "connector_name", "auth_url" ], "title": "PendingECARequest" }, "RequestPayload": { "properties": { "body_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Body Params" }, "query_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Query Params" }, "path_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Path Params" }, "headers": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Headers" } }, "type": "object", "title": "RequestPayload" }, "RequiredSecret": { "properties": { "name": { "type": "string", "title": "Name", "description": "Env var name, e.g. AWS_ACCESS_KEY_ID." }, "description": { "type": "string", "title": "Description", "description": "What the secret is for (shown under the input).", "default": "" }, "secret": { "type": "boolean", "title": "Secret", "description": "Mask the input (true for secrets, false for plain config).", "default": true }, "required": { "type": "boolean", "title": "Required", "description": "Whether the value must be filled before submitting.", "default": true } }, "type": "object", "required": [ "name" ], "title": "RequiredSecret", "description": "A single secret the card asks for (no value — the value is user-entered)." }, "ScheduledTask": { "properties": { "id": { "type": "string", "title": "Id", "description": "Source-node id. Pass it to update/remove/run the task." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Human-readable label for the task." }, "cron": { "type": "string", "title": "Cron", "description": "Cron expression (5-field crontab, UTC), e.g. '0 9 * * *'." }, "prompt": { "type": "string", "title": "Prompt", "description": "Instruction the agent runs on each fire." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the task is active. Disabled tasks keep their config but do not fire.", "default": true }, "type": { "$ref": "#/components/schemas/ScheduledTaskType", "description": "Job kind — scheduled-job or live-surface.", "default": "scheduled-job" } }, "type": "object", "required": [ "id", "cron", "prompt" ], "title": "ScheduledTask", "description": "A recurring scheduled task — the simplified view of one cron `task` source node." }, "ScheduledTaskType": { "type": "string", "enum": [ "scheduled-job", "live-surface" ], "title": "ScheduledTaskType", "description": "What a scheduled task drives — a plain job vs a live-surface regeneration." }, "SchemaOverride": { "properties": { "input": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input" } }, "type": "object", "title": "SchemaOverride", "description": "Schema override for workflow action nodes.\n\nAllows setting permanent (fixed) values for tool input properties.\nFields with permanentValue will be removed from the schema sent to the LLM\nand the permanent values will be applied to the payload before execution.\n\nAttributes:\n input: Input schema with permanentValue fields to override LLM-generated values." }, "SelfScheduleSettings": { "properties": { "can_self_schedule": { "type": "boolean", "title": "Can Self Schedule", "description": "Whether the agent may schedule its own future runs." }, "max_self_schedules": { "anyOf": [ { "type": "integer", "maximum": 1000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Self Schedules", "description": "Per-task lifetime cap on chained self-schedules (1-1000)." } }, "type": "object", "required": [ "can_self_schedule" ], "title": "SelfScheduleSettings", "description": "Agent-level self-schedule capability — request and response for the enable/disable toggle." }, "SelfScheduleView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Self-schedule id. Pass it to DELETE to cancel." }, "agent_id": { "type": "string", "title": "Agent Id", "description": "Owning agent id." }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id", "description": "Execution thread the run continues, if any." }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "Instruction for the scheduled run." }, "run_at": { "type": "string", "format": "date-time", "title": "Run At", "description": "When the run fires (UTC)." }, "status": { "type": "string", "title": "Status", "description": "scheduled, completed, or failed." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last update timestamp." } }, "type": "object", "required": [ "id", "agent_id", "run_at", "status" ], "title": "SelfScheduleView", "description": "A one-shot self-schedule row created by the agent at runtime." }, "SimplifiedAIAgent": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Agent id." }, "name": { "type": "string", "title": "Name", "description": "Agent name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Agent description." }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Agent icon." }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ], "description": "Agent type." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "description": "Agent status." }, "model_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Provider", "description": "LLM provider." }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "LLM model." }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "description": "Runtime: agno (built-in) or external-harness (Claude Code / Codex / OpenCode)." }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "description": "serverless or container." }, "harness_settings": { "anyOf": [ { "$ref": "#/components/schemas/HarnessSettings" }, { "type": "null" } ], "description": "External harness settings (default CLI, per-CLI models, permission mode, per-turn resources ceilings); absent for built-in agents." }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "description": "Agent instructions." }, "knowledge_base_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Base Ids", "description": "Attached knowledge base ids.", "default": [] }, "source_node_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source Node Types", "description": "Trigger source types (sdk, webhook, slack, ...).", "default": [] }, "tools": { "items": { "$ref": "#/components/schemas/AgentTool" }, "type": "array", "title": "Tools", "description": "Tools attached to this agent.", "default": [] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation timestamp." }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "Creator user id." }, "created_by_details": { "anyOf": [ { "$ref": "#/components/schemas/CreatedByDetails" }, { "type": "null" } ], "description": "Creator details." } }, "type": "object", "required": [ "name" ], "title": "SimplifiedAIAgent", "description": "Lean agent view exposing tools as one simple list, hiding low-level graph/oas internals." }, "SingleEdit": { "properties": { "path": { "type": "string", "title": "Path", "description": "Relative path to the file to edit" }, "old_text": { "type": "string", "title": "Old Text", "description": "Exact text to find and replace" }, "new_text": { "type": "string", "title": "New Text", "description": "Replacement text" } }, "type": "object", "required": [ "path", "old_text", "new_text" ], "title": "SingleEdit" }, "SingleEditResult": { "properties": { "path": { "type": "string", "title": "Path", "description": "The path of the edited file" }, "replacements_made": { "type": "integer", "title": "Replacements Made", "description": "Number of replacements made in this file", "default": 0 } }, "type": "object", "required": [ "path" ], "title": "SingleEditResult" }, "SlackCredentials": { "properties": { "authed_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authed User Id" }, "access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Token" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "verification_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verification Token" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret" }, "app_configuration_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Configuration Token" }, "app_configuration_refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Configuration Refresh Token" } }, "type": "object", "title": "SlackCredentials", "description": "Slack API authentication credentials.\n\nAttributes:\n authed_user_id: Authenticated user's Slack ID.\n access_token: OAuth access token for API calls.\n client_id: Slack app client ID.\n client_secret: Slack app client secret.\n verification_token: Token for verifying requests from Slack.\n signing_secret: Secret for validating webhook signatures.\n app_configuration_token: Token for app configuration.\n app_configuration_refresh_token: Refresh token for app configuration." }, "SlackNotificationSettings": { "properties": { "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "approve_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approve Button Text", "default": "Approve" }, "deny_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deny Button Text", "default": "Deny" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "default": "https://assets.xpanderai.io/xpander-logo.png" }, "channels": { "items": { "type": "string" }, "type": "array", "title": "Channels" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "credentials": { "$ref": "#/components/schemas/SlackCredentials" } }, "type": "object", "required": [ "channels" ], "title": "SlackNotificationSettings", "description": "Configuration for Slack notifications.\n\nAttributes:\n channels: List of Slack channel IDs or names to post to.\n connection_id: connector_organization id of a connected Slack workspace.\n When set and `credentials.access_token` is absent, the delivery path\n resolves the token server-side from the connection (the client never\n persists the token).\n credentials: Slack API authentication credentials. Optional — defaults to\n empty so a connection_id-only target parses; the token is resolved at\n send time." }, "SourceNodeType": { "type": "string", "enum": [ "workbench", "sdk", "task", "assistant", "webhook", "mcp", "a2a", "telegram", "slack", "email", "api" ], "title": "SourceNodeType" }, "SubExecutionResponse": { "properties": { "conversation_id": { "type": "string", "title": "Conversation Id", "description": "The sub-execution id (== its activity thread id)." }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/AgentExecution" }, { "type": "null" } ], "description": "Child execution row (status, result, ai_model, ...)." }, "activity": { "anyOf": [ { "$ref": "#/components/schemas/AgentActivityThread" }, { "type": "null" } ], "description": "Child execution's own activity thread (user, agent, tool calls, ...)." }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ConversationUsage" }, { "type": "null" } ], "description": "Usage for this sub-execution alone. Best-effort; None when upstream fails." }, "feedbacks": { "items": { "$ref": "#/components/schemas/MessageFeedbackItem" }, "type": "array", "title": "Feedbacks", "description": "Per-message feedback rows recorded against this sub-execution." } }, "type": "object", "required": [ "conversation_id" ], "title": "SubExecutionResponse", "description": "One sub-execution's `(execution, activity, usage)` triple.\n\nSame shape as `ConversationResponse` minus the recursive `sub_executions`\nlist — sub-executions don't currently spawn their own sub-executions in\nthe chat-backend surface, so we keep the depth at one level." }, "SubTasksMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "title": "SubTasksMode" }, "TaskBudget-Input": { "properties": { "amount_usd": { "type": "number", "title": "Amount Usd" }, "stop_mode": { "$ref": "#/components/schemas/BudgetStopMode", "default": "finish_inflight" }, "thresholds": { "items": { "$ref": "#/components/schemas/BudgetThreshold" }, "type": "array", "title": "Thresholds", "default": [] }, "notify": { "anyOf": [ { "$ref": "#/components/schemas/BudgetNotify-Input" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount_usd" ], "title": "TaskBudget", "description": "Overall (non-recurring) spend cap for a single task." }, "TaskBudget-Output": { "properties": { "amount_usd": { "type": "number", "title": "Amount Usd" }, "stop_mode": { "$ref": "#/components/schemas/BudgetStopMode", "default": "finish_inflight" }, "thresholds": { "items": { "$ref": "#/components/schemas/BudgetThreshold" }, "type": "array", "title": "Thresholds", "default": [] }, "notify": { "anyOf": [ { "$ref": "#/components/schemas/BudgetNotify-Output" }, { "type": "null" } ] } }, "type": "object", "required": [ "amount_usd" ], "title": "TaskBudget", "description": "Overall (non-recurring) spend cap for a single task." }, "TaskCompactizationError": { "properties": { "trigger": { "type": "string", "enum": [ "auto", "manual", "emergency", "pre_retry" ], "title": "Trigger" }, "error": { "type": "string", "title": "Error" }, "attempt": { "type": "integer", "title": "Attempt", "default": 1 } }, "type": "object", "required": [ "trigger", "error" ], "title": "TaskCompactizationError", "description": "Emitted when a compaction attempt fails." }, "TaskCompactizationOutput": { "properties": { "new_task_prompt": { "type": "string", "minLength": 1, "title": "New Task Prompt", "description": "A continuation prompt that seamlessly continues the running execution. This is NOT a new task - it's the next message in an ongoing conversation. The prompt must:\n1. Resume from where the execution left off (do NOT repeat completed work)\n2. Focus on completing ALL remaining uncompleted tasks\n3. Include specific instructions to mark each task as completed after finishing it\n4. Be written as if you're continuing mid-conversation, not starting fresh\n5. Reference the current state and what still needs to be done\nExample: 'Continuing from where we left off, we still need to complete tasks X, Y, and Z. Let's proceed with task X first, then mark it complete using the appropriate tool.'" }, "task_context": { "type": "string", "minLength": 1, "title": "Task Context", "description": "Comprehensive context for continuing the execution. This context will be injected into the agent's system prompt to maintain execution continuity.\n\nREQUIRED FORMAT (use these exact headings, in this order):\n1) ORIGINAL USER REQUEST\n- Verbatim user_input text and any file references.\n\n2) AGENT INSTRUCTIONS IN EFFECT\n- General description from agent instructions.\n- Role instructions (bullet list).\n- Goals (bullet list).\n- Any constraints or special requirements.\n\n3) EXECUTION SUMMARY\n- What actions were taken (facts only, no speculation).\n- What outputs were produced (facts only).\n\n4) CURRENT STATE AND ARTIFACTS\n- All created artifacts with their identifiers, paths, URLs, or references.\n- Current state of variables, decisions, configurations, and assumptions.\n- Active session or database state if relevant.\n\n5) MESSAGES AND KEY EVIDENCE\n- Compact chronological summary of the conversation flow.\n- Up to 5 verbatim quotes (max 25 words each) capturing critical details.\n\n6) TOOL CALLS AND OBSERVATIONS\n- For each tool call: tool name/id, purpose, key inputs, key outputs, errors.\n- Include plan tool calls (create/get/complete) if they occurred.\n- If no tools used: 'No tool calls were made.'\n\n7) COMPLETED VS UNCOMPLETED TASKS\n- Completed: List with task IDs and titles that are done.\n- Uncompleted: List each task ID, title, and specific reason it's incomplete.\n- CRITICAL: All uncompleted tasks MUST be finished in the continuation.\n\n8) OPEN QUESTIONS AND UNKNOWNS\n- Missing information needed to complete remaining tasks.\n- Blockers or dependencies preventing progress.\n- If none: 'No open questions.'\n\n9) NEXT ACTIONS TO COMPLETE ALL TASKS\n- Ordered list of specific actions to complete each uncompleted task.\n- Each action should reference the task ID it completes.\n- Final action must be to mark all tasks as completed using the plan tools.\n\nACCURACY REQUIREMENTS:\n- Do NOT invent details. Use 'Unknown' if information is missing.\n- Preserve exact names, IDs, numbers, file paths, and user wording.\n- Task completion status must match reality - no implied completion.\n- Focus on actionable, specific continuation steps.\n" } }, "type": "object", "required": [ "new_task_prompt", "task_context" ], "title": "TaskCompactizationOutput" }, "TaskCompactizationProgress": { "properties": { "trigger": { "type": "string", "enum": [ "auto", "manual", "emergency", "pre_retry" ], "title": "Trigger" }, "attempt": { "type": "integer", "title": "Attempt", "default": 1 }, "percent": { "type": "number", "title": "Percent", "default": 0.0 }, "label": { "type": "string", "title": "Label", "default": "Compacting context" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "trigger" ], "title": "TaskCompactizationProgress", "description": "Customer-facing progress update emitted during a running compaction.\n\nDesigned for direct rendering: the UI should only need ``percent``,\n``label`` and the optional ``detail`` line. Internal phase / timing /\nstreaming metrics are intentionally NOT included in the wire payload." }, "TaskCompactizationRetryEvent": { "properties": { "is_retry": { "type": "boolean", "title": "Is Retry" } }, "type": "object", "required": [ "is_retry" ], "title": "TaskCompactizationRetryEvent" }, "TaskCompactizationStarted": { "properties": { "trigger": { "type": "string", "enum": [ "auto", "manual", "emergency", "pre_retry" ], "title": "Trigger" }, "estimated_tokens": { "type": "integer", "title": "Estimated Tokens" }, "message_count": { "type": "integer", "title": "Message Count" }, "threshold": { "type": "integer", "title": "Threshold" }, "attempt": { "type": "integer", "title": "Attempt", "default": 1 }, "focus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus" } }, "type": "object", "required": [ "trigger", "estimated_tokens", "message_count", "threshold" ], "title": "TaskCompactizationStarted", "description": "Emitted when a compaction attempt begins." }, "TaskLevelStrategies-Input": { "properties": { "retry_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationRetryStrategy" }, { "type": "null" } ] }, "iterative_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationIterativeStrategy-Input" }, { "type": "null" } ] }, "stop_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationStopStrategy-Input" }, { "type": "null" } ] }, "max_runs_per_day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runs Per Day" }, "agentic_context_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agentic Context Enabled", "default": false }, "duplication_prevention": { "anyOf": [ { "$ref": "#/components/schemas/DuplicationPreventionSettings" }, { "type": "null" } ] }, "slackbot_formatting_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slackbot Formatting Instructions" }, "budget": { "anyOf": [ { "$ref": "#/components/schemas/BudgetSettings-Input" }, { "type": "null" } ] } }, "type": "object", "title": "TaskLevelStrategies", "description": "Configuration object for task-level execution strategies.\n\nThis model groups optional strategy configurations that control how a task is\nexecuted and managed over time, including retries, iterative execution,\nstopping conditions, and daily run limits.\n\nAttributes:\n retry_strategy:\n Optional retry policy configuration that defines how the task should\n behave when execution fails (e.g., max attempts, backoff rules).\n\n iterative_strategy:\n Optional iterative execution configuration for tasks that may run in\n repeated cycles/steps until completion or a stop condition is met.\n\n stop_strategy:\n Optional stopping policy configuration that defines when the task\n should stop running (e.g., timeout, max iterations, success criteria).\n\n max_runs_per_day:\n Optional limit on how many times the task is allowed to run within a\n 24-hour period. If not set, no explicit daily limit is enforced.\n \n agentic_context_enabled:\n if agentic memory is enabled and accesible to the executor.\n \n slackbot_formatting_instructions:\n Optional SlackBot formatting instructions\n\n budget:\n Optional spend budgets (agent-period and/or per-task) with thresholds." }, "TaskLevelStrategies-Output": { "properties": { "retry_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationRetryStrategy" }, { "type": "null" } ] }, "iterative_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationIterativeStrategy-Output" }, { "type": "null" } ] }, "stop_strategy": { "anyOf": [ { "$ref": "#/components/schemas/OrchestrationStopStrategy-Output" }, { "type": "null" } ] }, "max_runs_per_day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Runs Per Day" }, "agentic_context_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Agentic Context Enabled", "default": false }, "duplication_prevention": { "anyOf": [ { "$ref": "#/components/schemas/DuplicationPreventionSettings" }, { "type": "null" } ] }, "slackbot_formatting_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slackbot Formatting Instructions" }, "budget": { "anyOf": [ { "$ref": "#/components/schemas/BudgetSettings-Output" }, { "type": "null" } ] } }, "type": "object", "title": "TaskLevelStrategies", "description": "Configuration object for task-level execution strategies.\n\nThis model groups optional strategy configurations that control how a task is\nexecuted and managed over time, including retries, iterative execution,\nstopping conditions, and daily run limits.\n\nAttributes:\n retry_strategy:\n Optional retry policy configuration that defines how the task should\n behave when execution fails (e.g., max attempts, backoff rules).\n\n iterative_strategy:\n Optional iterative execution configuration for tasks that may run in\n repeated cycles/steps until completion or a stop condition is met.\n\n stop_strategy:\n Optional stopping policy configuration that defines when the task\n should stop running (e.g., timeout, max iterations, success criteria).\n\n max_runs_per_day:\n Optional limit on how many times the task is allowed to run within a\n 24-hour period. If not set, no explicit daily limit is enforced.\n \n agentic_context_enabled:\n if agentic memory is enabled and accesible to the executor.\n \n slackbot_formatting_instructions:\n Optional SlackBot formatting instructions\n\n budget:\n Optional spend budgets (agent-period and/or per-task) with thresholds." }, "TasksListItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for this execution" }, "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the agent being executed" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "ID of the user that created the task" }, "parent_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Task Id", "description": "ID of the parent task that triggered this task" }, "triggering_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Triggering Agent Id", "description": "ID of the triggering agen that triggered this task" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "ID of the organization that owns the agent" }, "status": { "$ref": "#/components/schemas/xpander_sdk__modules__tasks__models__task__AgentExecutionStatus", "description": "Current execution status" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp when the execution was created" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Timestamp of the last update to this execution" }, "source_node_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Node Type", "description": "Type of the source node that triggered this execution (if any)" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result", "description": "Final result of the execution, if available" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Task title" } }, "type": "object", "required": [ "id", "agent_id", "organization_id", "status" ], "title": "TasksListItem", "description": "Summary representation of a task in list operations.\n\nThis model provides essential information about a task, suitable for\ndisplay and interaction in list views, while enabling efficient retrieval\nof full task details when needed.\n\nAttributes:\n id (str): Unique identifier for this task execution.\n agent_id (str): ID of the agent responsible for executing the task.\n organization_id (str): ID of the organization that owns the agent.\n status (AgentExecutionStatus): Current execution status of the task.\n created_at (Optional[datetime]): Timestamp when the execution was created.\n updated_at (Optional[datetime]): Timestamp of the last update to this execution.\n source_node_type (Optional[str]): The type of the source node that triggered execution.\n result (Optional[str]): Final result of the execution, if available.\n title (Optional[str]): Task title.\n\nMethods:\n aload: Asynchronously load the full task details.\n load: Synchronously load the full task details.\n\nExample:\n >>> tasks = Tasks()\n >>> task_list = tasks.list(agent_id=\"agent123\")\n >>> for item in task_list:\n ... print(f\"Task: {item.id} - Status: {item.status}\")\n ... full_task = item.load() # Load complete task details" }, "ThinkMode": { "type": "string", "enum": [ "default", "harder" ], "title": "ThinkMode" }, "ToolCallRequestReasoning": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "ToolCallRequestReasoning" }, "ToolCatalogItem": { "properties": { "kind": { "$ref": "#/components/schemas/ToolKind", "description": "What kind of tool this is." }, "id": { "type": "string", "title": "Id", "description": "Identifier to attach this tool: connector_id, agent_id, workflow_id, custom_function_id, or mcp registry id." }, "name": { "type": "string", "title": "Name", "description": "Display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "What the tool does." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo", "description": "Logo/icon identifier." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Connector status ('ready' means usable). Connectors only." }, "total_operations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Operations", "description": "Number of operations available. Connectors only." }, "using_built_in_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Built In Auth", "description": "Whether xpander manages auth for this connector." }, "connections": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ConnectionSummary" }, "type": "array" }, { "type": "null" } ], "title": "Connections", "description": "Existing connections for this connector in your org. Connectors only." }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transport", "description": "MCP transport. MCP only." }, "auth_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Type", "description": "MCP auth type. MCP only." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "MCP server URL. MCP only." } }, "type": "object", "required": [ "kind", "id", "name" ], "title": "ToolCatalogItem", "description": "A discoverable, attachable tool returned by GET /tools and /tools/search." }, "ToolKind": { "type": "string", "enum": [ "connector", "agent", "workflow", "custom_function", "mcp" ], "title": "ToolKind", "description": "Kind of attachable tool in the unified catalog." }, "ToolSuggestionChoice": { "properties": { "kind": { "$ref": "#/components/schemas/GatewayToolKind" }, "connector_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connector Id" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "security": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Security" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "access_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Scope" }, "is_service_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Service Account", "default": false }, "headers": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Headers" }, "mcp_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Id" }, "skill_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Name" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "mcp_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Name" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transport" }, "auth_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Type" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key" }, "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "additional_scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Additional Scopes" }, "share_user_token_across_other_agents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Share User Token Across Other Agents", "default": true }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools" } }, "type": "object", "required": [ "kind" ], "title": "ToolSuggestionChoice", "description": "The tool the user picked. For a connector, either reference an existing\nconnection (connection_id) OR carry a new-connection payload (security + meta)\nthe backend persists — OAuth token, API key, AWS creds, etc." }, "UpdateAgentRequest": { "properties": { "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Set automatically by the API service from the authenticated request." }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Set automatically by the API service from the URL path parameter." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable name for the agent." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A brief description of what the agent does." }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Emoji icon displayed next to the agent name." }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "description": "Avatar identifier for the agent's visual representation." }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ], "description": "The agent type. Cannot be changed to 'orchestration' — use the Workflows API." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "description": "Agent status. Set to 'ACTIVE' to enable or 'INACTIVE' to disable the agent." }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "description": "The LLM provider to use." }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "The specific model identifier." }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Reasoning depth control." }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base", "description": "Custom API base URL for the LLM provider." }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key", "description": "Reference key to stored LLM API credentials." }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "description": "Type of credential storage." }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ], "description": "Direct LLM credentials object." }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "description": "Additional HTTP headers for LLM requests." }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "description": "Structured instructions for the agent." }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "description": "Description of expected output format." }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "description": "Response format." }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema for structured output." }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "description": "Execution framework." }, "deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deep Planning", "description": "Enable deep planning mode." }, "enforce_deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce Deep Planning", "description": "Force deep planning for all tasks." }, "tools": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/AddActionTool" }, { "$ref": "#/components/schemas/AddCustomFunctionTool" }, { "$ref": "#/components/schemas/AddMcpTool" }, { "$ref": "#/components/schemas/AddSubAgentTool" }, { "$ref": "#/components/schemas/AddWorkflowTool" }, { "$ref": "#/components/schemas/AddSkillTool" } ], "discriminator": { "propertyName": "type", "mapping": { "action": "#/components/schemas/AddActionTool", "agent": "#/components/schemas/AddSubAgentTool", "custom_function": "#/components/schemas/AddCustomFunctionTool", "mcp": "#/components/schemas/AddMcpTool", "skill": "#/components/schemas/AddSkillTool", "workflow": "#/components/schemas/AddWorkflowTool" } } }, "type": "array" }, { "type": "null" } ], "title": "Tools", "description": "Tools to attach in the unified simplified shape (same payload as POST /v1/agents/{agent_id}/tools). Additive: these are resolved and merged on top of the agent's existing tools (nothing is removed — use DELETE /v1/agents/{agent_id}/tools/{tool_id} to remove). See CreateAgentRequest.tools for the per-type shape." }, "attached_tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Connector" }, "type": "array" }, { "type": "null" } ], "title": "Attached Tools", "description": "Advanced/low-level: connector connections with operation IDs. Prefer `tools`. See CreateAgentRequest.attached_tools for full documentation." }, "graph": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentGraphItem-Input" }, "type": "array" }, { "type": "null" } ], "title": "Graph", "description": "Advanced/low-level: the agent's tool graph. Prefer `tools`. See CreateAgentRequest.graph for full documentation." }, "knowledge_bases": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentKnowledgeBase" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Bases", "description": "Attached knowledge bases." }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "description": "Agent trigger entry points." }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "description": "Deployment infrastructure." }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "description": "Access visibility scope." }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id", "description": "Target deployment environment." }, "connectivity_details": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2A" }, { "$ref": "#/components/schemas/AIAgentConnectivityDetailsCurl" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Connectivity Details", "description": "External agent connection details." }, "agno_settings": { "anyOf": [ { "$ref": "#/components/schemas/AgnoSettings" }, { "type": "null" } ], "description": "Agno framework settings." }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Input" }, { "type": "null" } ], "description": "Task execution strategies." }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Input" }, { "type": "null" } ], "description": "Task notification settings." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice ID for TTS output." }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "description": "Enable NeMo guardrails." }, "is_supervised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Supervised", "description": "Enable supervised mode." }, "is_autonomous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Autonomous", "description": "Run the agent in autonomous mode." }, "discoverable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Discoverable", "description": "Expose the agent to agent-discovery surfaces (e.g. omni)." }, "with_auto_context_management": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "With Auto Context Management", "description": "Run the SDK automatic context optimizer." }, "developer_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Developer Access", "description": "Allow invocation from the developer API and webhooks." }, "should_stage_before_publish": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Stage Before Publish", "description": "Stage edits as a draft before publishing." }, "can_self_schedule": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Can Self Schedule", "description": "Allow the agent to schedule its own future runs." }, "max_self_schedules": { "anyOf": [ { "type": "integer", "maximum": 1000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Self Schedules", "description": "Per-task lifetime cap on chained self-schedules." }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "description": "Enable event streaming." }, "orchestration_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrchestrationNode-Input" }, "type": "array" }, { "type": "null" } ], "title": "Orchestration Nodes", "description": "Workflow orchestration DAG nodes. Only for type=orchestration workflows." }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "description": "Enable OIDC pre-authentication." }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "description": "Allowed OIDC audiences." }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "description": "Forward OIDC token to LLM." }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience", "description": "OIDC audience for LLM access." }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience", "description": "OIDC audience for MCP access." } }, "type": "object", "title": "UpdateAgentRequest", "description": "Request model for updating an existing AI agent.\n\nAll fields are optional — only provide the fields you want to change.\nAt least one field must be provided. Fields not included in the request\nwill retain their current values.\n\nSystem-managed fields like `organization_id`, `agent_id`, `id`, `status`,\n`version`, etc. are set by the service layer and should not be provided." }, "UpdateCustomFunctionRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Updated function name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated function description." }, "source_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Code", "description": "Updated Python source code. If changed, triggers re-analysis." }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/CustomFunctionLimitsModel" }, { "type": "null" } ], "description": "Updated resource limits." } }, "type": "object", "title": "UpdateCustomFunctionRequest", "description": "Request model for updating an existing custom function.\n\nAll fields are optional. If source_code changes, the function will be\nre-analyzed automatically (status transitions to 'analysing' then 'ready')." }, "UpdateScheduledTaskRequest": { "properties": { "cron": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron", "description": "New cron expression." }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "New instruction." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "New label." }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "description": "Pause (false) or resume (true) without losing config." } }, "type": "object", "title": "UpdateScheduledTaskRequest", "description": "Update a recurring scheduled task. Only provided fields change." }, "User-Input": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "email": { "type": "string", "title": "Email" }, "additional_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Additional Attributes" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "default": "member" }, "is_super_admin": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Super Admin", "default": false }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" } }, "type": "object", "required": [ "email" ], "title": "User", "description": "Represents the details of a user.\n\nAttributes:\n id (Optional[str]): The unique identifier of the user. Defaults to None.\n first_name (Optional[str]): The first name of the user. Defaults to None.\n last_name (Optional[str]): The last name of the user. Defaults to None.\n email (str): The email address of the user. This field is required.\n additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.\n role (Optional[str]): The user's role in the organization. Defaults to \"member\".\n is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.\n timezone (Optional[str]): The user's timezone in IANA format (e.g. \"America/New_York\"). Defaults to None." }, "User-Output": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "email": { "type": "string", "title": "Email" }, "additional_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Additional Attributes" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role", "default": "member" }, "is_super_admin": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Super Admin", "default": false }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "display_name": { "type": "string", "title": "Display Name", "readOnly": true } }, "type": "object", "required": [ "email", "display_name" ], "title": "User", "description": "Represents the details of a user.\n\nAttributes:\n id (Optional[str]): The unique identifier of the user. Defaults to None.\n first_name (Optional[str]): The first name of the user. Defaults to None.\n last_name (Optional[str]): The last name of the user. Defaults to None.\n email (str): The email address of the user. This field is required.\n additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.\n role (Optional[str]): The user's role in the organization. Defaults to \"member\".\n is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.\n timezone (Optional[str]): The user's timezone in IANA format (e.g. \"America/New_York\"). Defaults to None." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VectorSearchResult": { "properties": { "content": { "type": "string", "title": "Content", "description": "The content of the document" }, "score": { "type": "number", "title": "Score", "description": "The search result score" } }, "type": "object", "required": [ "content", "score" ], "title": "VectorSearchResult", "description": "Represents the result of a vector search.\n\nAttributes:\n content (str): The content of the document.\n score (float): The search result score." }, "WebhookNotificationSettings": { "properties": { "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body" }, "approve_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approve Button Text", "default": "Approve" }, "deny_button_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deny Button Text", "default": "Deny" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "default": "https://assets.xpanderai.io/xpander-logo.png" }, "url": { "type": "string", "title": "Url" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "default": {} } }, "type": "object", "required": [ "url" ], "title": "WebhookNotificationSettings", "description": "Configuration for webhook notifications.\n\nAttributes:\n url: Target webhook URL to POST notification data.\n headers: Optional HTTP headers to include in the webhook request." }, "WorkflowCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for the workflow. Examples: 'Customer Onboarding Pipeline', 'Daily Report Generator'." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of what this workflow does, its trigger conditions, and expected outcomes.", "default": "" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Emoji icon for the workflow.", "default": "🚀" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "description": "Avatar identifier for visual representation.", "default": "male-avatar" }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "description": "Default LLM provider for LLM-powered nodes (classifiers, guardrails, summarizers) in this workflow. Individual nodes can override this in their own settings.", "default": "amazon_bedrock" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "Default model for LLM-powered nodes. Individual nodes can override.", "default": "global.anthropic.claude-sonnet-5" }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Default reasoning depth for agent nodes in this workflow.", "default": "medium" }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base", "description": "Custom API base URL for the LLM provider." }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key", "description": "Reference key to stored LLM credentials." }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "description": "Credential storage type.", "default": "xpander" }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ], "description": "Direct LLM credentials (prefer llm_credentials_key)." }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "description": "Extra headers for LLM API requests.", "default": {} }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "description": "High-level instructions for the workflow. These provide context to agent nodes within the workflow about the overall workflow purpose." }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "description": "Description of the workflow's expected final output.", "default": "" }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "description": "Format for the workflow's final output.", "default": "markdown" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema for structured workflow output (when output_format is 'json')." }, "orchestration_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrchestrationNode-Input" }, "type": "array" }, { "type": "null" } ], "title": "Orchestration Nodes", "description": "The workflow's execution DAG — an ordered list of nodes that define the execution flow.\nNodes execute sequentially following `next_node_ids` edges. The first non-special node in the list is the entry point.\n\nNode types:\n- **action**: Invokes a connector operation or xpander built-in tool.\n - definition.asset_id: \"{connection_id}_{operation_catalog_id}\" (e.g., \"da84aaaa-525d-4be4-ae60-091ea8bb3ae8_6822eb5f961d9263189b4017\")\n - definition.type: \"action\"\n - definition.instructions: Instructions for the LLM on how to use this action's output\n - definition.schema_override: Optional fixed values for tool input properties\n\n- **agent**: Invokes an AI agent as a step in the workflow.\n - definition.asset_id: the agent UUID\n - definition.type: \"agent\"\n - definition.instructions: Task instructions for the agent\n - definition.persist_thread_id: True to maintain conversation context across runs\n\n- **classifier**: LLM-based routing — classifies input into groups and routes to different downstream nodes.\n - definition.groups: list of {id, name, evaluation_criteria} for each classification category\n - Downstream nodes use condition.group_id to match classifier output\n\n- **guardrail**: LLM-based pass/fail check with \"pass\" and \"fail\" groups.\n - Routes to pass/fail downstream nodes based on evaluation\n\n- **summarizer**: LLM-based text processing — summarizes, extracts, or transforms the previous node's output.\n - definition.instructions: What to summarize/extract\n - The special \"end-summarizer\" (id=\"end-summarizer\") runs at the end of the workflow to produce the final output\n\n- **code**: Executes arbitrary Python code.\n - definition.code: Python source code string\n\n- **wait**: Pauses execution for an external event (webhook or human-in-the-loop approval).\n - definition.type: \"webhook\" or \"hitl\"\n\n- **send_to_end**: Routes execution to end nodes (end-summarizer, end-classifier).\n\n- **parallel**: Executes multiple child nodes simultaneously.\n - definition.nodes: list of child OrchestrationNode objects\n\nFlow control:\n- next_node_ids: list of node IDs to execute after this node completes\n- condition: optional condition on a node for conditional routing (used with classifier/guardrail)\n- The workflow ends when a node has empty next_node_ids, or routes to end-summarizer\n\nStrategies (per-node):\n- retry_strategy: {enabled, max_retries} — retry on failure\n- iterative_strategy: {enabled, max_iterations, end_condition} — loop until condition met\n- stop_strategy: {enabled, stop_on_failure, stop_on_condition} — halt workflow\n\nExample (Extract → Email → Summarize):\n[\n {\"type\": \"action\", \"id\": \"step-1\", \"name\": \"Extract Content\", \"next_node_ids\": [\"step-2\"],\n \"definition\": {\"asset_id\": \"_\", \"type\": \"action\", \"instructions\": \"Extract content from the provided URL\"}},\n {\"type\": \"action\", \"id\": \"step-2\", \"name\": \"Send Email\", \"next_node_ids\": [],\n \"definition\": {\"asset_id\": \"_\", \"type\": \"action\", \"instructions\": \"Send summary to recipient\"}},\n {\"type\": \"summarizer\", \"id\": \"end-summarizer\", \"name\": \"Output Summarizer\", \"next_node_ids\": [],\n \"definition\": {\"instructions\": \"Summarize the workflow execution results\", \"settings\": {\"model_provider\": \"anthropic\", \"model_name\": \"claude-sonnet-5\"}}}\n]", "default": [] }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Input" }, { "type": "null" } ], "description": "Execution strategies: retry (max retries on failure), iterative (repeated execution with stop conditions), stop (halt conditions), max_runs_per_day (daily execution limit), and agentic_context (persistent memory across workflow runs)." }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Input" }, { "type": "null" } ], "description": "Notifications on workflow completion — email, Slack, or webhook on success/error." }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "description": "How this workflow can be triggered: SDK, scheduled task, webhook, assistant UI, MCP, A2A, Telegram, Slack.", "default": [] }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "description": "Where the workflow runs. 'serverless' (recommended) or 'container'.", "default": "serverless" }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "description": "Who can access this workflow. 'personal' or 'organizational'.", "default": "personal" }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id", "description": "Target deployment environment." }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "description": "Enable NeMo guardrails.", "default": false }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "description": "Enable real-time event streaming.", "default": true }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "description": "Require OIDC pre-authentication before workflow execution.", "default": false }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "description": "Allowed OIDC token audiences.", "default": [] }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "description": "Forward OIDC token to LLM provider.", "default": false }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience", "description": "OIDC audience for LLM access." }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience", "description": "OIDC audience for MCP server access." } }, "type": "object", "required": [ "name" ], "title": "WorkflowCreateRequest", "description": "Request model for creating a new workflow on the xpander.ai platform.\n\nA workflow is a directed acyclic graph (DAG) of execution nodes. Each node\ncan be an agent invocation, a classifier (LLM-based routing), a code block,\na guardrail, a summarizer, a wait/HITL node, or an action (API call).\n\nOnly `name` is required. The workflow's type is automatically set to\n'orchestration' — do not use the Agents API to create workflows.\n\nAgent-specific fields (graph, attached_tools, delegation_*, deep_planning,\nframework, agno_settings, connectivity_details) are not applicable to\nworkflows and are excluded from this model." }, "WorkflowNodeView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Node id (use to update/remove the node)." }, "type": { "type": "string", "title": "Type", "description": "Node type (action, agent, classifier, ...)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Node name." }, "next_node_ids": { "items": { "type": "string" }, "type": "array", "title": "Next Node Ids", "description": "Ids of nodes that run after this one.", "default": [] }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id", "description": "Referenced asset id for action/agent nodes." }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id", "description": "Connection id parsed from an action node's asset_id." }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id", "description": "Operation catalog id parsed from an action node's asset_id." }, "target_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Agent Id", "description": "Agent id for agent nodes." } }, "type": "object", "required": [ "id", "type" ], "title": "WorkflowNodeView", "description": "Simplified view of one orchestration node." }, "WorkflowResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "unique_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unique Name" }, "origin_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin Template" }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id" }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "default": "serverless" }, "prompts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompts", "default": [] }, "is_latest": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Latest", "default": false }, "has_pending_changes": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Pending Changes", "default": false }, "deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deep Planning", "default": true }, "enforce_deep_planning": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enforce Deep Planning", "default": true }, "use_agent_gateway": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Agent Gateway", "default": false }, "name": { "type": "string", "title": "Name" }, "connectivity_details": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentConnectivityDetailsA2A" }, { "$ref": "#/components/schemas/AIAgentConnectivityDetailsCurl" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Connectivity Details", "default": {} }, "framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Framework", "default": "agno" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "default": "" }, "tools": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Tools", "default": [] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "default": "🚀" }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "default": "male-avatar" }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "default": [] }, "attached_tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Connector" }, "type": "array" }, { "type": "null" } ], "title": "Attached Tools", "default": [] }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "default": "personal" }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "default": { "role": [], "goal": [], "general": "" } }, "oas": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Oas", "default": {} }, "graph": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentGraphItem-Output" }, "type": "array" }, { "type": "null" } ], "title": "Graph", "default": [] }, "is_omni": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Omni", "default": false }, "skills": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Skills", "default": [] }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "default": "ACTIVE" }, "knowledge_bases": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentKnowledgeBase" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Bases", "default": [] }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "default": 1 }, "organization_id": { "type": "string", "title": "Organization Id" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/AgentType" }, { "type": "null" } ] }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "default": false }, "deletable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Deletable", "default": true }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "default": "amazon_bedrock" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "default": "global.anthropic.claude-sonnet-5" }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "default": "medium" }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base" }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "default": "markdown" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema" }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key" }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "default": "xpander" }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ] }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "default": {} }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "default": "" }, "agno_settings": { "anyOf": [ { "$ref": "#/components/schemas/AgnoSettings" }, { "type": "null" } ], "default": { "session_storage": true, "learning": false, "agent_memories": false, "agentic_culture": false, "user_memories": false, "agentic_memory": false, "session_summaries": false, "num_history_runs": 50, "max_tool_calls_from_history": 0, "tool_call_limit": 0, "coordinate_mode": true, "pii_detection_enabled": false, "pii_detection_mask": true, "prompt_injection_detection_enabled": false, "openai_moderation_enabled": false, "reasoning_tools_enabled": true, "max_plan_retries": 15 } }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "default": true }, "is_supervised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Supervised", "default": false }, "orchestration_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrchestrationNode-Output" }, "type": "array" }, { "type": "null" } ], "title": "Orchestration Nodes", "default": [] }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Output" }, { "type": "null" } ], "default": {} }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Output" }, { "type": "null" } ] }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "default": false }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "default": [] }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "default": false }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience" }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience" }, "can_self_schedule": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Can Self Schedule", "default": false }, "max_self_schedules": { "anyOf": [ { "type": "integer", "maximum": 1000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Self Schedules", "default": 3 }, "use_dynamic_tools": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Dynamic Tools", "default": false }, "workspace_tools_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Workspace Tools Enabled", "default": true }, "is_autonomous": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Autonomous", "default": false }, "discoverable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Discoverable", "default": true }, "with_auto_context_management": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "With Auto Context Management", "default": true }, "developer_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Developer Access", "default": true }, "should_stage_before_publish": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Should Stage Before Publish", "default": true }, "webhook_url": { "type": "string", "title": "Webhook Url", "readOnly": true } }, "type": "object", "required": [ "name", "organization_id", "webhook_url" ], "title": "WorkflowResponse", "description": "Response model for workflow endpoints.\n\nInherits from AIAgent but excludes agent-specific fields that are not\nrelevant to workflows (orchestrations). This provides a clean API surface\nfor workflow consumers without exposing confusing agent-only concepts.\n\nThe workflow's execution logic is defined in `orchestration_nodes` — a DAG\nof typed nodes. Agent-specific fields like `graph`, `attached_tools`,\n`delegation_*`, `framework`, and `agno_settings` are hidden." }, "WorkflowUpdateRequest": { "properties": { "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Workflow name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Workflow description." }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon", "description": "Emoji icon." }, "avatar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar", "description": "Avatar identifier." }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AgentStatus" }, { "type": "null" } ], "description": "Workflow status: 'ACTIVE' or 'INACTIVE'." }, "model_provider": { "anyOf": [ { "$ref": "#/components/schemas/LLMModelProvider" }, { "type": "null" } ], "description": "Default LLM provider." }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name", "description": "Default model name." }, "llm_reasoning_effort": { "anyOf": [ { "$ref": "#/components/schemas/LLMReasoningEffort" }, { "type": "null" } ], "description": "Reasoning depth." }, "llm_api_base": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Api Base", "description": "Custom LLM API base URL." }, "llm_credentials_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm Credentials Key", "description": "LLM credentials key." }, "llm_credentials_key_type": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentialsKeyType" }, { "type": "null" } ], "description": "Credential type." }, "llm_credentials": { "anyOf": [ { "$ref": "#/components/schemas/LLMCredentials" }, { "type": "null" } ], "description": "Direct LLM credentials." }, "llm_extra_headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Llm Extra Headers", "description": "Extra LLM headers." }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentInstructions" }, { "type": "null" } ], "description": "Workflow instructions." }, "expected_output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Output", "description": "Expected output description." }, "output_format": { "anyOf": [ { "$ref": "#/components/schemas/OutputFormat" }, { "type": "null" } ], "description": "Output format." }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "JSON Schema for output." }, "orchestration_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrchestrationNode-Input" }, "type": "array" }, { "type": "null" } ], "title": "Orchestration Nodes", "description": "Updated workflow DAG nodes." }, "task_level_strategies": { "anyOf": [ { "$ref": "#/components/schemas/TaskLevelStrategies-Input" }, { "type": "null" } ], "description": "Execution strategies." }, "notification_settings": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Input" }, { "type": "null" } ], "description": "Notification settings." }, "source_nodes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AIAgentSourceNode" }, "type": "array" }, { "type": "null" } ], "title": "Source Nodes", "description": "Trigger source nodes." }, "deployment_type": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentDeploymentType" }, { "type": "null" } ], "description": "Deployment type." }, "access_scope": { "anyOf": [ { "$ref": "#/components/schemas/AIAgentAccessScope" }, { "type": "null" } ], "description": "Access scope." }, "environment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Environment Id", "description": "Target environment." }, "using_nemo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Using Nemo", "description": "NeMo guardrails." }, "on_prem_event_streaming": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "On Prem Event Streaming", "description": "Event streaming." }, "use_oidc_pre_auth": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth", "description": "OIDC pre-auth." }, "pre_auth_audiences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Pre Auth Audiences", "description": "OIDC audiences." }, "use_oidc_pre_auth_token_for_llm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Oidc Pre Auth Token For Llm", "description": "Forward OIDC to LLM." }, "oidc_pre_auth_token_llm_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Llm Audience", "description": "OIDC LLM audience." }, "oidc_pre_auth_token_mcp_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oidc Pre Auth Token Mcp Audience", "description": "OIDC MCP audience." } }, "type": "object", "title": "WorkflowUpdateRequest", "description": "Request model for updating an existing workflow.\n\nAll fields are optional — only provide the fields you want to change.\nAt least one field must be provided. The workflow type remains 'orchestration'\nand cannot be changed." }, "src__models__knowledge__documents__KnowledgeBaseDocumentItem": { "properties": { "kb_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kb Id", "description": "KB identifier" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Document unique identifier" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Document name" }, "document_url": { "type": "string", "title": "Document Url", "description": "Document URL" } }, "type": "object", "required": [ "document_url" ], "title": "KnowledgeBaseDocumentItem", "description": "Knowledge base document metadata model." }, "xpander_dev_utils__models__executions__AgentExecutionStatus": { "type": "string", "enum": [ "pending", "executing", "paused", "error", "failed", "completed", "stopped" ], "title": "AgentExecutionStatus" }, "xpander_dev_utils__models__knowledge_bases__KnowledgeBaseDocumentItem": { "properties": { "kb_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kb Id", "description": "KB identifier" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Document unique identifier" }, "document_url": { "type": "string", "title": "Document Url", "description": "Document URL" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id", "description": "Organization ID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Doc name" }, "raw_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Raw Data", "description": "Raw data (textual)" }, "local_env": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Local Env", "description": "Is local", "default": false }, "sync": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sync", "description": "Is sync?", "default": false } }, "type": "object", "required": [ "document_url" ], "title": "KnowledgeBaseDocumentItem", "description": "Represents a document item within a Knowledge Base.\n\nAttributes:\n kb_id (Optional[str]): KB identifier.\n id (str): Document unique identifier.\n document_url (str): URL of the document.\n raw_data (Optional[str]): Raw textual data of the document.\n local_env (Optional[bool]): Indicates if the document is in a local environment. Defaults to False." }, "xpander_sdk__modules__tasks__models__task__AgentExecutionStatus": { "type": "string", "enum": [ "pending", "executing", "paused", "error", "failed", "completed", "stopped" ], "title": "AgentExecutionStatus", "description": "Enumeration of possible execution statuses for an agent task.\n\nValues:\n Pending: Task is pending execution.\n Executing: Task is currently executing.\n Paused: Task execution is paused.\n Error: Task encountered an error during execution.\n Failed: Task execution failed to complete successfully.\n Completed: Task execution completed successfully.\n Stopped: Task execution was stopped by the user.\n\nExample:\n >>> status = AgentExecutionStatus.Executing\n >>> print(status.value) # \"executing\"" }, "InboxConversation": { "properties": { "id": { "type": "string", "title": "Id", "description": "Conversation (execution) id." }, "source": { "type": "string", "title": "Source", "description": "Inbound channel: email or whatsapp." }, "title": { "type": "string", "title": "Title", "default": "", "description": "Conversation title." }, "status": { "type": "string", "title": "Status", "default": "", "description": "Execution status." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id", "description": "Profile id or address of whoever started the conversation." }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender", "description": "Sender email address; resolved from the profile when the row carries an id." }, "created_at": { "type": "string", "title": "Created At", "default": "", "description": "Creation timestamp (ISO)." }, "updated_at": { "type": "string", "title": "Updated At", "default": "", "description": "Last update timestamp (ISO)." } }, "type": "object", "required": [ "id", "source" ], "title": "InboxConversation", "description": "One inbound email/WhatsApp conversation of an agent." }, "InboxConversationsResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/InboxConversation" }, "type": "array", "title": "Items" }, "sources_enabled": { "items": { "type": "string" }, "type": "array", "title": "Sources Enabled", "description": "Inbox channels enabled on this agent; empty means no inbox at all." }, "total": { "type": "integer", "title": "Total", "default": 0, "description": "Matches before the limit cap was applied." } }, "type": "object", "title": "InboxConversationsResponse", "description": "The agent's inbound inbox, filtered." }, "HarnessPermissionMode": { "type": "string", "enum": [ "full", "gated" ], "title": "HarnessPermissionMode", "description": "Permission mode for an external-harness agent's workspace commands. 'full' runs them; 'gated' holds the ones matched by gated_commands for approval." }, "HarnessCli": { "type": "string", "enum": [ "claude-code", "codex", "opencode", "xpander" ], "title": "HarnessCli", "description": "A CLI the harness container can run." }, "HarnessRuntime": { "type": "string", "enum": [ "fleet", "legacy" ], "title": "HarnessRuntime", "description": "Where a harness agent's turns run: the shared executor fleet ('fleet', the default for new agents) or one always-on pod per agent ('legacy')." }, "HarnessResources": { "properties": { "memory_limit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory Limit", "description": "Memory ceiling per turn, e.g. '24Gi', '512Mi' or a byte count (128Mi to 24Gi)." }, "memory_high": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory High", "description": "Throttle threshold below memory_limit; set together with memory_limit." }, "cpu": { "anyOf": [ { "type": "number", "minimum": 0.1, "maximum": 8.0 }, { "type": "null" } ], "title": "Cpu", "description": "CPU cores per turn (0.1 to 8; '500m' is accepted)." }, "pids": { "anyOf": [ { "type": "integer", "minimum": 64, "maximum": 8192 }, { "type": "null" } ], "title": "Pids", "description": "Process limit per turn (64 to 8192)." }, "disk": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disk", "description": "Disk ceiling per turn, e.g. '10Gi' (1Gi to 50Gi)." } }, "additionalProperties": false, "type": "object", "title": "HarnessResources", "description": "Per-turn sandbox ceilings for a harness agent on the fleet; every unset field keeps the runner default. A value past the platform caps is rejected with 422." }, "HarnessSettings": { "properties": { "permission_mode": { "anyOf": [ { "$ref": "#/components/schemas/HarnessPermissionMode" }, { "type": "null" } ], "default": "full" }, "max_concurrent_tasks": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 64 }, { "type": "null" } ], "title": "Max Concurrent Tasks", "default": 12 }, "workdir_gc_days": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Workdir Gc Days", "default": 14, "description": "Days an idle working directory is kept." }, "image_tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Tag", "description": "Pinned build of the platform harness image; null means the current build." }, "approval_hold_hours": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 72 }, { "type": "null" } ], "title": "Approval Hold Hours", "default": 4, "description": "Hours a turn waits for an approval before giving up." }, "cli_auto_update": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cli Auto Update", "default": true, "description": "Platform-managed; always reads back true." }, "default_cli": { "anyOf": [ { "$ref": "#/components/schemas/HarnessCli" }, { "type": "null" } ], "description": "CLI that runs the agent's turns. A new agent gets 'claude-code'." }, "models": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Models", "default": {}, "description": "One model per CLI, keyed by CLI name, e.g. {\"claude-code\": \"claude-sonnet-5\"}. A missing key means the platform default for that CLI." }, "available_clis": { "items": { "$ref": "#/components/schemas/HarnessCli" }, "type": "array", "title": "Available Clis", "default": [], "description": "CLIs the agent's runtime reports as installed; read-only." }, "runtime": { "anyOf": [ { "$ref": "#/components/schemas/HarnessRuntime" }, { "type": "null" } ], "description": "'fleet' for new agents; 'legacy' keeps one pod per agent." }, "resources": { "anyOf": [ { "$ref": "#/components/schemas/HarnessResources" }, { "type": "null" } ] } }, "type": "object", "title": "HarnessSettings", "description": "Runtime settings for an agent whose framework is 'external-harness'; null for 'agno' agents." }, "SkillVisibility": { "type": "string", "enum": [ "org", "restricted", "agent" ], "title": "SkillVisibility", "description": "Who may hold the skill: `org` is any agent in the organization, `restricted` is the agents listed in `agents`, `agent` is the one owner agent listed in `agents`." }, "SkillAccessScope": { "type": "string", "enum": [ "personal", "organizational" ], "title": "SkillAccessScope", "description": "Which catalog the skill sits in: the publisher's personal catalog or the organization's." }, "SkillPublishMetadata": { "properties": { "visibility": { "$ref": "#/components/schemas/SkillVisibility", "default": "org" }, "agents": { "items": { "type": "string" }, "type": "array", "title": "Agents", "default": [], "description": "Agent ids allowed to hold the skill. Required for `restricted` (one or more) and `agent` (exactly one); ignored for `org`." }, "access_scope": { "$ref": "#/components/schemas/SkillAccessScope", "default": "organizational" }, "users": { "items": { "type": "string" }, "type": "array", "title": "Users", "default": [], "description": "User ids of the Manage access user audience: who sees the skill in the catalog." }, "groups": { "items": { "type": "string" }, "type": "array", "title": "Groups", "default": [], "description": "Group ids of the Manage access group audience: who sees the skill in the catalog." } }, "type": "object", "title": "SkillPublishMetadata", "description": "The access contract of one skill, mirrored from its `xpander.yaml`." }, "PublishManagedBy": { "properties": { "repo": { "type": "string", "title": "Repo", "description": "Repository that owns the skills, as `owner/name`.", "examples": [ "acme/agent-skills" ] }, "path_prefix": { "type": "string", "title": "Path Prefix", "default": "", "description": "Folder inside the repo that holds the skill folders. Skills are matched for `archive_missing` by repo and prefix." }, "ref": { "type": "string", "title": "Ref", "description": "Git ref that was merged.", "examples": [ "refs/heads/main" ] }, "commit": { "type": "string", "title": "Commit", "description": "Commit SHA the bundles were built from." }, "run_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Url", "description": "Link to the CI run that made the call." } }, "type": "object", "required": [ "repo", "ref", "commit" ], "title": "PublishManagedBy", "description": "Where the skills come from. Stored on each published skill so the registry knows which repository manages it." }, "PublishSkillItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Skill name, the `name` in `SKILL.md` frontmatter. It is the key used in `results` and `archived`." }, "path": { "type": "string", "title": "Path", "description": "Path of the skill folder inside the repo, relative to `path_prefix`." }, "skill_md": { "type": "string", "title": "Skill Md", "description": "Contents of `SKILL.md`." }, "bundle_b64": { "type": "string", "title": "Bundle B64", "description": "The skill folder as a base64-encoded tar.gz, `SKILL.md` and `xpander.yaml` included." }, "sha256": { "type": "string", "title": "Sha256", "description": "Hex SHA-256 of the decoded bundle. A matching value on an existing skill returns `unchanged`." }, "metadata": { "$ref": "#/components/schemas/SkillPublishMetadata" } }, "type": "object", "required": [ "name", "path", "skill_md", "bundle_b64", "sha256", "metadata" ], "title": "PublishSkillItem" }, "PublishSkillsRequest": { "properties": { "managed_by": { "$ref": "#/components/schemas/PublishManagedBy" }, "archive_missing": { "type": "boolean", "title": "Archive Missing", "default": false, "description": "Archive skills that this repo and prefix published earlier and that are absent from `skills`. Their names are returned in `archived`." }, "dry_run": { "type": "boolean", "title": "Dry Run", "default": false, "description": "Compute every outcome without writing to the registry." }, "skills": { "items": { "$ref": "#/components/schemas/PublishSkillItem" }, "type": "array", "minItems": 1, "maxItems": 25, "title": "Skills", "description": "Up to 25 skills per call." } }, "type": "object", "required": [ "managed_by", "skills" ], "title": "PublishSkillsRequest" }, "PublishSkillOutcome": { "type": "string", "enum": [ "created", "updated", "unchanged", "archived", "error" ], "title": "PublishSkillOutcome" }, "PublishSkillResult": { "properties": { "name": { "type": "string", "title": "Name" }, "outcome": { "$ref": "#/components/schemas/PublishSkillOutcome" }, "skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Id", "description": "Registry id of the skill, when the registry holds one." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Short human-readable note on the outcome, for example what changed or why it failed." } }, "type": "object", "required": [ "name", "outcome" ], "title": "PublishSkillResult" }, "PublishSkillsResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/PublishSkillResult" }, "type": "array", "title": "Results", "description": "One entry per skill in the request, in request order." }, "archived": { "items": { "type": "string" }, "type": "array", "title": "Archived", "default": [], "description": "Names of skills archived by `archive_missing`." }, "warnings": { "items": { "type": "string" }, "type": "array", "title": "Warnings", "default": [], "description": "Non-fatal notes about the call." } }, "type": "object", "required": [ "results" ], "title": "PublishSkillsResponse" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "description": "API Key for authentication", "in": "header", "name": "x-api-key" } } } }