Review options

The Server AI Toolkit execute-tool endpoint accepts a reviewOptions property. Use it to control how tiptapEdit writes reviewable changes instead of directly mutating the document.

import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    document,
    tool: {
      name: 'tiptapEdit',
      input: toolCallInput,
    },
    reviewOptions: {
      mode: 'trackedChanges',
    },
  }),
})

The reviewOptions property takes a ReviewOptions configuration object.

ReviewOptions

• mode? ('disabled' | 'trackedChanges'): Controls whether edits are applied directly or written as tracked changes. Default: 'disabled'
  • 'disabled': The edit is applied directly to the document.
  • 'trackedChanges': The edit is encoded as tracked changes using the Tracked Changes extension so users can accept or reject individual changes.
• trackedChangesOptions? ({ userId?: string, userMetadata?: Record<string, unknown> | null }): Author metadata for the trackedChanges mode. userId identifies the suggestion author. Defaults to the request user when ommitted and, if that is not available, it defaults to 'AI'. userMetadata stores additional author information such as a display name. Defaults to null.
• diffUtilityOptions? (object): Advanced options for reconstructing tracked changes from the before/after document state.
  • simplifyChanges? (boolean, default: true): Simplify nearby changes before tracked changes are generated.
  • ignoreAttributes? (string[], default: ['id', 'data-thread-id', '_hash']): Ignore specific node attributes during diffing.
  • ignoreMarks? (string[], default: ['inlineThread']): Ignore specific marks during diffing.
  • changeMergeDistance? (number | null, default: auto-calculated): Merge nearby changes within this distance. Set to null to disable merging.
  • mode? ('inline' | 'block' | 'smart', default: 'smart'): Diff strategy to use when generating tracked changes.
  • groupInlineChanges? (number, default: 1): Group inline edits that are within this distance.
  • expandBlockChanges? (string[], default: ['listItem']): Node types that should be expanded as block changes.

Typical configurations

Direct edits

Skip review mode and apply edits immediately:

reviewOptions: {
  mode: 'disabled',
}

Tracked changes with AI author metadata

Attach a stable AI identity to the generated suggestions:

reviewOptions: {
  mode: 'trackedChanges',
  trackedChangesOptions: {
    userId: 'ai-assistant',
    userMetadata: {
      name: 'AI Assistant',
    },
  },
}

Tracked changes with custom diff behavior

Tune how edits are grouped and displayed:

reviewOptions: {
  mode: 'trackedChanges',
  diffUtilityOptions: {
    mode: 'block',
    groupInlineChanges: 2,
  },
}