Xagent Docs
Get started

Chat / Tasks API

The /api/chat endpoints create and track chat tasks in the web application. Authenticate with a JWT access token from POST /api/auth/login, sent as a bearer token. Errors use the { "detail": "..." } shape; see the API Reference for the full auth and error model.

App API vs Workspace SDK

These /api/chat/* endpoints are the application surface used by the web app. For stable, versioned programmatic integration, prefer the Workspace SDK (POST /v1/chat/tasks) — a smaller, versioned contract. The two surfaces create tasks independently and return different shapes.

Create a Task — POST /api/chat/task/create

Auth: JWT access tokenfrom POST /api/auth/login

Creates a chat task. Only title is required; supply agent_id to run a specific Agent Builder agent.

FieldTypeRequiredDescription
titlestringYesTask title. The only required field.
descriptionstringNoLonger task description.
agent_idintegerNoAgent Builder agent to run.
filesarrayNoUploaded file_ids to attach to the task.
execution_modestringNoOne of flash, balanced, think, auto.
agent_typestringNoDefault standard.
is_visiblebooleanNoDefault true. Set is_preview: true for a hidden preview run.
llm_idsarrayNoModel ids by slot: [default, fast, vision, compact].
memory_similarity_thresholdnumberNoDefault 1.5.
agent_configobjectNoInline agent configuration overrides.

Request:

curl -X POST http://localhost:8000/api/chat/task/create \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summarize Q2 report",
    "description": "Summarize the attached PDF",
    "agent_id": 42,
    "execution_mode": "balanced"
  }'

Response (200): required fields are task_id, title, status, and created_at; the model / channel / agent fields are populated when applicable.

{
  "task_id": 1001,
  "title": "Summarize Q2 report",
  "status": "pending",
  "created_at": "2026-07-10T09:20:00Z",
  "model_id": "gpt-4o",
  "model_name": "gpt-4o",
  "small_fast_model_id": null,
  "visual_model_id": null,
  "compact_model_id": null,
  "execution_mode": "balanced",
  "channel_id": null,
  "channel_name": null,
  "agent_id": 42,
  "agent_name": "Research Assistant",
  "agent_logo_url": "/uploads/agent_logos/agent_42.png"
}

Validation error (422): missing or malformed fields return FastAPI's validation shape — an array of per-field errors:

HTTP/1.1 422 Unprocessable Entity
{
  "detail": [
    { "loc": ["body", "title"], "msg": "Field required", "type": "missing" }
  ]
}

Errors: 401 (missing/invalid token), 404 "Agent not found or access denied" (bad agent_id), 422 (validation), 500.

Other Task Endpoints

The rest of the task lifecycle on the application API. All require the same JWT bearer auth and return { "detail": ... } on error.

MethodPathPurpose
GET/api/chat/tasksList tasks (paginated: page, per_page, search, and filters). Returns { tasks, pagination }.
GET/api/chat/task/{task_id}Full task detail.
GET/api/chat/task/{task_id}/statusLightweight status — poll this while a task runs.
PUT/api/chat/task/{task_id}Update task details (e.g. title).
DELETE/api/chat/task/{task_id}Delete a task and its related data.
GET/api/chat/workspace/{task_id}/filesWorkspace files produced during the run.
GET/api/chat/workspace/{task_id}/outputFinal output files.
GET/api/chat/task/{task_id}/runtime-extensionsLive metadata published by the runtime extensions active on this task.

Runtime Extensions — GET /api/chat/task/{task_id}/runtime-extensions

Auth: JWT access tokenfrom POST /api/auth/login

Returns metadata published by each runtime extension attached to the task. Values are read live from every registered extension on each call rather than served from a stored snapshot, and only fields an extension explicitly publishes are exposed.

Response (200):

{
  "task_id": 1001,
  "runtime_extensions": {
    "example_extension": { "status": "ready" }
  },
  "runtime_extensions_status": "complete",
  "runtime_extensions_omitted": []
}
FieldDescription
runtime_extensionsExtension name → that extension's published metadata.
runtime_extensions_statuscomplete when every extension's metadata is included; truncated when some was dropped to stay within the response size cap.
runtime_extensions_omittedNames dropped because of that cap.

The endpoint is fail-closed: if an extension cannot report, the call returns an error rather than partial data. Errors: 404 "Task not found" (also when the task is not yours), 400 or 403 from an extension, 500.

Full generated reference

Every application endpoint and its exact schema is available from the live OpenAPI spec — open /docs (Swagger) or /openapi.json on a running instance. This page curates the high-value task endpoints; the generated spec is the exhaustive source.

Next Steps