Chat with a Workspace

Stream a conversation with a workspace’s AI agent over HTTP and receive generated charts in the response stream

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. generateSql, generateChart)
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 === "generateChart". 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
  "explanation": "A bar chart best shows the month-over-month comparison…"
}

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" &&
      event.payload?.toolName === "generateChart" &&
      event.payload?.result?.chartConfig
    ) {
      chart = event.payload.result; // { chartConfig, chartData, ... }
    }
  }
}

Rate limits

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