Sign in
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.

Changes

Changed in 1 of the 15 revisions of this API.23310

  • 5798f431973a23310See the full diff
    • ▲

      added CreateConversationRequest subschema #2 to the request body allOf list

      request-body-all-of-added

    • ▲

      the request's body type/format changed from object/ to /

      request-body-type-changed

    • ●

      removed the request property appliedFilters

      request-property-removed

    • ●

      removed the request property attachments

      request-property-removed

    • ●

      removed the request property chatMode

      request-property-removed

    • ●

      removed the request property currentTime

      request-property-removed

    • ●

      removed the request property filters

      request-property-removed

    • ●

      removed the request property modelFriendlyName

      request-property-removed

    • ●

      removed the request property modelKey

      request-property-removed

    • ●

      removed the request property modelName

      request-property-removed

    • ●

      removed the request property query

      request-property-removed

    • ●

      removed the request property recordIds

      request-property-removed

    • ●

      removed the request property timezone

      request-property-removed

    • ●

      removed the request property tools

      request-property-removed

    • ●

      added the new CUSTOM enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new HEARTBEAT enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new REASONING_END enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new REASONING_MESSAGE_CONTENT enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new REASONING_MESSAGE_END enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new REASONING_MESSAGE_START enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new REASONING_START enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new RUN_ERROR enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new RUN_FINISHED enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new RUN_STARTED enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new STATE_DELTA enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new STATE_SNAPSHOT enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new STEP_FINISHED enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new STEP_STARTED enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TEXT_MESSAGE_CONTENT enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TEXT_MESSAGE_END enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TEXT_MESSAGE_START enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TOOL_CALL_ARGS enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TOOL_CALL_END enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TOOL_CALL_RESULT enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TOOL_CALL_START enum value to the event response property for the response status 200

      response-property-enum-value-added

    • ○

      removed the answer_chunk enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the complete enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the connected enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the error enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the restreaming enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the status enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the tool_call enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the tool_calls enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the tool_error enum value from the event response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the tool_success enum value from the event response property for the response status 200

      response-property-enum-value-removed

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog