# Reviews A review reads the whole document you send, applies a system review or your own prompt to it, and returns a suggestion for each element. It is the endpoint behind the editor’s [AI Review](../../../../ckeditor5/latest/features/ai/ckeditor-ai-review.md), and [AI Translate](../../../../ckeditor5/latest/features/ai/ckeditor-ai-translate.md) features. This page is the contract: the request and the streamed result, how suggestions are anchored, the accepted review names, and the scopes a token needs. The endpoints are documented in the [Reviews section of the API reference](https://ai.cke-cs.com/v1/docs#tag/Reviews). ## Request and response Send the whole document as a single `text` part, with a `data-id` on each top-level element: ```http POST /v1/reviews/system/correctness/calls Content-Type: application/json Authorization: Bearer { "content": [ { "type": "text", "content": "

The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.

" } ] } ``` The other system reviews take the same request with a different name in the path: `clarity`, `readability`, `make-tone-casual`, and the rest of the table under [Accepted names](#accepted-names). Only `translate` takes an argument, the target language, as `"args": { "language": "Spanish" }`. A custom review carries its own `prompt` and a `model`, and returns suggestions in the same shape: ```http POST /v1/reviews/custom/calls Content-Type: application/json Authorization: Bearer { "content": [ { "type": "text", "content": "

Our product is really good and customers love it because it has many features.

" } ], "prompt": "Review the text for vague language and generic claims. Suggest specific, concrete alternatives that would make the content more credible and informative.", "model": "agent-1" } ``` Both endpoints accept a `contexts` array, so a review can check the document against a style guide, glossary, or policy stored in a context. The context applies to every element of the document. A custom review may take its prompt from the context, so `prompt` is optional when the request references a context that holds one. See [Context library](extensions/context-library.md) for how to store and reference a context. The response streams one result per element. See [Streaming events](#streaming-events). ## What a review may change A suggestion is HTML, and it replaces one element at a time. How much of the element a review rewrites depends on which one you run. * `correctness`, `clarity`, and `readability` are told to change the text only, and to leave tags, attributes, CSS classes, and structure as they are. * `make-longer`, `make-shorter`, the `make-tone-*` reviews, and `translate` may restructure the content inside the element, such as splitting a paragraph in two. * A custom review does what its prompt asks for. State the limits you want in the prompt. Whichever review runs, a suggestion comes back wrapped in the original element with its `data-id`. The service restores the element and its `data-id` if the model dropped them, and removes any extra elements that come with the suggestion. A review returns a result for every element that carries a `data-id`, either a suggested edit or an `unmodified` mark. It never inserts new elements. ## How results are anchored Every suggestion gives the `data-id` of its element, so you can find that element in your copy of the document. Give each top-level element a unique `data-id` attribute: ```html

The norhtern lights dence across the polar skies.

Dep in the ocean, bioluminiscent creatures glow softly.

``` The review skips an element that has no `data-id`. It still runs on the rest of the document, and no event in the response names the skipped element. ## Streaming events The service sends one event for each element as it reads the document: * `review-metadata` arrives first with the `callId` and `pendingElements`, the number of elements under review. Use it to size a progress bar before the first suggestion arrives. * `review-delta` carries the result for one element: `dataId` names the element, `operation` is `edit` or `unmodified`, and `textDelta` holds the suggested HTML. An `unmodified` event has no `textDelta`. * `error` ends the stream. ``` event: review-metadata data: {"callId":"V1StGXR8_Z5jdHi6B-myT","pendingElements":2} event: review-delta data: {"dataId":"p1","textDelta":"

The northern lights dance across the polar skies.

","operation":"edit"} event: review-delta data: {"dataId":"p2","operation":"unmodified"} ``` Some system reviews cache their results. If the same user runs the same review again on unchanged content, the service returns the stored suggestions with `cached: true` on each and does not call the model. See [Streaming protocol](streaming-protocol.md) for the payload of each event, the order they arrive in, and how to cancel a stream. See [Fragment responses](fragment-responses.md) for how an element-addressed suggestion is applied to your copy of the document. ## Accepted names | Review name | What it does | | ------------------------ | ------------------------------------------------------------------ | | `correctness` | Fixes errors in grammar, spelling, punctuation and capitalization. | | `clarity` | Improves sentence structure, word choice and logical flow. | | `readability` | Improves paragraph structure, transitions, and reading level. | | `make-longer` | Expands the content and keeps the original points. | | `make-shorter` | Shortens the content and keeps the original points. | | `make-tone-casual` | Rewrites the content in a casual tone. | | `make-tone-direct` | Rewrites the content in a direct tone. | | `make-tone-friendly` | Rewrites the content in a friendly tone. | | `make-tone-confident` | Rewrites the content in a confident tone. | | `make-tone-professional` | Rewrites the content in a professional tone. | | `translate` | Translates the content to another language. | These are the path segments the endpoint accepts. The editor names them differently: its `length` and `tone` reviews each cover several of these, and AI Translate runs the `translate` review. A custom review runs your own prompt and returns suggestions in the same per-element shape as a system review. Write one when the check depends on your own rules, such as a style guide, a glossary, or a compliance policy. For example, if your style guide bans marketing adjectives, write a prompt that finds them. ## Permissions The scopes in the token you issue control access: `ai:reviews:system:` for one system review and `ai:reviews:custom` for custom reviews. See [Permissions](permissions.md) for the full list and the wildcard rules. ## Next steps * **[REST API](rest-api.md)** lists every endpoint family and the mechanics they share. * **[Streaming protocol](streaming-protocol.md)** defines the SSE events and how to parse and cancel a stream. * **[Fragment responses](fragment-responses.md)** explains how an element-addressed result is merged into the document. * **[Permissions](permissions.md)** lists the scopes a token needs for each review. --- Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)