---
title: "Add message to a conversation with streaming response"
method: POST
path: "/conversations/{conversationId}/messages/stream"
tags: ["Conversations"]
---

# Add message to a conversation with streaming response

`POST /conversations/{conversationId}/messages/stream`

Add a follow-up message to an existing conversation and stream the
assistant's response over Server-Sent Events.

Functionally equivalent to `POST /conversations/{conversationId}/messages`
but the response is delivered as an SSE stream so clients can render
the answer incrementally.

AG-UI is the sole wire protocol. The vocabulary is described by
`ConversationMessageStreamSSEEvent`; it is the same event set as
`/conversations/stream`, while the terminal result reflects an
existing conversation.

## Path parameters

- `conversationId` string, objectId, required

## Request body

- ConversationMessageStreamRequest — Request body for `POST /conversations/{conversationId}/messages/stream`. The public stream requires an explicit universal execution mode.
  - `query` string, required — The follow-up question or message content
  - `filters` Filters — App connector instance ids and knowledge-base / record-group ids that narrow retrieval for a turn. For **org assistant** chat streams, send explicit `apps` / `kb` lists. For **agent** chat streams, send explicit id lists, or **omit** `filters` (and `tools`) to let the service use the agent’s stored knowledge and tool configuration. Sending `{ "apps": [], "kb": [] }` on an agent stream means **no** knowledge sources for that turn (it is not “full org default”).
    - `apps` string[] — Connector instance ids to scope retrieval for this turn. Each element must be a valid UUID (connector app id, KB app id, record-group id, etc.). Gateway validation matches Zod `appOrKbIdSchema`.
    - `kb` string[] — Knowledge-base app ids to scope retrieval for this turn. Each element must be a valid UUID.
  - `appliedFilters` AppliedFilters — Rich filter state selected by the user, used for display and persistence only. This mirrors the active selection shown in the UI and is distinct from the machine-readable `filters` field used for retrieval scoping.
    - `apps` AppliedFilterNode[] — Applied app/connector filter nodes
      - `id` string — Unique identifier of the filter node
      - `name` string — Display name of the filter node
      - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
      - `connector` string — Connector identifier associated with this node
    - `kb` AppliedFilterNode[] — Applied knowledge-base filter nodes
      - `id` string — Unique identifier of the filter node
      - `name` string — Display name of the filter node
      - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
      - `connector` string — Connector identifier associated with this node
  - `attachments` ChatAttachmentRef[] — Uploaded chat attachments for this follow-up turn (see `POST /conversations/attachments/upload`).
    - `recordId` string, required — Attachment record id returned from the upload endpoint.
    - `recordName` string — Original display name of the file when known.
    - `mimeType` string — MIME type of the uploaded file.
    - `extension` string — File extension (e.g. `pdf`).
    - `virtualRecordId` string — Optional synthetic record id used by the graph layer.
  - `modelKey` string — Override the model for this specific message
  - `modelName` string — Display name of the model
  - `modelFriendlyName` string — Friendly display name of the model
  - `chatMode` 'agent' | 'internal_search' | 'web_search', required — Optional execution mode for non-stream consumers of this shared request schema.
  - `timezone` string — IANA timezone identifier from the client (top-level field). Used to provide time-aware context to the AI.
  - `currentTime` string, date-time — ISO 8601 / RFC 3339 datetime from the client (top-level field; UTC `Z` or numeric offset).
  - `tools` string[] — Optional list of tool identifiers the agent may invoke for this follow-up message. Semantics are identical to the create-conversation tools field.
  - `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 (see `ConversationMessageStreamSSEEvent`). Kept in the schema for backward compatibility with callers that already send it.
  - `agentCapabilities` AgentCapabilities — Per-request agent capability toggles. Only meaningful when `chatMode` selects an agent mode; ignored otherwise. Each field falls back to its own `default` below when omitted — a missing flag is not uniformly `true`. Omitting the whole object applies every default.
    - `internalSearch` boolean — Whether the agent may search internal knowledge bases for this turn.
    - `webSearch` boolean — Whether the agent may perform web search for this turn.
    - `deepSearch` boolean — Whether the agent may use deeper, higher-latency retrieval for this turn.

## Response `200`

SSE stream established. The body is a sequence of
`text/event-stream` frames using the event vocabulary described
on the schema below.

## Other responses

- `400` — Invalid request — `query` is missing or empty, or another field fails validation (for example a malformed `currentTime`).
- `401` — Unauthorized — valid bearer token required.
- `403` — Forbidden — the caller's token does not include the `conversation:chat` OAuth scope.
- `404` — The conversation does not exist, is deleted, or does not belong to the caller.
- `500` — Internal error before the SSE stream is established (for example, the user message could not be persisted to the conversation). Once the stream is open, terminal failures are surfaced as a `RUN_ERROR` SSE event instead of an HTTP status change.

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/revisions/64bfe76b130e/schema)