---
title: "Ask the AI Assistant, streaming its work"
method: POST
path: "/assistant/chat/conversations/{conversation_id}/messages/stream/"
tags: ["assistant"]
---

# Ask the AI Assistant, streaming its work

`POST /assistant/chat/conversations/{conversation_id}/messages/stream/`

## Request

- Base URL: `https://api.getoneprofile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getoneprofile.ai/assistant/chat/conversations/{conversation_id}/messages/stream/`
- Auth: HTTP bearer

Run one turn and stream it as Server-Sent Events: a `plan` frame whenever the AI Assistant publishes or ticks its plan, a `step` frame for each thing the AI Assistant actually did (read_context when the workspace has a business context, then plan, then write_column, retry_column and price_column for a column the message described, then one apply_action per action it applied), one `turn` frame naming the saved user message's sequence once it is saved (the Stop route is addressed by it), `delta` frames carrying the whole reply so far (assign, never append), a `said` frame when a later round of the turn starts writing (the words the reply showed until then, now a step: put `step` at `at` among the steps sent and empty the reply, which the next `delta` fills), then exactly one `result` frame with the same body the non-streaming route returns, the reply carrying its action cards, sent once the reply is saved. The last `delta` always equals the saved reply.

A turn that could not run ends in one `error` frame whose `reason` is `limit`, `paused` or `not_found`; a message naming a file that is not yours or was already sent ends in an `error` frame with no reason and nothing saved; any other failure is an `error` frame with no reason. A turn that breaks while running still ends in a `result` whose reply carries `failed`, and so does a stopped one, its reply reading `Stopped by you`.

Closing the connection does not cancel the turn: it finishes and saves its reply, so reopening the conversation shows the answer.

## Path parameters

- `conversation_id` string, uuid, required

## Request body

- WorkspaceChatMessageCreateSchema: Send the AI Assistant a message.
  - `attachment_ids` string[]: The files sent with this message, as the attachments route returned them when they were uploaded: CSV, Excel or PDF, each of them yours and not yet sent with another message. The assistant reads a spreadsheet's columns and rows and a PDF's pages. Optional.
  - `page` PageContextSchema: What the person had open when they sent the message. So "this table" resolves without them naming it. Sent by the dashboard, optional everywhere: a message from anywhere else simply carries none. Kept with the message and read back with it, so the transcript can say where each message was sent from.
    - `entity_id` string, nullable: The id of that thing.
    - `entity_name` string, nullable: What it is called, as the page showed it, so the assistant can say it back. Cut to 255 characters rather than refused.
    - `entity_type` string, nullable: What the page is about: `table`, `sequence`, `agent`, `integration`, `inbox thread`, `sender` or `mailbox`. Null on a page about no one thing.
    - `page_name` string, nullable: The page or tab they have open, in the screen's own words: a sequence's "Audience" tab, an agent's "Train", or a page about no one thing, such as "Tasks".
    - `route` string, nullable: The path they have open, e.g. `/tables/1234`.
    - `selected_step_id` string, nullable: The selected sequence builder step; resolve it against the sequence before editing.
    - `selected_step_label` string, nullable: The selected step as the Builder numbers and names it, e.g. "Step 1 · Opener". The id is what to edit by; this is how the person sees it.
  - `pasted` string[], nullable: A list you pasted rather than typed: domains, emails, names, one per entry. Sent as data instead of prose, so the assistant reads it as a list and the conversation shows it as a count rather than a wall of text. Optional.
  - `prompt` string, required
  - `quote` string, nullable: Part of an earlier reply you selected, sent with your words so the assistant knows what they refer to. Kept with the message and shown above it in the conversation. Optional.

## Response `200`

A stream of Server-Sent Events. The final `result` frame's `data` is a turn; an `error` frame's `data` is a stream error.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Invalid request made to the API.
- `500`: Internal server error.
- `502`: Bad gateway error.
- `503`: Service unavailable.

---

[API](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile.md) · [All operations](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/llms.txt) · [OpenAPI document](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/revisions/4a6bd71e3f02?raw)