Organization
Users and User Groups
Permissions
Data Source
Workspaces
Logical Data Model
Analytical Objects
Reporting
Export & Automations
AI Lake
AI Assistant
    Conversations
      List conversationsgetStart a conversationpostGet a conversationgetDelete a conversationdeleteUpdate a conversationpatchLink a saved dashboardpatchSubmit feedbackpostGenerate a titlepostList conversation itemsgetSend a messagepostList responsesgetRate a responsepatchList reasoning stepsgetSwitch agentpostLink a saved visualizationpatch
    Dashboard Summary
    Knowledge
    Knowledge Recommendations
    Memory Items
    LLM Providers
    Observability
Agents
Other
Schemas
powered by Zudoku
OpenAPI definition

Conversations

Endpoint:/

Chat with an AI Assistant agent. A conversation holds the message history for one workspace and user; sending a message streams the agent's reply back over SSE as a sequence of items (text, visualizations, dashboards) that these endpoints then read back, rate, or link to saved metadata objects.

List conversations

GET
/api/v1/ai/workspaces/{workspace_id}/chat/conversations

Conversations belonging to the current user in this workspace.

List conversations › path Parameters

  • workspace_idstring · required

List conversations › query Parameters

  • isPreviewboolean
    Default: false
  • pageinteger · min: 0
    Default: 0
  • sizeinteger · min: 1 · max: 100
    Default: 20

List conversations › Responses

Successful Response

  • dataobject[] · required
  • metaobject · required
GET /api/v1/ai/workspaces/{workspace_id}/chat/conversations

Start a conversation

POST
/api/v1/ai/workspaces/{workspace_id}/chat/conversations

Start a conversation › path Parameters

  • workspace_idstring · required

Start a conversation › query Parameters

  • isPreviewboolean
    Default: false

Start a conversation › Request Body

  • agentId
  • mode

    What this conversation serves. Omit for USER — a person's own thread in the assistant. PREVIEW backs the Agent Builder preview pane; MCP backs a single-purpose MCP tool call. Anything other than USER is a utility conversation: it is persisted (so follow-up turns can continue it) but kept out of the user's conversation list and out of per-agent last-activity, and it cannot switch agent.

    Mutually exclusive with the deprecated isPreview query parameter.

Start a conversation › Responses

Successful Response

  • conversationIdstring · required

    Conversation identifier.

  • createdAtstring · required

    Conversation creation timestamp (ISO-8601 UTC).

  • lastActivityAtstring · required

    Last activity timestamp (ISO-8601 UTC).

  • organizationIdstring · required

    Organization identifier.

  • userIdstring · required

    Owner user identifier.

  • workspaceIdstring · required

    Workspace identifier.

  • agentId

    Identifier of the agent bound to this conversation (if any).

  • modestring · enum

    What a conversation exists to serve.

    USER is a person's own thread in the assistant. The others are utility modes, where the conversation serves something else and is kept out of the user's history: PREVIEW backs the Agent Builder preview pane, MCP backs a single-purpose MCP tool call.

    Enum values:
    USER
    PREVIEW
    MCP
  • pinnedboolean

    Whether this conversation is pinned by the user.

    Default: false
  • title

    Conversation title.

  • isPreviewboolean · deprecated · required

    Deprecated, use mode. True only when mode is PREVIEW.

    Default: false
POST /api/v1/ai/workspaces/{workspace_id}/chat/conversations

Get a conversation

GET
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Get a conversation › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Get a conversation › Responses

Successful Response

  • conversationIdstring · required

    Conversation identifier.

  • createdAtstring · required

    Conversation creation timestamp (ISO-8601 UTC).

  • lastActivityAtstring · required

    Last activity timestamp (ISO-8601 UTC).

  • organizationIdstring · required

    Organization identifier.

  • userIdstring · required

    Owner user identifier.

  • workspaceIdstring · required

    Workspace identifier.

  • agentId

    Identifier of the agent bound to this conversation (if any).

  • modestring · enum

    What a conversation exists to serve.

    USER is a person's own thread in the assistant. The others are utility modes, where the conversation serves something else and is kept out of the user's history: PREVIEW backs the Agent Builder preview pane, MCP backs a single-purpose MCP tool call.

    Enum values:
    USER
    PREVIEW
    MCP
  • pinnedboolean

    Whether this conversation is pinned by the user.

    Default: false
  • title

    Conversation title.

  • isPreviewboolean · deprecated · required

    Deprecated, use mode. True only when mode is PREVIEW.

    Default: false
GET /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Delete a conversation

DELETE
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Delete a conversation › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Delete a conversation › Responses

Successful Response

No data returned
DELETE /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Update a conversation

PATCH
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Only the title and the pinned flag can be changed.

Update a conversation › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Update a conversation › Request Body

  • pinned
  • title

Update a conversation › Responses

Successful Response

  • conversationIdstring · required

    Conversation identifier.

  • createdAtstring · required

    Conversation creation timestamp (ISO-8601 UTC).

  • lastActivityAtstring · required

    Last activity timestamp (ISO-8601 UTC).

  • organizationIdstring · required

    Organization identifier.

  • userIdstring · required

    Owner user identifier.

  • workspaceIdstring · required

    Workspace identifier.

  • agentId

    Identifier of the agent bound to this conversation (if any).

  • modestring · enum

    What a conversation exists to serve.

    USER is a person's own thread in the assistant. The others are utility modes, where the conversation serves something else and is kept out of the user's history: PREVIEW backs the Agent Builder preview pane, MCP backs a single-purpose MCP tool call.

    Enum values:
    USER
    PREVIEW
    MCP
  • pinnedboolean

    Whether this conversation is pinned by the user.

    Default: false
  • title

    Conversation title.

  • isPreviewboolean · deprecated · required

    Deprecated, use mode. True only when mode is PREVIEW.

    Default: false
