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.

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.

Request:

curl -X POST https://sg-origin.cloud.xagent.co/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",
  "connector_runtime_requirements": null
}

Also always present: connector_runtime_requirements — see the Connector Runtime Requirements section below. It reports what a task created from the given agent needs (never a stored value), and is null when created through the public widget or share-link paths, which never see connector key names.

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, 503 (the agent's knowledge base could not be resolved against its team — see the note below).

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.

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": []
}

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.

Connector Runtime Requirements

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

Reports which runtime inputs an agent's connectors declare (context values, secrets, or an auth selector) and whether each one already has a value — never the value itself, and never a connector's URL, headers, or authentication configuration. Two read endpoints return the same shape, and POST /api/chat/task/create's response also includes it (see connector_runtime_requirements below):

Response (200):

{
  "satisfied": false,
  "secrets_expires_at": null,
  "connectors": [
    {
      "connector_ref": { "connector_type": "custom_api", "connector_id": 17 },
      "name": "Internal Ticketing API",
      "inputs": [
        { "section": "context", "key": "project_key", "type": "string", "required": true, "satisfied": false, "expired": false }
      ]
    }
  ]
}

The task-keyed read endpoint's access is plain task ownership and does not extend the admin exception that /task/{task_id}/runtime-extensions has. Errors: 404 (agent or task not found, or not yours).

Submitting Values — POST /api/chat/task/{task_id}/connector-runtime-values

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

Supplies context values for the connectors a task already has selected. Only context is accepted at this phase — a secrets or auth_selector key in the request body is rejected outright rather than silently accepted and ignored.

{
  "items": [
    {
      "connector_ref": { "connector_type": "custom_api", "connector_id": 17 },
      "context": { "project_key": "ENG" }
    }
  ]
}

Values merge key by key, and a stored value is never replaced:

• a key the task does not have yet is written;
• a key already stored with the identical value is a no-op;
• a key already stored with a different value fails the whole request with no partial write — 409, error code runtime_context_immutable.

On success (200), the response is the same requirements report the read endpoints return, reflecting exactly what was just merged in — a 200 means only that the submitted keys were accepted, not that every required input is now present; check the response's own satisfied fields for that. A ref that is not currently visible or was not selected for this task answers the same uniform 404 a read endpoint would.

Errors use a structured envelope, { "error": { "code", "message", "details" } }, rather than the plain-detail shape the read endpoints use:

Next Steps

• Workspace SDK → — the versioned /v1 task API
• End-to-End Example →