Chat with a Workspace

Ask a workspace’s agent a question and stream the answer. The agent answers with text and, when the question calls for a visualization, a generated chart configuration you can render, save, and add to dashboards. It always answers from the workspace’s published (production) version.

This endpoint streams its response. It is not part of the OpenAPI playground — use the examples below to integrate it.

Endpoint

POST https://api.upsolve.ai/v2/api/projects/{projectId}/workspaces/{workspaceId}/chat

Path parameter	Type	Description
`projectId`	string (UUID)	The project. Both IDs are in the workspace’s URL in the hub, `/projects/{projectId}/workspaces/{workspaceId}`, and in the embed snippet on its Deploy page.
`workspaceId`	string (UUID)	The workspace whose agent answers.

This replaces POST /v1/api/project-agents/{agentId}/chat, which has been removed along with project agents. Requests now name the project and the workspace in the path.

Authentication

Authenticate with a project user token obtained from Get Project User Token:

Authorization: Bearer <project_user_token>

The token must be for the project in the URL. It determines whose data the agent can access, so each of your end users sees only their own data.

Request body

Field	Type	Required	Description
`messages`	array	Yes	The new turn, as `[{ "role": "user", "content": "<the question>" }]`. Only the new question is needed: the agent remembers earlier turns of the same `thread_id`.
`thread_id`	string	No	The conversation this turn belongs to. Reuse it across turns so the agent keeps context (previous SQL, chart, and data); a new ID starts a new conversation.

{
  "messages": [{ "role": "user", "content": "Show me revenue by month for 2025" }],
  "thread_id": "thread-4f2a1c"
}

Response stream

The response is a text/event-stream of newline-separated events, each on a data: {json} line. Every event has a type; the ones you need are:

Event type	Payload	Meaning
`text-start`	—	A new assistant text message begins
`text-delta`	`payload.text`	Next chunk of assistant text
`text-end`	—	The current text message is complete
`tool-call`	`payload.toolName`	The agent started a tool (e.g. `getRowData`, `visualizeData`)
`tool-result`	`payload.toolName`, `payload.result`	A tool finished; `result` holds its output

Other event types may appear (workflow steps, finish markers); ignore any type you don’t handle.

The chart result

When the agent builds a chart, a tool-result event arrives with payload.toolName === "visualizeData" ("renderChart" from an agent deployed before that tool was renamed, and "generateChart" for an organization still on the legacy agent). Its payload.result contains:

{
  "chartConfig": {
    // A complete chart configuration, including the SQL that powers it
    "title": "Monthly Revenue 2025",
    "type": "bar",
    "dimensions": [ { "name": "Month", "field": "month", "type": "date", "bucketing": "month" } ],
    "measures": [ { "name": "Revenue", "field": "revenue", "aggregation": "sum" } ],
    "settings": { "layout": "vertical" },
    "sqlOverride": "SELECT ..." // baked in by the agent — required for saving
  },
  "chartData": [ /* the aggregated rows the chart plots */ ],
  "generatedChartRef": "d5e0…", // session-scoped reference — not a saved chart ID
  "notes": ["Showed 12 of 14 months."] // optional: what the chart could not do as asked
}

A visualizeData call that drew no chart answers "status": "failed" with an "error" explaining why, or "status": "skipped" with "notes"; in both, chartConfig is null and generatedChartRef is null, so check for a chartConfig before treating a result as a chart.

chartConfig is ephemeral — the chat endpoint does not persist charts. To keep a chart (and add it to a dashboard), pass chartConfig to Save Chart from Chat. Do not strip sqlOverride; a chart saved without it cannot load data on a dashboard. generatedChartRef is a transient session ID, not a chart ID.

Example: call and parse the stream

const response = await fetch(
  `https://api.upsolve.ai/v2/api/projects/${projectId}/workspaces/${workspaceId}/chat`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${projectUserToken}`,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Show me revenue by month for 2025" }],
      thread_id: threadId,
    }),
  }
);

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
let assistantText = "";
let chart: { chartConfig: unknown; chartData: unknown[] } | null = null;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? "";

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const event = JSON.parse(line.slice(6));

    if (event.type === "text-delta") {
      assistantText += event.payload?.text ?? "";
    }

    if (
      event.type === "tool-result" &&
      ["visualizeData", "renderChart", "generateChart"].includes(
        event.payload?.toolName
      ) &&
      event.payload?.result?.chartConfig
    ) {
      chart = event.payload.result; // { chartConfig, chartData, ... }
    }
  }
}

Rate limits

Requests are rate limited at 180 requests per minute per organization + user.

Applications (legacy)

API Documentation

Chat with a Workspace

Endpoint

Authentication

Request body

Response stream

The chart result

Example: call and parse the stream

Rate limits

​Endpoint

​Authentication

​Request body

​Response stream

​The chart result

​Example: call and parse the stream

​Rate limits

Endpoint

Authentication

Request body

Response stream

The chart result

Example: call and parse the stream

Rate limits