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, and AI Translate 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.

Send the whole document as a single text part, with a data-id on each top-level element:

POST /v1/reviews/system/correctness/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
	{
	  "type": "text",
	  "content": "<p data-id=\"p1\">The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.</p>"
	}
  ]
}

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. 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:

POST /v1/reviews/custom/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
	{
	  "type": "text",
	  "content": "<p data-id=\"p1\">Our product is really good and customers love it because it has many features.</p>"
	}
  ],
  "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 for how to store and reference a context.

The response streams one result per element. See Streaming events.

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.

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:

<p data-id="p1">The norhtern lights dence across the polar skies.</p>
<p data-id="p2">Dep in the ocean, bioluminiscent creatures glow softly.</p>

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.

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":"<p data-id=\"p1\">The northern lights dance across the polar skies.</p>","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 for the payload of each event, the order they arrive in, and how to cancel a stream. See Fragment responses for how an element-addressed suggestion is applied to your copy of the document.

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.

The scopes in the token you issue control access: ai:reviews:system:<review-name> for one system review and ai:reviews:custom for custom reviews. See Permissions for the full list and the wildcard rules.

• REST API lists every endpoint family and the mechanics they share.
• Streaming protocol defines the SSE events and how to parse and cancel a stream.
• Fragment responses explains how an element-addressed result is merged into the document.
• Permissions lists the scopes a token needs for each review.