AI Actions

An AI Action is an entity that can be used to specify a configurable instruction that is later processed by a Language Learning Model (LLM). AI Actions are space-scoped, whereas invoking an AI Action takes place in the context of an entire environment.

AI Action configuration

Variables

Variables are configuration parameters for AI Actions that accept dynamic input when the action is executed. Each AI Action can define multiple variables of different types.

Model configuration

AI Actions can be configured with different language models and parameters that affect the model’s behavior.

Available models

Temperature Configuration

The temperature parameter controls the randomness and creativity of AI-generated outputs:

When creating or updating an AI Action, these configuration options can be specified in the request body.

AI Actions collection

Get all AI actions

Returns all the AI Actions that exist in a given space.

Create an AI action

Use this endpoint to create a new AI Action for a specified space.

Query AI Actions

To query AI Actions, use the Get all AI actions endpoint. This endpoint allows to query AI Actions with certain filters. The filters are defined as query parameters which are described in the endpoint specifications.

AI Action

Get an AI action

Use this endpoint to read an AI Action for a specified space.

Update AI Action

Use this endpoint to update an AI Action for a specified space.

Delete AI Action

Use this endpoint to delete an AI Action for a specified space.

Publish AI Action

Publish an AI action

Use this endpoint to publish an AI Action for a specified space.

Unpublish an AI action

Use this endpoint to unpublish an AI Action for a specified space.

Invoke AI Action

Invoke an AI action

Use this endpoint to invoke an AI Action for a specified space and environment.

Reading result of AI Action Invocation

Get an AI action invocation

Use this endpoint to obtain the result of an AI Action Invocation for a specified space, environment, AI Action and Invocation.

AI Suggestions

AI Suggestions are entry-scoped AI Actions that analyze content and return recommendations for users to review and apply. Running a suggestion does not modify the entry.

AI Suggestions use the same creation, publication, and invocation endpoints as other AI Actions. Set the following properties in the action’s configuration:

Create and publish an AI Suggestion

Use Create an AI action with scope: "Entry" and outputType: "Suggestion". Include a StandardInput variable for the entry fields to analyze. The following example also defines a text variable for terms to preserve:

const payload = {
  name: 'Fix spelling & grammar',
  description: 'Review content for spelling and grammar errors.',
  instruction: {
    template: 'Check the content for spelling and grammar errors. Preserve these terms: {{var.zuoYgmKjmlU0}}. Content to check: {{var.8igfdwv6dy8y}}',
    variables: [
      {
        id: 'zuoYgmKjmlU0',
        name: 'Terms to preserve',
        description: 'Words or terms to leave unchanged.',
        type: 'Text',
      },
      {
        id: '8igfdwv6dy8y',
        type: 'StandardInput',
      },
    ],
  },
  configuration: {
    modelTemperature: 0.1,
    modelType: 'anthropic.claude-sonnet-4-6',
    scope: 'Entry',
    outputType: 'Suggestion',
  },
  testCases: [],
};

Choose a model available to your space. Create the action using this payload, then publish it before invoking it:

import { createClient } from 'contentful-management';
const client = createClient({ accessToken: '<cma_token>' });
const suggestion = await client.aiAction.create({ spaceId: '<space_id>' }, payload);
await client.aiAction.publish({
  spaceId: '<space_id>',
  aiActionId: suggestion.sys.id,
  version: suggestion.sys.version,
});

Invoke an AI Suggestion

Use Invoke an AI action and set outputFormat to Suggestion. Variable IDs must match the action definition. The StandardInput value must identify an entry and include a non-empty entityPaths array for the fields and locales to analyze:

const invocationPayload = {
  outputFormat: 'Suggestion',
  variables: [
    {
      id: 'zuoYgmKjmlU0',
      value: 'Contentful',
    },
    {
      id: '8igfdwv6dy8y',
      value: {
        entityId: '<entry_id>',
        entityType: 'Entry',
        entityPaths: ['fields.title.en-US', 'fields.description.en-US'],
      },
    },
  ],
};

const invocation = await client.aiAction.invoke({
  spaceId: '<space_id>',
  environmentId: '<environment_id>',
  aiActionId: suggestion.sys.id,
}, invocationPayload);

The endpoint returns 201 with an invocation ID and status. Generation completes asynchronously.

Read the suggestions

Poll Get an AI action invocation using the returned invocation ID. When sys.status is COMPLETED, read result.content. Handle failed invocations separately.

const currentInvocation = await client.aiActionInvocation.get({
  spaceId: '<space_id>',
  environmentId: '<environment_id>',
  aiActionId: suggestion.sys.id,
  invocationId: invocation.sys.id,
});

result is a top-level property of the invocation response. Once the invocation completes, currentInvocation.result.content is an array containing Markdown and suggestion blocks, for example:

[
  {
    "type": "MarkdownBlock",
    "text": "One spelling correction is suggested."
  },
  {
    "type": "SuggestionBlock",
    "format": "Text",
    "fieldId": "title",
    "original": "Welcomme to Contentful",
    "suggested": "Welcome to Contentful",
    "reason": "Correct the spelling of Welcome.",
    "confidence": 1
  }
]

A MarkdownBlock contains explanatory Markdown. A SuggestionBlock identifies the field with fieldId, the original text, its suggested replacement, a numeric confidence, and an optional reason. A successful run can contain only Markdown blocks when no changes are suggested. Present the recommendations for review before applying changes to the entry.