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 guide.
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.
| 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. |
| 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. |
| 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. |
| 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.
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.
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.
The API reference has the request and response schemas of every streaming endpoint. For versioning, limits, and error codes, see REST API.
- Conversations run a multi-turn chat with documents and files in context.
- Reviews check a document and anchor each suggestion to the element it applies to.
- Actions apply a single transformation to a piece of content.
- Document Processing edits a whole document in one call.
- Fragment responses explains the fragment format that
modification-deltaevents use in Conversations and Document Processing.