# Actions An action applies one transformation to a piece of content and does not keep the change history on the backend. The API is called by the editor’s [Quick Actions](../../../../ckeditor5/latest/features/ai/ckeditor-ai-actions.md) feature. This page describes the contract: the request and the streamed result, the accepted action names, and the scopes a token needs. The endpoints are documented in the [Actions section of the API reference](https://ai.cke-cs.com/v1/docs#tag/Actions). ## Request and response A system action needs only the content: ```http POST /v1/actions/system/fix-grammar/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 result streams back as the model produces it. `action-metadata` arrives first, then the transformed content in `modification-delta` chunks that share an `id`: ``` event: action-metadata data: {"callId":"V1StGXR8_Z5jdHi6B-myT"} event: modification-delta data: {"id":"modf-id-0000000000000","textDelta":"

Chapter 2

The story continues "} event: modification-delta data: {"id":"modf-id-0000000000000","textDelta":"with new developments.

"} ``` The other system actions take the same request with a different name in the path: `improve-writing`, `make-longer`, `make-tone-casual`, and the rest of the table under [Accepted names](#accepted-names). Only `translate` takes an argument, the target language: ```http POST /v1/actions/system/translate/calls Content-Type: application/json Authorization: Bearer { "content": [ { "type": "text", "content": "

Hello, how are you today?

" } ], "args": { "language": "Spanish" } } ``` A custom action takes its own `prompt` and a `model`, and `outputFormat` sets the format of the result: ```http POST /v1/actions/custom/calls Content-Type: application/json Authorization: Bearer { "content": [ { "type": "text", "content": "

The company's Q4 revenue was $2.5M, representing a 15% increase YoY.

" } ], "prompt": "Convert financial abbreviations to full words (e.g., 'YoY' to 'year-over-year', 'Q4' to 'fourth quarter') to make the text more accessible to general audiences.", "model": "agent-1", "outputFormat": "html" } ``` ## Streaming events The response is a Server-Sent Events stream with these events: * `action-metadata` arrives first and carries the `callId`. * `modification-delta` carries the transformed content as markup, in chunks that share an `id`. Every system action sends these, and so does a custom action with `outputFormat: "html"`. * `text-delta` carries text with no markup, and arrives only from a custom action with `outputFormat: "plainText"`. * `error` ends the stream. Actions have no resume endpoint, so retry the call from the start. Some system actions cache their result. If the same user sends the same content to the same action again, the service returns the cached result with `cached: true` on the event 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 join the chunks of one modification. ## Accepted names System actions cover common transformations: grammar fixes, writing improvements, expanding or shortening text, tone changes, and translation. Each system action has a built-in prompt, so the request needs only the content. The `translate` action also takes the target language in `args`. | Action name | What it does | | ------------------------ | ---------------------------------------------------------------- | | `fix-grammar` | Fixes spelling, grammar and punctuation errors in the content. | | `improve-writing` | Improves clarity and flow. | | `continue` | Continues the text from where it stopped. | | `make-longer` | Expands the content with more detail, examples and explanations. | | `make-shorter` | Shortens the content and keeps the essential information. | | `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. | The editor’s command ids are finer than these names. Its `translate-to-*` commands all call the `translate` action, each with its own `args.language`. ### Custom actions A custom action runs your own prompt on the content and streams the result the same way a system action does. It takes a `model`, an `outputFormat`, and a `prompt`. `outputFormat` sets the format of the result. `html` returns the modified content as HTML. `plainText` returns text with no markup, for results such as a title or a summary. ## Contexts Both endpoints accept a `contexts` array. A context holds prompts and reference files you store in your environment, such as a glossary, and the action reads them as part of the call. A system action keeps its built-in prompt, and the context adds to it. A custom action can take its prompt from the context, so `prompt` is optional there. See [Context library](extensions/context-library.md). ## Permissions To run a system action, the token needs `ai:actions:system:`. To run a custom action, it needs `ai:actions:custom` and the scope for the model the request names. A wildcard such as `ai:actions:*` covers both. If the request references a context, the token also needs `ai:contexts:`. See [Actions permissions](permissions.md#actions-permissions) for the full list. ## Next steps * **[REST API](rest-api.md)** lists every endpoint family and the mechanics they share. * **[Streaming protocol](streaming-protocol.md)** covers event ordering and error handling for every streaming endpoint. * **[Permissions](permissions.md)** lists every scope a token can carry. --- Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)