PATCH /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}

Link a saved dashboard

PATCH
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/dashboards/{dashboard_id}

Re-points the conversation's dashboard at the metadata object the user saved.

Link a saved dashboard › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required
  • dashboard_idstring · required

Link a saved dashboard › Request Body

  • idstring · minLength: 1 · required

Link a saved dashboard › Responses

Successful Response

No data returned
PATCH /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/dashboards/{dashboard_id}

Submit feedback

POST
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/feedback

Submit feedback › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Submit feedback › Request Body

  • feedbackrequired
  • responseIdstring · minLength: 1 · required

Submit feedback › Responses

Successful Response

No data returned
POST /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/feedback

Generate a title

POST
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/generateTitle

Derives a title for the conversation from the messages exchanged so far.

Generate a title › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Generate a title › Responses

Successful Response

  • conversationIdstring · required

    Conversation identifier.

  • createdAtstring · required

    Conversation creation timestamp (ISO-8601 UTC).

  • lastActivityAtstring · required

    Last activity timestamp (ISO-8601 UTC).

  • organizationIdstring · required

    Organization identifier.

  • userIdstring · required

    Owner user identifier.

  • workspaceIdstring · required

    Workspace identifier.

  • agentId

    Identifier of the agent bound to this conversation (if any).

  • modestring · enum

    What a conversation exists to serve.

    USER is a person's own thread in the assistant. The others are utility modes, where the conversation serves something else and is kept out of the user's history: PREVIEW backs the Agent Builder preview pane, MCP backs a single-purpose MCP tool call.

    Enum values:
    USER
    PREVIEW
    MCP
  • pinnedboolean

    Whether this conversation is pinned by the user.

    Default: false
  • title

    Conversation title.

  • isPreviewboolean · deprecated · required

    Deprecated, use mode. True only when mode is PREVIEW.

    Default: false
POST /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/generateTitle

List conversation items

GET
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/items

Items in the order the agent produced them: text, visualizations, dashboards.

List conversation items › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

List conversation items › Responses

Successful Response

  • itemsobject[] · required

    Ordered list of conversation items.

GET /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/items

Send a message

POST
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/messages

Streams the agent's reply back over SSE; see the 200 response for the event sequence.

Send a message › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Send a message › Request Body

  • itemobject · required
  • options
  • userContext

Send a message › Responses

SSE stream with response_started/item/response_ended events; when interaction intelligence is enabled, interaction_step events (payload {"step": ...}) stream alongside the items.

string
POST /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/messages

List responses

GET
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/responses

List responses › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

List responses › Responses

Successful Response

  • responsesobject[] · required

    Conversation responses.

GET /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/responses

Rate a response

PATCH
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/responses/{response_id}

Attaches positive or negative feedback, with optional free-text, to one response.

Rate a response › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required
  • response_idstring · required

Rate a response › Request Body

  • feedbackrequired

Rate a response › Responses

Successful Response

No data returned
PATCH /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/responses/{response_id}

List reasoning steps

GET
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/steps

The agent's interaction steps, available when interaction intelligence is enabled.

List reasoning steps › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

List reasoning steps › query Parameters

  • responseId

List reasoning steps › Responses

Successful Response

  • stepsobject[] · required

    Ordered list of interaction steps.

GET /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/steps

Switch agent

POST
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/switchAgent

Changes the active agent on an existing conversation.

Switch agent › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required

Switch agent › Request Body

  • agentIdstring · required

Switch agent › Responses

Successful Response

  • conversationIdstring · required

    Conversation identifier.

  • createdAtstring · required

    Conversation creation timestamp (ISO-8601 UTC).

  • lastActivityAtstring · required

    Last activity timestamp (ISO-8601 UTC).

  • organizationIdstring · required

    Organization identifier.

  • userIdstring · required

    Owner user identifier.

  • workspaceIdstring · required

    Workspace identifier.

  • agentId

    Identifier of the agent bound to this conversation (if any).

  • modestring · enum

    What a conversation exists to serve.

    USER is a person's own thread in the assistant. The others are utility modes, where the conversation serves something else and is kept out of the user's history: PREVIEW backs the Agent Builder preview pane, MCP backs a single-purpose MCP tool call.

    Enum values:
    USER
    PREVIEW
    MCP
  • pinnedboolean

    Whether this conversation is pinned by the user.

    Default: false
  • title

    Conversation title.

  • isPreviewboolean · deprecated · required

    Deprecated, use mode. True only when mode is PREVIEW.

    Default: false
POST /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/switchAgent

Link a saved visualization

PATCH
/api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/visualizations/{visualization_id}

Re-points the conversation's visualization at the metadata object the user saved.

Link a saved visualization › path Parameters

  • workspace_idstring · required
  • conversation_idstring · required
  • visualization_idstring · required

Link a saved visualization › Request Body

  • idstring · minLength: 1 · required

Link a saved visualization › Responses

Successful Response

No data returned
PATCH /api/v1/ai/workspaces/{workspace_id}/chat/conversations/{conversation_id}/visualizations/{visualization_id}
AI Lake - Iceberg REST CatalogDashboard Summary