# Streaming protocol
CKEditor AI streams its answers as Server-Sent Events (SSE). Use this page to write the client that reads the stream: the event names for your endpoint family, the order of the events, and the event that ends the stream. To learn what the streaming endpoints do and when to call them, start with the [REST API](rest-api.md) guide.
## Event types
Every stream opens with a metadata event. The events that follow depend on the endpoint family.
The tables list the event names and what each event means. For the fields and types in each payload, see the [API reference](https://ai.cke-cs.com/v1/docs).
### Conversations
| Event | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `message-metadata` | The `messageId` of the reply the endpoint streams. Sent first. |
| `text-delta` | A chunk of the reply text from the model. |
| `reasoning` | The model runs a reasoning step. The event has no payload. |
| `web-search` | The model runs a web search. The event has no payload. |
| `source` | One source the web search found, with its URL and title, and a `favicon` URL for an attribution chip. |
| `document-read` | The model read part of an attached document. `method` names how it read it. |
| `modification-delta` | An edit the model proposes for the document. |
| `conversation-title` | A title the model suggests for the conversation. |
| `mcp-tool-result` | The result of an MCP tool call. The service adds the server name as a prefix to `toolName`. |
| `mcp-tool-notification` | A notification from an MCP tool that is not part of a tool result. `level` runs from `debug` to `emergency`. |
| `hook-progress` | The progress text a hook reports, in `text`. |
| `error` | The model provider failed during the stream. Ends the stream. |
### Reviews
| Event | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `review-metadata` | The `callId`, and `pendingElements` with the number of elements under review. Sent first. |
| `review-delta` | One event for each element under review. The event has the `dataId` of the element and an `operation`: `'edit'` when the model suggests a change, `'unmodified'` when it does not. An `edit` operation streams the new text as deltas. |
| `error` | The model provider failed during the stream. Ends the stream. |
### Actions
| Event | Description |
| -------------------- | --------------------------------------------------------------------------- |
| `action-metadata` | The `callId`. Sent first. |
| `modification-delta` | A chunk of the HTML content after the transformation. |
| `text-delta` | A chunk of the generated text content. Only with `outputFormat: plainText`. |
| `error` | The model provider failed during the stream. Ends the stream. |
### Document Processing
| Event | Description |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `metadata` | The stream ID. Sent first. |
| `document-delta` | The full document HTML with all modifications applied. Only with `responseFormat: html`. |
| `modification-delta` | A chunk of a document modification, in the fragment format. Only with `responseFormat: arf`. |
| `text-delta` | A chunk of the text that summarizes the changes. Sent in both formats. |
| `document` | The final document and the summary. Sent last. |
| `mcp-tool-result` | The result of an MCP tool call. |
| `mcp-tool-notification` | A notification from an MCP tool that is not part of a tool result. |
| `error` | The model provider failed during the stream. Ends the stream. |
Actions use the `outputFormat` parameter, and Document Processing uses `responseFormat`. The two names are not interchangeable.
## Event ordering
Every stream starts with the metadata event of its family: `message-metadata`, `review-metadata`, `action-metadata`, or `metadata`. A Document Processing stream ends with the `document` event. An `error` event ends any stream at any point.
Modification deltas arrive in the order you apply them. A Document Processing request can contain several documents, and the stream then sends deltas for all of them. Each `document-delta` and `modification-delta` then has a `documentId` field that names the document it belongs to. The service omits the field when the request has one document.
One modification arrives as several `modification-delta` events that share an `id`. They break wherever the model pauses, including mid-tag and mid-attribute, so join the events of one `id` before you parse the markup.
## Error handling
An `error` event ends the stream. The payload has a `message`, and can also have a `cause` with more detail. The service sends no retry signal. Choose your own retry policy, such as an exponential backoff and a maximum number of attempts.
A request that fails before the stream opens returns an HTTP error status, not an `error` event. See [Error codes](rest-api.md#error-codes).
## API reference
The [API reference](https://ai.cke-cs.com/v1/docs) has the request and response schemas of every streaming endpoint. For versioning, limits, and error codes, see [REST API](rest-api.md).
## Next steps
* **[Conversations](conversations.md)** run a multi-turn chat with documents and files in context.
* **[Reviews](reviews.md)** check a document and anchor each suggestion to the element it applies to.
* **[Actions](actions.md)** apply a single transformation to a piece of content.
* **[Document Processing](document-processing.md)** edits a whole document in one call.
* **[Fragment responses](fragment-responses.md)** explains the fragment format that `modification-delta` events use in Conversations and Document Processing.
---
Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)