Create a new SDK-driven task and kick off its first turn.
Single endpoint does three things atomically from the caller’s
perspective:
Verifies the body’s agent_id matches the agent bound to
the presented API key. Mismatch -> 404 agent_not_found
(404 not 403, so the existence of unrelated agents isn’t
leaked via error code).
Persists a new :class:Task row owned by the agent’s user,
with source='sdk' and input set to the user message.
Also persists the first user message to
task_chat_messages so the existing background execution
path can consume it without special-casing this entry point.
Schedules background execution via
start_task_in_background (which uses the same coroutine
the WebSocket handler does). Returns 202 immediately —
callers poll GET /v1/chat/tasks/{task_id} to observe the
eventual completed / failed status.
Args:
request: Validated :class:CreateTaskRequest. message.content
is guaranteed non-empty by Pydantic; agent_id is the
target agent the SDK caller wants to invoke.
authed: (Agent, AgentApiKey) tuple resolved by the auth
dependency. The agent here is the key-bound agent, the
single source of truth for what this caller may touch.
db: SQLAlchemy session.
Returns:
:class:CreateTaskResponse with the new task_id,
agent_id, status='running' (the atomic claim inside
the handler flips the row from PENDING to RUNNING before the
response is sent), and created_at for the caller to
start polling from.
Raises:
V1ApiError 401: missing/invalid/revoked key (raised inside
get_agent_from_api_key; envelope is uniform with
other auth failures).
V1ApiError 404: request.agent_id != authed_agent.id.
500 (V1 envelope): any unexpected exception — the global
handler in web/app.py translates to
{"error": {"code": "internal_error", ...}} and the raw
exception message stays out of the response.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Body for POST /v1/chat/tasks.
agent_id is required and must match the agent bound to the
presented API key; the server enforces body.agent_id == authed.agent.id and returns 404 agent_not_found on mismatch.
Dispatch class to request for this task: 'interactive' or 'batch'. Omit it or send null to let the server decide. Whether the deployment honors the request is its own setting; the response's 'dispatch_class' shows the class the start command was given.
Priority of this task's commands, an integer from -10 to 10; higher goes first. Omit it or send null for 0. It takes effect only where the deployment dispatches fairly across accounts, and only orders commands of the same account and the same dispatch class. Messages appended to the task and manual resumes inherit it.
Required range: -10 <= x <= 10
Response
Successful Response
POST /v1/chat/tasks -> 202 Accepted response.
The task has been persisted, claimed as RUNNING in the same
transaction, and queued for background execution; callers poll
GET /v1/chat/tasks/{task_id} to observe the transition
running -> completed/failed.
Initial status, 'running' in the 202 response (the atomic claim inside POST commits the status flip before the response is sent). Use GET /v1/chat/tasks/{task_id} to observe later transitions.
Dispatch class the start command was given, which is the requested class only when the deployment accepted it. Null when the server runs the task in this process rather than through the dispatch queue. Later commands on the task are not reported here.
Available options:
interactive,
batch
⌘I
{"docsConfig":{"theme":"willow","$schema":"https://mintlify.com/docs.json","name":"Xagent","colors":{"primary":"#6A0CF5","light":"#AB66F3","dark":"#5A0BD3"},"logo":{"light":"https://mintcdn.com/xorbitsinc/iidWB4pLRl1L1AC4/images/logo/xagent-logo-light.png?fit=max\u0026auto=format\u0026n=iidWB4pLRl1L1AC4\u0026q=85\u0026s=d45e51a54fae46740727ec694e10dbda","dark":"https://mintcdn.com/xorbitsinc/iidWB4pLRl1L1AC4/images/logo/xagent-logo-dark.png?fit=max\u0026auto=format\u0026n=iidWB4pLRl1L1AC4\u0026q=85\u0026s=6c316247f095e6ffc81aa2fd470b492c"},"favicon":"https://mintcdn.com/xorbitsinc/iidWB4pLRl1L1AC4/favicon.png?fit=max\u0026auto=format\u0026n=iidWB4pLRl1L1AC4\u0026q=85\u0026s=25d06ff0abe8bcf002173d802165bbe0","api":{"openapi":"api-reference/openapi.json"},"navbar":{"links":[{"href":"https://github.com/xorbitsai/xagent","label":"GitHub"}],"primary":{"type":"button","label":"Get Started","href":"/quickstart"}},"footer":{"socials":{"github":"https://github.com/xorbitsai/xagent","x":"https://x.com/xorbitsai"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"xorbitsinc","hasAudioNarration":false,"actualSubdomain":"xorbitsinc","customDomains":["docs.xagent.co"],"gitSource":{"type":"github","owner":"xorbitsai","repo":"xagent-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae55edaa11e082850869934","collectionId":"0bfcd2b1-0e76-49e2-b17b-87d132f9c8f4","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae55edaa11e082850869934"},"entitlements":{},"buildId":"6ae55edaa11e082850869934","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"en","tag":"API Reference","count":199},{"language":"en","tag":"Models","count":38},{"language":"en","tag":"Use Xagent","count":29},{"language":"en","tag":"Agents","count":21},{"language":"en","tag":"Authentication","count":20},{"language":"en","tag":"Workforces","count":19},{"language":"en","tag":"Knowledge Base","count":18},{"language":"en","tag":"Files","count":13},{"language":"en","tag":"Tools","count":13},{"language":"en","tag":"MCP","count":11}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"custom.css","content":"html[data-page-mode=wide] #content-area:has(.xagent-homewide),html[data-page-mode=wide] #content-area:has(.xagent-homewide) #content,html[data-page-mode=wide] #content-area:has(.xagent-homewide) .xagent-homewide,html[data-page-mode=wide] #content-area:has(.xagent-homewide)>div,html[data-page-mode=wide] #content-area:has(.xagent-homewide)>div>div{width:100%;max-width:none}html[data-page-mode=wide] #content-area:has(.xagent-homewide) div:has(>.xagent-homewide){box-sizing:border-box;padding-inline:clamp(1.5rem,3vw,4rem)}"}],"page":{"pagePath":"api-reference/sdk-v1/create-chat-task","slug":"/api-reference/sdk-v1/create-chat-task","pageMetadata":{"openapi":"post /v1/chat/tasks","title":"Create Chat Task","description":"Create a new SDK-driven task and kick off its first turn.\n\nSingle endpoint does three things atomically from the caller's\nperspective:\n\n 1. Verifies the body's ``agent_id`` matches the agent bound to\n the presented API key. Mismatch -> 404 ``agent_not_found``\n (404 not 403, so the existence of unrelated agents isn't\n leaked via error code).\n 2. Persists a new :class:`Task` row owned by the agent's user,\n with ``source='sdk'`` and ``input`` set to the user message.\n Also persists the first user message to\n ``task_chat_messages`` so the existing background execution\n path can consume it without special-casing this entry point.\n 3. Schedules background execution via\n ``start_task_in_background`` (which uses the same coroutine\n the WebSocket handler does). Returns 202 immediately --\n callers poll ``GET /v1/chat/tasks/{task_id}`` to observe the\n eventual ``completed`` / ``failed`` status.\n\nArgs:\n request: Validated :class:`CreateTaskRequest`. ``message.content``\n is guaranteed non-empty by Pydantic; ``agent_id`` is the\n target agent the SDK caller wants to invoke.\n authed: ``(Agent, AgentApiKey)`` tuple resolved by the auth\n dependency. The agent here is the *key-bound* agent, the\n single source of truth for what this caller may touch.\n db: SQLAlchemy session.\n\nReturns:\n :class:`CreateTaskResponse` with the new ``task_id``,\n ``agent_id``, ``status='running'`` (the atomic claim inside\n the handler flips the row from PENDING to RUNNING before the\n response is sent), and ``created_at`` for the caller to\n start polling from.\n\nRaises:\n V1ApiError 401: missing/invalid/revoked key (raised inside\n ``get_agent_from_api_key``; envelope is uniform with\n other auth failures).\n V1ApiError 404: ``request.agent_id != authed_agent.id``.\n 500 (V1 envelope): any unexpected exception -- the global\n handler in ``web/app.py`` translates to\n ``{\"error\": {\"code\": \"internal_error\", ...}}`` and the raw\n exception message stays out of the response.","href":"/api-reference/sdk-v1/create-chat-task"},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n em: \"em\",\n li: \"li\",\n ol: \"ol\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a new SDK-driven task and kick off its first turn.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Single endpoint does three things atomically from the caller’s\\nperspective:\"\n }), \"\\n\", _jsxs(_components.ol, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Verifies the body’s \", _jsx(_components.code, {\n children: \"agent_id\"\n }), \" matches the agent bound to\\nthe presented API key. Mismatch -> 404 \", _jsx(_components.code, {\n children: \"agent_not_found\"\n }), \"\\n(404 not 403, so the existence of unrelated agents isn’t\\nleaked via error code).\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Persists a new :class:\", _jsx(_components.code, {\n children: \"Task\"\n }), \" row owned by the agent’s user,\\nwith \", _jsx(_components.code, {\n children: \"source='sdk'\"\n }), \" and \", _jsx(_components.code, {\n children: \"input\"\n }), \" set to the user message.\\nAlso persists the first user message to\\n\", _jsx(_components.code, {\n children: \"task_chat_messages\"\n }), \" so the existing background execution\\npath can consume it without special-casing this entry point.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Schedules background execution via\\n\", _jsx(_components.code, {\n children: \"start_task_in_background\"\n }), \" (which uses the same coroutine\\nthe WebSocket handler does). Returns 202 immediately —\\ncallers poll \", _jsx(_components.code, {\n children: \"GET /v1/chat/tasks/{task_id}\"\n }), \" to observe the\\neventual \", _jsx(_components.code, {\n children: \"completed\"\n }), \" / \", _jsx(_components.code, {\n children: \"failed\"\n }), \" status.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Args:\\nrequest: Validated :class:\", _jsx(_components.code, {\n children: \"CreateTaskRequest\"\n }), \". \", _jsx(_components.code, {\n children: \"message.content\"\n }), \"\\nis guaranteed non-empty by Pydantic; \", _jsx(_components.code, {\n children: \"agent_id\"\n }), \" is the\\ntarget agent the SDK caller wants to invoke.\\nauthed: \", _jsx(_components.code, {\n children: \"(Agent, AgentApiKey)\"\n }), \" tuple resolved by the auth\\ndependency. The agent here is the \", _jsx(_components.em, {\n children: \"key-bound\"\n }), \" agent, the\\nsingle source of truth for what this caller may touch.\\ndb: SQLAlchemy session.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Returns:\\n:class:\", _jsx(_components.code, {\n children: \"CreateTaskResponse\"\n }), \" with the new \", _jsx(_components.code, {\n children: \"task_id\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"agent_id\"\n }), \", \", _jsx(_components.code, {\n children: \"status='running'\"\n }), \" (the atomic claim inside\\nthe handler flips the row from PENDING to RUNNING before the\\nresponse is sent), and \", _jsx(_components.code, {\n children: \"created_at\"\n }), \" for the caller to\\nstart polling from.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Raises:\\nV1ApiError 401: missing/invalid/revoked key (raised inside\\n\", _jsx(_components.code, {\n children: \"get_agent_from_api_key\"\n }), \"; envelope is uniform with\\nother auth failures).\\nV1ApiError 404: \", _jsx(_components.code, {\n children: \"request.agent_id != authed_agent.id\"\n }), \".\\n500 (V1 envelope): any unexpected exception — the global\\nhandler in \", _jsx(_components.code, {\n children: \"web/app.py\"\n }), \" translates to\\n\", _jsx(_components.code, {\n children: \"{\\\"error\\\": {\\\"code\\\": \\\"internal_error\\\", ...}}\"\n }), \" and the raw\\nexception message stays out of the response.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"openapi":"post /v1/chat/tasks","title":"Create Chat Task","description":"Create a new SDK-driven task and kick off its first turn.\n\nSingle endpoint does three things atomically from the caller's\nperspective:\n\n 1. Verifies the body's ``agent_id`` matches the agent bound to\n the presented API key. Mismatch -> 404 ``agent_not_found``\n (404 not 403, so the existence of unrelated agents isn't\n leaked via error code).\n 2. Persists a new :class:`Task` row owned by the agent's user,\n with ``source='sdk'`` and ``input`` set to the user message.\n Also persists the first user message to\n ``task_chat_messages`` so the existing background execution\n path can consume it without special-casing this entry point.\n 3. Schedules background execution via\n ``start_task_in_background`` (which uses the same coroutine\n the WebSocket handler does). Returns 202 immediately --\n callers poll ``GET /v1/chat/tasks/{task_id}`` to observe the\n eventual ``completed`` / ``failed`` status.\n\nArgs:\n request: Validated :class:`CreateTaskRequest`. ``message.content``\n is guaranteed non-empty by Pydantic; ``agent_id`` is the\n target agent the SDK caller wants to invoke.\n authed: ``(Agent, AgentApiKey)`` tuple resolved by the auth\n dependency. The agent here is the *key-bound* agent, the\n single source of truth for what this caller may touch.\n db: SQLAlchemy session.\n\nReturns:\n :class:`CreateTaskResponse` with the new ``task_id``,\n ``agent_id``, ``status='running'`` (the atomic claim inside\n the handler flips the row from PENDING to RUNNING before the\n response is sent), and ``created_at`` for the caller to\n start polling from.\n\nRaises:\n V1ApiError 401: missing/invalid/revoked key (raised inside\n ``get_agent_from_api_key``; envelope is uniform with\n other auth failures).\n V1ApiError 404: ``request.agent_id != authed_agent.id``.\n 500 (V1 envelope): any unexpected exception -- the global\n handler in ``web/app.py`` translates to\n ``{\"error\": {\"code\": \"internal_error\", ...}}`` and the raw\n exception message stays out of the response.","href":"/api-reference/sdk-v1/create-chat-task"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["sdk-v1"],"summary":"Create Chat Task","description":"Create a new SDK-driven task and kick off its first turn.\n\nSingle endpoint does three things atomically from the caller's\nperspective:\n\n 1. Verifies the body's ``agent_id`` matches the agent bound to\n the presented API key. Mismatch -> 404 ``agent_not_found``\n (404 not 403, so the existence of unrelated agents isn't\n leaked via error code).\n 2. Persists a new :class:`Task` row owned by the agent's user,\n with ``source='sdk'`` and ``input`` set to the user message.\n Also persists the first user message to\n ``task_chat_messages`` so the existing background execution\n path can consume it without special-casing this entry point.\n 3. Schedules background execution via\n ``start_task_in_background`` (which uses the same coroutine\n the WebSocket handler does). Returns 202 immediately --\n callers poll ``GET /v1/chat/tasks/{task_id}`` to observe the\n eventual ``completed`` / ``failed`` status.\n\nArgs:\n request: Validated :class:`CreateTaskRequest`. ``message.content``\n is guaranteed non-empty by Pydantic; ``agent_id`` is the\n target agent the SDK caller wants to invoke.\n authed: ``(Agent, AgentApiKey)`` tuple resolved by the auth\n dependency. The agent here is the *key-bound* agent, the\n single source of truth for what this caller may touch.\n db: SQLAlchemy session.\n\nReturns:\n :class:`CreateTaskResponse` with the new ``task_id``,\n ``agent_id``, ``status='running'`` (the atomic claim inside\n the handler flips the row from PENDING to RUNNING before the\n response is sent), and ``created_at`` for the caller to\n start polling from.\n\nRaises:\n V1ApiError 401: missing/invalid/revoked key (raised inside\n ``get_agent_from_api_key``; envelope is uniform with\n other auth failures).\n V1ApiError 404: ``request.agent_id != authed_agent.id``.\n 500 (V1 envelope): any unexpected exception -- the global\n handler in ``web/app.py`` translates to\n ``{\"error\": {\"code\": \"internal_error\", ...}}`` and the raw\n exception message stays out of the response.","operationId":"create_chat_task_v1_chat_tasks_post","requestBody":"c05b3a0f-8ff9-475c-9562-3e7186878c8d","responses":{"202":"2a52b041-5147-468e-a24a-d3311061c929","422":"95d9c2ff-488b-4833-b4fa-0f8b0ac67273"},"security":["d955e26d-0a0f-4d33-ba21-2b0889ad96ef"],"method":"post","type":"path","servers":[],"path":"/v1/chat/tasks","baseUrlOptions":[],"title":"Create Chat Task","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"integer","title":"Agent Id","description":"Target agent's primary key. Must match the agent the presented API key is bound to.","isRequired":true,"uniqueKey":"agent_id","typeLabel":"integer"},"message":{"properties":{"content":{"type":"string","minLength":1,"title":"Content","description":"The user's message text. Must be non-empty.","isRequired":true,"uniqueKey":"message.content","typeLabel":"string"},"role":{"type":"string","const":"user","title":"Role","description":"Currently must be 'user'. Reserved as a field for future expansion (system / function roles) without breaking the wire shape.","default":"user","uniqueKey":"message.role","typeLabel":"string"}},"type":"object","required":["content"],"title":"MessageBody","description":"First user message of the task.","isRequired":true,"uniqueKey":"message","typeLabel":"MessageBody · object"},"metadata":{"oneOf":[{"type":"object","title":"Metadata","description":"Free-form correlation data the SDK caller can pass through (trace_id, request_id, etc). Not interpreted server-side.","additionalProperties":true,"uniqueKey":"metadata.oneOf.0","typeLabel":"Metadata · object"},{"type":"null","title":"Metadata","description":"Free-form correlation data the SDK caller can pass through (trace_id, request_id, etc). Not interpreted server-side.","uniqueKey":"metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"metadata","typeLabel":"Metadata · object | null"},"dispatch_class":{"oneOf":[{"type":"string","title":"Dispatch Class","description":"Dispatch class to request for this task: 'interactive' or 'batch'. Omit it or send null to let the server decide. Whether the deployment honors the request is its own setting; the response's 'dispatch_class' shows the class the start command was given.","enum":["interactive","batch"],"uniqueKey":"dispatch_class.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","title":"Dispatch Class","description":"Dispatch class to request for this task: 'interactive' or 'batch'. Omit it or send null to let the server decide. Whether the deployment honors the request is its own setting; the response's 'dispatch_class' shows the class the start command was given.","uniqueKey":"dispatch_class.oneOf.1","typeLabel":"null"}],"uniqueKey":"dispatch_class","typeLabel":"enum\u003cstring> | null"},"priority":{"oneOf":[{"type":"integer","title":"Priority","description":"Priority of this task's commands, an integer from -10 to 10; higher goes first. Omit it or send null for 0. It takes effect only where the deployment dispatches fairly across accounts, and only orders commands of the same account and the same dispatch class. Messages appended to the task and manual resumes inherit it.","maximum":10,"minimum":-10,"uniqueKey":"priority.oneOf.0","typeLabel":"integer"},{"type":"null","title":"Priority","description":"Priority of this task's commands, an integer from -10 to 10; higher goes first. Omit it or send null for 0. It takes effect only where the deployment dispatches fairly across accounts, and only orders commands of the same account and the same dispatch class. Messages appended to the task and manual resumes inherit it.","uniqueKey":"priority.oneOf.1","typeLabel":"null"}],"uniqueKey":"priority","typeLabel":"integer | null"}},"type":"object","required":["agent_id","message"],"title":"CreateTaskRequest","description":"Body for ``POST /v1/chat/tasks``.\n\n``agent_id`` is required and must match the agent bound to the\npresented API key; the server enforces ``body.agent_id ==\nauthed.agent.id`` and returns 404 ``agent_not_found`` on mismatch.","uniqueKey":"","typeLabel":"CreateTaskRequest · object"},"examples":{"Example":{"title":"Example","value":{"agent_id":123,"message":{"content":"\u003cstring>","role":"user"},"metadata":{},"priority":0}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"2a52b041-5147-468e-a24a-d3311061c929":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"task_id":{"type":"integer","title":"Task Id","description":"Newly created task primary key.","isRequired":true,"uniqueKey":"task_id","typeLabel":"integer"},"agent_id":{"type":"integer","title":"Agent Id","description":"Agent the task is bound to.","isRequired":true,"uniqueKey":"agent_id","typeLabel":"integer"},"status":{"type":"string","title":"Status","description":"Initial status, 'running' in the 202 response (the atomic claim inside POST commits the status flip before the response is sent). Use GET /v1/chat/tasks/{task_id} to observe later transitions.","isRequired":true,"uniqueKey":"status","typeLabel":"string"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"UTC creation timestamp.","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"dispatch_class":{"oneOf":[{"type":"string","title":"Dispatch Class","description":"Dispatch class the start command was given, which is the requested class only when the deployment accepted it. Null when the server runs the task in this process rather than through the dispatch queue. Later commands on the task are not reported here.","enum":["interactive","batch"],"uniqueKey":"dispatch_class.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","title":"Dispatch Class","description":"Dispatch class the start command was given, which is the requested class only when the deployment accepted it. Null when the server runs the task in this process rather than through the dispatch queue. Later commands on the task are not reported here.","uniqueKey":"dispatch_class.oneOf.1","typeLabel":"null"}],"uniqueKey":"dispatch_class","typeLabel":"enum\u003cstring> | null"}},"type":"object","required":["task_id","agent_id","status","created_at"],"title":"CreateTaskResponse","description":"``POST /v1/chat/tasks`` -> 202 Accepted response.\n\nThe task has been persisted, claimed as RUNNING in the same\ntransaction, and queued for background execution; callers poll\n``GET /v1/chat/tasks/{task_id}`` to observe the transition\nrunning -> completed/failed.","uniqueKey":"","typeLabel":"CreateTaskResponse · object"},"examples":{"Example":{"title":"Example","value":{"task_id":123,"agent_id":123,"status":"\u003cstring>","created_at":"2023-11-07T05:31:56Z","dispatch_class":"interactive"}}},"exampleType":"generated"}},"exampleType":"generated"},"95d9c2ff-488b-4833-b4fa-0f8b0ac67273":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>"}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"d955e26d-0a0f-4d33-ba21-2b0889ad96ef":{"HTTPBearer":{"type":"http","scheme":"bearer","scopes":[],"schemeName":"HTTPBearer"}}},"servers":{},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","scopes":[],"schemeName":"HTTPBearer"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"HTTPBearer","name":"Authorization"}],"title":"HTTPBearer"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"xorbitsinc","siteName":"Xagent","title":"Create Chat Task - Xagent","navMaps":{"firstHrefInVersion":{"Latest":{"href":"/api-reference/sdk-v1/create-chat-task","matchLevel":0}},"firstHrefInLanguage":{"en":{"href":"/api-reference/sdk-v1/create-chat-task","matchLevel":0}}},"lastModified":"2026-06-13T11:27:58.183Z","originalFileLocation":"api-reference/sdk-v1/create-chat-task.mdx","locale":"en"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a new SDK-driven task and kick off its first turn. Single endpoint does three things atomically from the caller\u0026#x27;s perspective: 1. Verifies the body\u0026#x27;s agent_id matches the agent bound to the presented API key. Mismatch -\u0026gt; 404 agent_not_found (404 not 403, so the existence of unrelated agents isn\u0026#x27;t leaked via error code). 2. Persists a new :class:Task row owned by the agent\u0026#x27;s user, with source=\u0026#x27;sdk\u0026#x27; and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point. 3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status. Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session. Returns: :class:CreateTaskResponse with the new task_id, agent_id, status=\u0026#x27;running\u0026#x27; (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from. Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {\u0026quot;error\u0026quot;: {\u0026quot;code\u0026quot;: \u0026quot;internal_error\u0026quot;, ...}} and the raw exception message stays out of the response.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Xagent\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Chat Task - Xagent\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a new SDK-driven task and kick off its first turn. Single endpoint does three things atomically from the caller\u0026#x27;s perspective: 1. Verifies the body\u0026#x27;s agent_id matches the agent bound to the presented API key. Mismatch -\u0026gt; 404 agent_not_found (404 not 403, so the existence of unrelated agents isn\u0026#x27;t leaked via error code). 2. Persists a new :class:Task row owned by the agent\u0026#x27;s user, with source=\u0026#x27;sdk\u0026#x27; and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point. 3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status. Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session. Returns: :class:CreateTaskResponse with the new task_id, agent_id, status=\u0026#x27;running\u0026#x27; (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from. Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {\u0026quot;error\u0026quot;: {\u0026quot;code\u0026quot;: \u0026quot;internal_error\u0026quot;, ...}} and the raw exception message stays out of the response.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Xagent\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://xorbitsinc.mintlify.app/_mintlify/api/og/v2?division=SDK+v1\u0026amp;title=Create+Chat+Task\u0026amp;description=Create+a+new+SDK-driven+task+and+kick+off+its+first+turn.%0A%0ASingle+endpoint+does+three+things+atomically+from+the+caller%27s%0Aperspective%3A%0A%0A++1.+Verifies+the+body%27s\u0026amp;theme=7a21b44f6d5c94939f15c745\u0026amp;signature=bb28001eac8edc12abe959ce6513dc995c02a9a59704e64a4257d155dda47da0\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create Chat Task - Xagent\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a new SDK-driven task and kick off its first turn. Single endpoint does three things atomically from the caller\u0026#x27;s perspective: 1. Verifies the body\u0026#x27;s agent_id matches the agent bound to the presented API key. Mismatch -\u0026gt; 404 agent_not_found (404 not 403, so the existence of unrelated agents isn\u0026#x27;t leaked via error code). 2. Persists a new :class:Task row owned by the agent\u0026#x27;s user, with source=\u0026#x27;sdk\u0026#x27; and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point. 3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status. Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session. Returns: :class:CreateTaskResponse with the new task_id, agent_id, status=\u0026#x27;running\u0026#x27; (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from. Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {\u0026quot;error\u0026quot;: {\u0026quot;code\u0026quot;: \u0026quot;internal_error\u0026quot;, ...}} and the raw exception message stays out of the response.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://xorbitsinc.mintlify.app/_mintlify/api/og/v2?division=SDK+v1\u0026amp;title=Create+Chat+Task\u0026amp;description=Create+a+new+SDK-driven+task+and+kick+off+its+first+turn.%0A%0ASingle+endpoint+does+three+things+atomically+from+the+caller%27s%0Aperspective%3A%0A%0A++1.+Verifies+the+body%27s\u0026amp;theme=7a21b44f6d5c94939f15c745\u0026amp;signature=bb28001eac8edc12abe959ce6513dc995c02a9a59704e64a4257d155dda47da0\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/xorbitsinc/PSDisYJ6JNoefUDf/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Xagent\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#6A0CF5\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/sdk-v1/create-chat-task.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.xagent.co/#organization\",\"name\":\"Xagent\",\"url\":\"https://docs.xagent.co\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/xorbitsinc/iidWB4pLRl1L1AC4/images/logo/xagent-logo-light.png?fit=max\u0026auto=format\u0026n=iidWB4pLRl1L1AC4\u0026q=85\u0026s=d45e51a54fae46740727ec694e10dbda\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.xagent.co#website\",\"name\":\"Xagent\",\"url\":\"https://docs.xagent.co\",\"publisher\":{\"@id\":\"https://docs.xagent.co/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task#webpage\",\"url\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task\",\"name\":\"Create Chat Task\",\"description\":\"Create a new SDK-driven task and kick off its first turn. Single endpoint does three things atomically from the caller's perspective: 1. Verifies the body's agent_id matches the agent bound to the presented API key. Mismatch -> 404 agent_not_found (404 not 403, so the existence of unrelated agents isn't leaked via error code). 2. Persists a new :class:Task row owned by the agent's user, with source='sdk' and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point. 3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status. Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session. Returns: :class:CreateTaskResponse with the new task_id, agent_id, status='running' (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from. Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {\\\"error\\\": {\\\"code\\\": \\\"internal_error\\\", ...}} and the raw exception message stays out of the response.\",\"dateModified\":\"2026-06-13T11:27:58.183Z\",\"isPartOf\":{\"@id\":\"https://docs.xagent.co#website\"},\"breadcrumb\":{\"@id\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"SDK v1\",\"item\":\"https://docs.xagent.co/api-reference/sdk-v1/get-me\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Chat Task\",\"item\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task#apireference\",\"headline\":\"Create Chat Task\",\"name\":\"Create Chat Task\",\"description\":\"Create a new SDK-driven task and kick off its first turn. Single endpoint does three things atomically from the caller's perspective: 1. Verifies the body's agent_id matches the agent bound to the presented API key. Mismatch -> 404 agent_not_found (404 not 403, so the existence of unrelated agents isn't leaked via error code). 2. Persists a new :class:Task row owned by the agent's user, with source='sdk' and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point. 3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status. Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session. Returns: :class:CreateTaskResponse with the new task_id, agent_id, status='running' (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from. Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {\\\"error\\\": {\\\"code\\\": \\\"internal_error\\\", ...}} and the raw exception message stays out of the response.\",\"url\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task\",\"mainEntityOfPage\":{\"@id\":\"https://docs.xagent.co/api-reference/sdk-v1/create-chat-task#webpage\"},\"dateModified\":\"2026-06-13T11:27:58.183Z\",\"publisher\":{\"@id\":\"https://docs.xagent.co/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.xagent.co#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Xagent\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Xagent","nav":{"global":null,"versions":[{"version":"Latest","languages":[{"language":"en","default":true,"dropdowns":[{"dropdown":"Use Xagent","icon":"sparkles","pages":[{"group":" ","pages":[{"group":"Overview","expanded":true,"pages":[{"title":"What is Xagent","mode":"wide","icon":"rocket","href":""},{"title":"Quick Start","icon":"zap","href":"/quickstart"},{"title":"Installation","icon":"download","href":"/installation"}]},{"group":"Tasks","expanded":false,"pages":[{"title":"Tasks Overview","icon":"play","href":"/tasks/overview"},{"title":"Task Execution","icon":"play-circle","href":"/tasks/execution"}]},{"group":"Agents","expanded":false,"pages":[{"title":"Agents Overview","icon":"robot","href":"/agents/overview"},{"title":"Building Agents","icon":"wrench","href":"/agents/building"},{"title":"Sharing Agents","icon":"share","href":"/agents/sharing"},{"title":"Embedding Agents as Widgets","icon":"layout-panel-top","href":"/agents/widget-embed"}]},{"group":"Workforces","expanded":false,"pages":[{"title":"Workforces Overview","icon":"users","href":"/workforces/overview"},{"title":"Building Workforces","icon":"workflow","href":"/workforces/building"}]},{"group":"Templates","expanded":false,"pages":[{"title":"Templates","icon":"copy","href":"/templates/overview"},{"title":"Creating Templates","icon":"plus","href":"/templates/creating"}]},{"group":"Knowledge Base","expanded":false,"pages":[{"title":"Knowledge Base Overview","icon":"database","href":"/knowledge/overview"},{"title":"Uploading Knowledge","icon":"upload","href":"/knowledge/uploading"},{"title":"Knowledge Retrieval","icon":"search","href":"/knowledge/retrieval"}]},{"group":"Models","expanded":false,"pages":[{"title":"Models Overview","icon":"box","href":"/models/overview"},{"title":"LLM Models","icon":"brain","href":"/models/llm"},{"title":"Embedding Models","icon":"database","href":"/models/embedding"},{"title":"Image Generation Models","icon":"image","href":"/models/image-generation"}]},{"group":"Tools","expanded":false,"pages":[{"title":"Tools Overview","icon":"wrench","href":"/tools/overview"},{"title":"Built-in Tools","icon":"box","href":"/tools/built-in"},{"title":"Custom Tools via MCP","icon":"code","href":"/tools/custom"}]},{"group":"Memory","expanded":false,"pages":[{"title":"Memory Overview","icon":"brain","href":"/memory/overview"},{"title":"Memory Types","icon":"database","href":"/memory/types"},{"title":"Memory Configuration","icon":"sliders","href":"/memory/configuration"}]},{"group":"Files","expanded":false,"pages":[{"title":"Files Overview","icon":"file","href":"/files/overview"},{"title":"File Upload","icon":"upload","href":"/files/upload"},{"title":"File Management","icon":"folder","href":"/files/management"}]},{"title":"Release Notes","href":"/release-notes"}]}]},{"dropdown":"Release Notes","icon":"clock-rotate-left","pages":[{"title":"Release Notes","href":"/release-notes"}]},{"dropdown":"Platform","icon":"server","pages":[{"title":"MCP Providers Configuration","href":"/tools/mcp-providers"},{"title":"SDK \u0026 API Keys","icon":"key-round","href":"/guides/sdk"},{"group":"Channels","expanded":false,"pages":[{"title":"Channels Overview","icon":"message-square","href":"/channels/overview"},{"title":"Telegram","icon":"send","href":"/channels/telegram"}]},{"group":"Deployment","expanded":false,"pages":[{"title":"Configuration","href":"/deployment/configuration"},{"title":"Self-Hosted Deployment","href":"/deployment/self-hosted"}]}]},{"dropdown":"API Reference","icon":"code","pages":[{"title":"API Reference","href":"/api-reference/introduction"},{"group":"Authentication","expanded":false,"pages":[{"openapi":"get /api/auth/setup-status","title":"Setup Status","href":"/api-reference/authentication/setup-status"},{"openapi":"post /api/auth/setup-admin","title":"Setup Admin","href":"/api-reference/authentication/setup-admin"},{"openapi":"get /api/auth/register-switch","title":"Get Register Switch","href":"/api-reference/authentication/get-register-switch"},{"openapi":"patch /api/auth/register-switch","title":"Update Register Switch","href":"/api-reference/authentication/update-register-switch"},{"openapi":"post /api/auth/login","title":"Login","href":"/api-reference/authentication/login"},{"openapi":"post /api/auth/register","title":"Register","href":"/api-reference/authentication/register"},{"openapi":"post /api/auth/forgot-password","title":"Forgot Password","href":"/api-reference/authentication/forgot-password"},{"openapi":"post /api/auth/reset-password","title":"Reset Password","href":"/api-reference/authentication/reset-password"},{"openapi":"get /api/auth/me","title":"Get Current User Profile","href":"/api-reference/authentication/get-current-user-profile"},{"openapi":"patch /api/auth/email","title":"Update Current User Email","href":"/api-reference/authentication/update-current-user-email"},{"openapi":"post /api/auth/refresh","title":"Refresh Token","href":"/api-reference/authentication/refresh-token"},{"openapi":"post /api/auth/change-password","title":"Change Password","href":"/api-reference/authentication/change-password"},{"openapi":"get /api/auth/check","title":"Check Auth","href":"/api-reference/authentication/check-auth"},{"openapi":"get /api/auth/verify","title":"Verify Current Token","href":"/api-reference/authentication/verify-current-token"},{"openapi":"get /api/auth/{provider}/login","title":"Oauth Login","href":"/api-reference/authentication/oauth-login"},{"openapi":"get /api/auth/{provider}/callback","title":"Oauth Callback","href":"/api-reference/authentication/oauth-callback"},{"openapi":"get /api/auth/oidc/google/status","title":"Google Oidc Status","href":"/api-reference/authentication/google-oidc-status"},{"openapi":"get /api/auth/oidc/google/login","title":"Google Oidc Login","href":"/api-reference/authentication/google-oidc-login"},{"openapi":"get /api/auth/oidc/google/callback","title":"Google Oidc Callback","href":"/api-reference/authentication/google-oidc-callback"},{"openapi":"post /api/auth/oidc/google/exchange","title":"Google Oidc Exchange","href":"/api-reference/authentication/google-oidc-exchange"}]},{"group":"Agents","expanded":false,"pages":[{"openapi":"post /api/agents/optimize-instructions","title":"Optimize Instructions","href":"/api-reference/agents/optimize-instructions"},{"openapi":"get /api/agents","title":"List Agents","href":"/api-reference/agents/list-agents"},{"openapi":"post /api/agents","title":"Create Agent","href":"/api-reference/agents/create-agent"},{"openapi":"get /api/agents/{agent_id}","title":"Get Agent","href":"/api-reference/agents/get-agent"},{"openapi":"put /api/agents/{agent_id}","title":"Update Agent","href":"/api-reference/agents/update-agent"},{"openapi":"delete /api/agents/{agent_id}","title":"Delete Agent","href":"/api-reference/agents/delete-agent"},{"openapi":"post /api/agents/{agent_id}/publish","title":"Publish Agent","href":"/api-reference/agents/publish-agent"},{"openapi":"post /api/agents/{agent_id}/unpublish","title":"Unpublish Agent","href":"/api-reference/agents/unpublish-agent"},{"openapi":"get /api/agents/{agent_id}/share-link","title":"Get Agent Share Link","href":"/api-reference/agents/get-agent-share-link"},{"openapi":"post /api/agents/{agent_id}/share-link","title":"Enable Agent Share Link","href":"/api-reference/agents/enable-agent-share-link"},{"openapi":"delete /api/agents/{agent_id}/share-link","title":"Disable Agent Share Link","href":"/api-reference/agents/disable-agent-share-link"},{"openapi":"post /api/agents/{agent_id}/share-link/rotate","title":"Rotate Agent Share Link","href":"/api-reference/agents/rotate-agent-share-link"},{"openapi":"post /api/agents/preview","title":"Preview Agent","href":"/api-reference/agents/preview-agent"},{"openapi":"post /api/agents/{agent_id}/logo","title":"Upload Agent Logo","href":"/api-reference/agents/upload-agent-logo"},{"openapi":"get /api/agents/{agent_id}/api-key","title":"Get Agent Api Key","href":"/api-reference/agents/get-agent-api-key"},{"openapi":"post /api/agents/{agent_id}/api-key","title":"Generate Agent Api Key","href":"/api-reference/agents/generate-agent-api-key"},{"openapi":"delete /api/agents/{agent_id}/api-key","title":"Revoke Agent Api Key","href":"/api-reference/agents/revoke-agent-api-key"}]},{"group":"SDK v1","expanded":false,"pages":[{"openapi":"get /v1/me","title":"Get Me","href":"/api-reference/sdk-v1/get-me"},{"openapi":"get /v1/templates","title":"List Templates","href":"/api-reference/sdk-v1/list-templates"},{"openapi":"get /v1/templates/{template_id}","title":"Get Template","href":"/api-reference/sdk-v1/get-template"},{"openapi":"get /v1/agents","title":"List Agents","href":"/api-reference/sdk-v1/list-agents"},{"openapi":"post /v1/agents","title":"Create Agent","href":"/api-reference/sdk-v1/create-agent"},{"openapi":"post /v1/agents/from-template","title":"Create Agent From Template","href":"/api-reference/sdk-v1/create-agent-from-template"},{"openapi":"post /v1/agents/{agent_id}/api-key","title":"Rotate Agent Runtime Key","description":null,"href":"/api-reference/sdk-v1/rotate-agent-runtime-key"},{"openapi":"post /v1/chat/tasks","title":"Create Chat Task","href":"/api-reference/sdk-v1/create-chat-task"},{"openapi":"post /v1/chat/tasks/{task_id}/messages","title":"Append Message To Task","description":"Append the next user message to an existing task and kick off its next turn.\n\nPhase 1 multi-turn model is task-centric: subsequent user inputs\nextend the same ``task_id`` rather than creating a new task or a\nnew ``conversation_id``. This endpoint:\n\n 1. Validates the path ``task_id`` exists and belongs to the\n key-bound agent (404 ``task_not_found`` otherwise).\n 2. Validates ``body.agent_id`` matches the key-bound agent\n (404 ``agent_not_found`` otherwise).\n 3. Rejects the call with 409 ``task_busy`` if the task is\n currently ``RUNNING`` -- the SDK client should poll\n ``GET /v1/chat/tasks/{id}`` until status leaves RUNNING and\n retry.\n 4. Otherwise persists the new user message to\n ``task_chat_messages``, updates ``task.input`` to record\n this turn's input, and kicks off the next background turn\n via the same helper POST uses.\n\nArgs:\n task_id: Path parameter; the target task's primary key.\n request: Validated :class:`AppendMessageRequest`. ``message.content``\n is guaranteed non-empty by Pydantic.\n authed: ``(Agent, AgentApiKey)`` from the auth dependency.\n db: SQLAlchemy session.\n\nReturns:\n :class:`AppendMessageResponse` with the task identity and an\n ``accepted_at`` timestamp.\n\nRaises:\n V1ApiError 401: missing / invalid / revoked key.\n V1ApiError 404: task not found OR not owned by the agent OR\n body.agent_id doesn't match the bound agent.\n V1ApiError 409: ``task_busy`` -- task currently RUNNING.\n 500: any other unexpected error (V1 envelope via global handler).","href":"/api-reference/sdk-v1/append-message-to-task"},{"openapi":"get /v1/chat/tasks/{task_id}","title":"Get Chat Task","href":"/api-reference/sdk-v1/get-chat-task"},{"openapi":"get /v1/chat/tasks/{task_id}/steps","title":"Get Chat Task Steps","href":"/api-reference/sdk-v1/get-chat-task-steps"}]},{"group":"Web App Tasks","expanded":false,"pages":[{"openapi":"post /api/chat/task/create","title":"Create Task","href":"/api-reference/chat/create-task"},{"openapi":"get /api/chat/tasks","title":"Get Tasks","href":"/api-reference/chat/get-tasks"},{"openapi":"get /api/chat/task/{task_id}","title":"Get Task","href":"/api-reference/chat/get-task"},{"openapi":"put /api/chat/task/{task_id}","title":"Update Task","href":"/api-reference/chat/update-task"},{"openapi":"delete /api/chat/task/{task_id}","title":"Delete Task","href":"/api-reference/chat/delete-task"},{"openapi":"get /api/chat/task/{task_id}/status","title":"Get Task Status","href":"/api-reference/chat/get-task-status"},{"openapi":"get /api/chat/workspace/{task_id}/output","title":"Get Task Output Files","href":"/api-reference/chat/get-task-output-files"},{"openapi":"get /api/chat/workspace/{task_id}/files","title":"Get Task Workspace Files","href":"/api-reference/chat/get-task-workspace-files"}]},{"group":"Files","expanded":false,"pages":[{"openapi":"post /api/files/upload","title":"Upload File","href":"/api-reference/files/upload-file"},{"openapi":"get /api/files/list","title":"List Files","href":"/api-reference/files/list-files"},{"openapi":"get /api/files/tasks","title":"List File Tasks","href":"/api-reference/files/list-file-tasks"},{"openapi":"get /api/files/task/{task_id}","title":"List Task Files","href":"/api-reference/files/list-task-files"},{"openapi":"get /api/files/download/{file_id}","title":"Download File","href":"/api-reference/files/download-file"},{"openapi":"get /api/files/preview/{file_id}","title":"Preview File","href":"/api-reference/files/preview-file"},{"openapi":"get /api/files/preview-pdf/{file_id}","title":"Preview Pptx As Pdf","href":"/api-reference/files/preview-pptx-as-pdf"},{"openapi":"get /api/files/public/download/{file_id}","title":"Public Download File","href":"/api-reference/files/public-download-file"},{"openapi":"get /api/files/public/preview/{file_id}","title":"Public Preview File","href":"/api-reference/files/public-preview-file"},{"openapi":"delete /api/files/{file_id}","title":"Delete File","href":"/api-reference/files/delete-file"}]},{"group":"Knowledge Base","expanded":false,"pages":[{"openapi":"post /api/kb/ingest","title":"Ingest","href":"/api-reference/kb/ingest"},{"openapi":"post /api/kb/ingest/jobs","title":"Create Ingest Job","href":"/api-reference/kb/create-ingest-job"},{"openapi":"post /api/kb/ingest-cloud","title":"Ingest Cloud","href":"/api-reference/kb/ingest-cloud"},{"openapi":"post /api/kb/search","title":"Search","href":"/api-reference/kb/search"},{"openapi":"post /api/kb/ingest-web","title":"Ingest Web","href":"/api-reference/kb/ingest-web"},{"openapi":"post /api/kb/ingest-web/jobs","title":"Create Ingest Web Job","href":"/api-reference/kb/create-ingest-web-job"},{"openapi":"post /api/kb/collections/{collection}/config","title":"Save Collection Config","href":"/api-reference/kb/save-collection-config"},{"openapi":"patch /api/kb/collections/{collection}/rerank-model","title":"Set Collection Rerank Model","href":"/api-reference/kb/set-collection-rerank-model"},{"openapi":"get /api/kb/collections","title":"List Collections Api","href":"/api-reference/kb/list-collections-api"},{"openapi":"post /api/kb/collections/batch-delete","title":"Batch Delete Collections Api","href":"/api-reference/kb/batch-delete-collections-api"},{"openapi":"post /api/kb/collections/{collection_name}/documents/check","title":"Check Documents Exist Api","href":"/api-reference/kb/check-documents-exist-api"},{"openapi":"put /api/kb/collections/{collection_name}","title":"Rename Collection Api","href":"/api-reference/kb/rename-collection-api"},{"openapi":"delete /api/kb/collections/{collection_name}","title":"Delete Collection Api","href":"/api-reference/kb/delete-collection-api"},{"openapi":"delete /api/kb/collections/{collection_name}/documents/{filename}","title":"Delete Document Api","href":"/api-reference/kb/delete-document-api"},{"openapi":"get /api/kb/collections/{collection_name}/parses/{doc_id}/parse_result","title":"Get Parse Result Api","href":"/api-reference/kb/get-parse-result-api"}]},{"group":"Memory","expanded":false,"pages":[{"openapi":"get /api/memory/{memory_id}","title":"Get Memory","href":"/api-reference/memory/get-memory"},{"openapi":"get /api/memory/list","title":"List Memories","href":"/api-reference/memory/list-memories"},{"openapi":"post /api/memory","title":"Create Memory","href":"/api-reference/memory/create-memory"},{"openapi":"put /api/memory/{memory_id}","title":"Update Memory","href":"/api-reference/memory/update-memory"},{"openapi":"delete /api/memory/{memory_id}","title":"Delete Memory","href":"/api-reference/memory/delete-memory"},{"openapi":"get /api/memory/stats","title":"Get Memory Stats","href":"/api-reference/memory/get-memory-stats"},{"openapi":"get /api/memory/store-info","title":"Get Store Info","href":"/api-reference/memory/get-store-info"}]},{"group":"Models","expanded":false,"pages":[{"openapi":"post /api/models/register","title":"Create Model","href":"/api-reference/models/create-model"},{"openapi":"get /api/models/","title":"List Models","href":"/api-reference/models/list-models"},{"openapi":"post /api/models/","title":"Create Model","href":"/api-reference/models/create-model-1"},{"openapi":"get /api/models/user-default","title":"Get User Default Models","href":"/api-reference/models/get-user-default-models"},{"openapi":"post /api/models/user-default","title":"Set User Default Model","href":"/api-reference/models/set-user-default-model"},{"openapi":"get /api/models/by-id/{model_id}","title":"Get Model By Path","href":"/api-reference/models/get-model-by-path"},{"openapi":"put /api/models/by-id/{model_id}","title":"Update Model By Path","href":"/api-reference/models/update-model-by-path"},{"openapi":"delete /api/models/by-id/{model_id}","title":"Delete Model By Path","href":"/api-reference/models/delete-model-by-path"},{"openapi":"get /api/models/{model_id}","title":"Get Model","href":"/api-reference/models/get-model"},{"openapi":"put /api/models/{model_id}","title":"Update Model","href":"/api-reference/models/update-model"},{"openapi":"delete /api/models/{model_id}","title":"Delete Model","href":"/api-reference/models/delete-model"},{"openapi":"post /api/models/test-connection","title":"Test Model Connection","href":"/api-reference/models/test-model-connection"},{"openapi":"post /api/models/test","title":"Test Models","href":"/api-reference/models/test-models"},{"openapi":"get /api/models/types/available","title":"Get Available Model Providers","href":"/api-reference/models/get-available-model-providers"},{"openapi":"get /api/models/categories","title":"List Model Categories","href":"/api-reference/models/list-model-categories"},{"openapi":"get /api/models/summary","title":"Get Models Summary","href":"/api-reference/models/get-models-summary"},{"openapi":"get /api/models/default/{model_provider}","title":"Get Default Model","href":"/api-reference/models/get-default-model"},{"openapi":"get /api/models/default/general","title":"Get General Default Model","href":"/api-reference/models/get-general-default-model"},{"openapi":"get /api/models/default/small-fast","title":"Get Small Fast Default Model","href":"/api-reference/models/get-small-fast-default-model"},{"openapi":"get /api/models/default/visual","title":"Get Visual Default Model","href":"/api-reference/models/get-visual-default-model"},{"openapi":"get /api/models/default/compact","title":"Get Compact Default Model","href":"/api-reference/models/get-compact-default-model"},{"openapi":"get /api/models/default/embedding","title":"Get Embedding Default Model","href":"/api-reference/models/get-embedding-default-model"},{"openapi":"get /api/models/providers","title":"List Model Providers","href":"/api-reference/models/list-model-providers"},{"openapi":"get /api/models/abilities","title":"List Model Abilities","href":"/api-reference/models/list-model-abilities"},{"openapi":"get /api/models/user-default/{config_type}","title":"Get User Default Model","href":"/api-reference/models/get-user-default-model"},{"openapi":"delete /api/models/user-default/{config_type}","title":"Delete User Default Model","href":"/api-reference/models/delete-user-default-model"},{"openapi":"get /api/models/public/list","title":"List Public Models","href":"/api-reference/models/list-public-models"},{"openapi":"get /api/models/public/categories","title":"List Public Categories","href":"/api-reference/models/list-public-categories"},{"openapi":"get /api/models/public/providers","title":"List Public Providers","href":"/api-reference/models/list-public-providers"},{"openapi":"get /api/models/public/summary","title":"Get Public Summary","href":"/api-reference/models/get-public-summary"},{"openapi":"get /api/models/providers/supported","title":"List Supported Providers","href":"/api-reference/models/list-supported-providers"},{"openapi":"post /api/models/providers/{provider}/models","title":"Fetch Provider Models","href":"/api-reference/models/fetch-provider-models"},{"openapi":"post /api/models/providers/fetch","title":"Fetch Multiple Providers Models","href":"/api-reference/models/fetch-multiple-providers-models"},{"openapi":"get /api/models/xinference/tts-models","title":"List Xinference Tts Models","href":"/api-reference/models/list-xinference-tts-models"}]},{"group":"Tools","expanded":false,"pages":[{"openapi":"get /api/tools/available","title":"Get Available Tools","href":"/api-reference/tools/get-available-tools"},{"openapi":"get /api/tools/configurable","title":"Get Configurable Tools","href":"/api-reference/tools/get-configurable-tools"},{"openapi":"get /api/tools/sql-connections","title":"Get Sql Connections","href":"/api-reference/tools/get-sql-connections"},{"openapi":"put /api/tools/sql-connections/{name}","title":"Upsert Sql Connection","href":"/api-reference/tools/upsert-sql-connection"},{"openapi":"delete /api/tools/sql-connections/{name}","title":"Remove Sql Connection","href":"/api-reference/tools/remove-sql-connection"},{"openapi":"put /api/tools/{tool_name}/enabled","title":"Update Tool Enabled","href":"/api-reference/tools/update-tool-enabled"},{"openapi":"get /api/tools/{tool_name}/credentials","title":"Get Tool Credentials","href":"/api-reference/tools/get-tool-credentials"},{"openapi":"put /api/tools/{tool_name}/credentials","title":"Update Tool Credentials","href":"/api-reference/tools/update-tool-credentials"},{"openapi":"delete /api/tools/{tool_name}/credentials/{field_name}","title":"Delete Tool Credential","href":"/api-reference/tools/delete-tool-credential"},{"openapi":"get /api/tools/usage","title":"Get Tool Usage","href":"/api-reference/tools/get-tool-usage"}]},{"group":"Cloud storage","expanded":false,"pages":[{"openapi":"get /api/cloud/accounts","title":"List Connected Accounts","href":"/api-reference/cloud-storage/list-connected-accounts"},{"openapi":"delete /api/cloud/accounts/{account_id}","title":"Delete Connected Account","href":"/api-reference/cloud-storage/delete-connected-account"},{"openapi":"get /api/cloud/google-drive/drives","title":"List Google Drives","href":"/api-reference/cloud-storage/list-google-drives"},{"openapi":"get /api/cloud/google-drive/files","title":"List Google Drive Files","href":"/api-reference/cloud-storage/list-google-drive-files"}]},{"group":"Channels","expanded":false,"pages":[{"openapi":"get /api/channels","title":"Get User Channels","href":"/api-reference/channels/get-user-channels"},{"openapi":"post /api/channels","title":"Create User Channel","href":"/api-reference/channels/create-user-channel"},{"openapi":"put /api/channels/{channel_id}","title":"Update User Channel","href":"/api-reference/channels/update-user-channel"},{"openapi":"delete /api/channels/{channel_id}","title":"Delete User Channel","href":"/api-reference/channels/delete-user-channel"}]},{"group":"Personal API keys","expanded":false,"pages":[{"openapi":"get /api/me/personal-keys","title":"List Personal Keys","href":"/api-reference/me/list-personal-keys"},{"openapi":"post /api/me/personal-keys","title":"Create Personal Key","href":"/api-reference/me/create-personal-key"},{"openapi":"delete /api/me/personal-keys/{key_id}","title":"Revoke Personal Key","href":"/api-reference/me/revoke-personal-key"}]},{"group":"Skills","expanded":false,"pages":[{"openapi":"get /api/skills/","title":"List Skills","href":"/api-reference/skills/list-skills"},{"openapi":"get /api/skills/{skill_name}","title":"Get Skill","href":"/api-reference/skills/get-skill"},{"openapi":"post /api/skills/recall","title":"Recall Skill","href":"/api-reference/skills/recall-skill"},{"openapi":"post /api/skills/reload","title":"Reload Skills","href":"/api-reference/skills/reload-skills"}]},{"group":"Templates","expanded":false,"pages":[{"openapi":"get /api/templates/","title":"List Templates","href":"/api-reference/templates/list-templates"},{"openapi":"get /api/templates/{template_id}","title":"Get Template","href":"/api-reference/templates/get-template"},{"openapi":"post /api/templates/{template_id}/use","title":"Use Template","href":"/api-reference/templates/use-template"},{"openapi":"post /api/templates/{template_id}/like","title":"Like Template","href":"/api-reference/templates/like-template"}]},{"group":"MCP","expanded":false,"pages":[{"openapi":"get /api/mcp/apps","title":"List Mcp Apps","href":"/api-reference/mcp-management/list-mcp-apps"},{"openapi":"get /api/mcp/servers","title":"Get Mcp Servers","href":"/api-reference/mcp-management/get-mcp-servers"},{"openapi":"get /api/mcp/servers/{server_id}","title":"Get Mcp Server","href":"/api-reference/mcp-management/get-mcp-server"},{"openapi":"post /api/mcp/servers","title":"Create Mcp Server","href":"/api-reference/mcp-management/create-mcp-server"},{"openapi":"put /api/mcp/servers/{server_id}","title":"Update Mcp Server","href":"/api-reference/mcp-management/update-mcp-server"},{"openapi":"delete /api/mcp/servers/{server_id}","title":"Delete Mcp Server","href":"/api-reference/mcp-management/delete-mcp-server"},{"openapi":"post /api/mcp/servers/{server_id}/toggle","title":"Toggle Mcp Server","href":"/api-reference/mcp-management/toggle-mcp-server"},{"openapi":"post /api/mcp/test-connection","title":"Test Mcp Connection","href":"/api-reference/mcp-management/test-mcp-connection"},{"openapi":"get /api/mcp/servers/{server_id}/tools","title":"Get Mcp Server Tools","href":"/api-reference/mcp-management/get-mcp-server-tools"},{"openapi":"get /api/mcp/servers/{server_id}/logs","title":"Get Mcp Server Logs","href":"/api-reference/mcp-management/get-mcp-server-logs"},{"openapi":"get /api/mcp/transports","title":"Get Supported Transports","href":"/api-reference/mcp-management/get-supported-transports"}]},{"group":"Custom APIs","expanded":false,"pages":[{"openapi":"get /api/custom-apis","title":"List Custom Apis","href":"/api-reference/custom-api-management/list-custom-apis"},{"openapi":"post /api/custom-apis","title":"Create Custom Api","href":"/api-reference/custom-api-management/create-custom-api"},{"openapi":"get /api/custom-apis/{api_id}","title":"Get Custom Api","href":"/api-reference/custom-api-management/get-custom-api"},{"openapi":"put /api/custom-apis/{api_id}","title":"Update Custom Api","href":"/api-reference/custom-api-management/update-custom-api"},{"openapi":"delete /api/custom-apis/{api_id}","title":"Delete Custom Api","href":"/api-reference/custom-api-management/delete-custom-api"}]},{"group":"Share","expanded":false,"pages":[{"openapi":"post /api/share/auth","title":"Authenticate Share Link","href":"/api-reference/share/authenticate-share-link"},{"openapi":"post /api/share/files/upload","title":"Upload Share File","href":"/api-reference/share/upload-share-file"},{"openapi":"post /api/share/chat/task/create","title":"Create Share Task","href":"/api-reference/share/create-share-task"}]},{"group":"Workforces","expanded":false,"pages":[{"openapi":"get /api/workforces","title":"List Workforces","href":"/api-reference/workforces/list-workforces"},{"openapi":"post /api/workforces","title":"Create Workforce","href":"/api-reference/workforces/create-workforce"},{"openapi":"post /api/workforces/from-prompt","title":"Create Workforce From Prompt Endpoint","href":"/api-reference/workforces/create-workforce-from-prompt-endpoint"},{"openapi":"get /api/workforces/agent-options","title":"List Workforce Agent Options","href":"/api-reference/workforces/list-workforce-agent-options"},{"openapi":"get /api/workforces/{workforce_id}","title":"Get Workforce","href":"/api-reference/workforces/get-workforce"},{"openapi":"delete /api/workforces/{workforce_id}","title":"Archive Workforce","href":"/api-reference/workforces/archive-workforce"},{"openapi":"patch /api/workforces/{workforce_id}","title":"Update Workforce","href":"/api-reference/workforces/update-workforce"},{"openapi":"post /api/workforces/{workforce_id}/publish","title":"Publish Workforce","href":"/api-reference/workforces/publish-workforce"},{"openapi":"post /api/workforces/{workforce_id}/unpublish","title":"Unpublish Workforce","href":"/api-reference/workforces/unpublish-workforce"},{"openapi":"post /api/workforces/{workforce_id}/agents","title":"Add Workforce Agent","href":"/api-reference/workforces/add-workforce-agent"},{"openapi":"delete /api/workforces/{workforce_id}/agents/{member_id}","title":"Remove Workforce Agent","href":"/api-reference/workforces/remove-workforce-agent"},{"openapi":"patch /api/workforces/{workforce_id}/agents/{member_id}","title":"Update Workforce Agent","href":"/api-reference/workforces/update-workforce-agent"},{"openapi":"post /api/workforces/{workforce_id}/runs","title":"Create Workforce Run","href":"/api-reference/workforces/create-workforce-run"},{"openapi":"get /api/workforces/{workforce_id}/builder/messages","title":"Get Workforce Builder Messages","href":"/api-reference/workforces/get-workforce-builder-messages"},{"openapi":"post /api/workforces/{workforce_id}/builder/propose","title":"Propose Workforce Changes","href":"/api-reference/workforces/propose-workforce-changes"},{"openapi":"post /api/workforces/{workforce_id}/builder/apply","title":"Apply Workforce Changes","href":"/api-reference/workforces/apply-workforce-changes"},{"openapi":"get /api/workforces/{workforce_id}/canvas","title":"Get Workforce Canvas","href":"/api-reference/workforces/get-workforce-canvas"}]},{"group":"Monitor","expanded":false,"pages":[{"openapi":"get /api/monitor/dashboard-stats","title":"Get Dashboard Stats","href":"/api-reference/monitor/get-dashboard-stats"},{"openapi":"get /api/monitor/stats","title":"Get Monitoring Stats","href":"/api-reference/monitor/get-monitoring-stats"},{"openapi":"get /api/monitor/agents","title":"Get Agents","href":"/api-reference/monitor/get-agents"},{"openapi":"get /api/monitor/tools","title":"Get Tools","href":"/api-reference/monitor/get-tools"},{"openapi":"get /api/monitor/popular-tools","title":"Get Popular Tools","href":"/api-reference/monitor/get-popular-tools"},{"openapi":"get /api/monitor/model-stats","title":"Get Model Stats","href":"/api-reference/monitor/get-model-stats"}]},{"group":"Widget","expanded":false,"pages":[{"openapi":"post /api/widget/auth","title":"Authenticate Widget","href":"/api-reference/widget/authenticate-widget"},{"openapi":"post /api/widget/files/upload","title":"Upload Widget File","href":"/api-reference/widget/upload-widget-file"},{"openapi":"post /api/widget/chat/task/create","title":"Create Widget Task","href":"/api-reference/widget/create-widget-task"}]},{"group":"WebSocket","expanded":false,"pages":[{"title":"WebSocket API","icon":"radio","href":"/api-reference/websocket/websocket"},{"title":"Trace Events Reference","icon":"pulse","href":"/api-reference/websocket/trace-events"}]}]}]}]}]},"basePath":"","title":"Create Chat Task - Xagent","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CS552b7R.js","utils-DDTCYAF2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-De8ttokP.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DrwRDvAh.js","snippetPresets-DtAN0nWx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D5rWArI6.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-O2i12wsz.js","shallow-DV8xABTt.js","getApiPlaygroundDisplay-DBZ0B5Jx.js","CodeSnippet-BVi0tPUX.js","CodeSnippets-CqASbIwY.js","Page-m07pfKpT.js","getPastedJson-DG9vsMS8.js","icon-CXzRSCr8.js","MethodPill-BdKVtEuX.js","DuplicateIcon-CZlmBrJI.js","createIcon-biFEUKPL.js","DynamicMarkdown-B54_zNBF.js","SectionHeading-DwwHK3Pt.js","axios-vUo_bRtp.js","Markdown-DfhCTwyA.js","clsx-xpJZXxdP.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-BTZUMDnx.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-DqdKa2R4.js"]}