Sign in
OpenAPI 3.0.0raw.githubusercontent.com2026-08-1291215647.5 KB

11f5086fcbb8

Conversations

Create conversation with streaming response

Start a new conversation and stream the AI response over Server-Sent Events (SSE). Behaves like POST /conversations but emits tokens, tool activity, and status updates incrementally instead of returning a single JSON response at the end.

Lifecycle

  1. The server validates query, persists an in-progress conversation, then opens the SSE stream with HTTP 200.
  2. A CUSTOM event named conversation_created is emitted immediately with the new conversationId so the client can link the stream (sidebar, parallel tabs, deep links) without an extra request.
  3. AI-backend events stream through (token chunks, tool calls, status, etc.).
  4. On success a single root RUN_FINISHED event is emitted carrying the full persisted conversation in result.
  5. On failure a root RUN_ERROR event is emitted and the conversation is marked FAILED before the stream closes.

Event vocabulary

AG-UI is the sole wire protocol. See ConversationStreamSSEEvent for the full event enum and payload guidance.

Clients should ignore unknown event names rather than treating them as errors.

Agent mode

When chatMode is agent, the optional tools list restricts which tools the agent may invoke for this turn. Outside agent modes the tools field is ignored.

post/conversations/stream

Request body

querystring required

The user's question or prompt to start the conversation. Supports natural language queries of any complexity.

recordIdsstring[]

Limit the AI's knowledge scope to specific records/documents. When provided, only these records will be searched for context.

modelKeystring

Identifier for the AI model configuration to use. Available models depend on organization settings.

modelNamestring

Display name of the AI model

modelFriendlyNamestring

Friendly display name of the selected model

chatMode'agent' | 'internal_search' | 'web_search' required

Optional execution mode for non-stream consumers of this shared request schema. agent uses the universal agent loop, while internal_search and web_search use their corresponding assistant search paths.

timezonestring

IANA timezone identifier from the client (top-level field). Used to provide time-aware context to the AI.

currentTimestring date-time

ISO 8601 / RFC 3339 datetime from the client (top-level field; UTC Z or numeric offset).

toolsstring[]

Optional list of tool identifiers (fully-qualified action names such as "jira.create_issue") that the AI agent is permitted to invoke for this request. When omitted the agent may use any configured tool. Applicable only when chatMode is agent.

protocol'agui'

AG-UI is the only supported wire protocol. When present must be "agui". Omitting the field is equivalent — the server always uses the AG-UI vocabulary (RUN_STARTED, TEXT_MESSAGE_CONTENT, etc.). Kept in the schema for backward compatibility with callers that already send it.

Example request

{
  "query": "What are the key findings from our Q4 financial report?",
  "recordIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "modelKey": "gpt-4-turbo",
  "modelName": "GPT-4 Turbo",
  "modelFriendlyName": "GPT-4 Turbo",
  "chatMode": "internal_search",
  "timezone": "America/New_York",
  "currentTime": "2026-04-12T16:00:00+05:30",
  "tools": [
    "jira.create_issue",
    "confluence.search_content"
  ]
}

Response

SSE stream established. The body is a sequence of text/event-stream frames using the event vocabulary described above.