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.

const response = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  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. userMetadata stores additional author information such as a display name.
• diffUtilityOptions? (object): Advanced options for reconstructing tracked changes from the before/after document state.
  • simplifyChanges? (boolean): Simplify nearby changes before tracked changes are generated.
  • ignoreAttributes? (string[]): Ignore specific node attributes during diffing.
  • ignoreMarks? (string[]): Ignore specific marks during diffing.
  • changeMergeDistance? (number | null): Merge nearby changes within this distance.
  • mode? ('inline' | 'block' | 'smart'): Diff strategy to use when generating tracked changes.
  • groupInlineChanges? (number): Group inline edits that are within this distance.
  • expandBlockChanges? (string[]): 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,
  },
}