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}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    schemaAwarenessData,
    document,
    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 'AI' when omitted. userMetadata stores additional author information such as a display name. Defaults to null.
• useDiffUtility? (boolean): Whether to use the diff utility for tracked-changes reconstruction. When true, changes are computed via fine-grained diffing. When false or absent, range-level tracked changes are applied directly.
• 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,
  },
}