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

A system action needs only the content:

POST /v1/actions/system/fix-grammar/calls
Content-Type: application/json
Authorization: Bearer <your-token>

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

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":"<h2 data-id=\"new-element\">Chapter 2</h2><p data-id=\"new-element\">The story continues "}

event: modification-delta
data: {"id":"modf-id-0000000000000","textDelta":"with new developments.</p>"}

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. Only translate takes an argument, the target language:

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

{
  "content": [
	{
	  "type": "text",
	  "content": "<p>Hello, how are you today?</p>"
	}
  ],
  "args": {
	"language": "Spanish"
  }
}

A custom action takes its own prompt and a model, and outputFormat sets the format of the result:

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

{
  "content": [
	{
	  "type": "text",
	  "content": "<p>The company's Q4 revenue was $2.5M, representing a 15% increase YoY.</p>"
	}
  ],
  "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"
}

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 for the payload of each event, the order they arrive in, and how to join the chunks of one modification.

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.

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.

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.

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.

To run a system action, the token needs ai:actions:system:<actionName>. 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:<contextId>. See Actions permissions for the full list.

• REST API lists every endpoint family and the mechanics they share.
• Streaming protocol covers event ordering and error handling for every streaming endpoint.
• Permissions lists every scope a token can carry.