---
title: "Use with Tracked Changes"
description: "Display server-side AI edits as tracked changes that users can accept or reject individually."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/agents/tracked-changes"
---

# Use with Tracked Changes

Display server-side AI edits as tracked changes that users can accept or reject individually.

Display server-side AI edits as tracked changes, so your users can review and accept or reject them individually. This integrates the Server AI Toolkit with the [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension.

> **Separate product:**
>
> [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) is a separate Tiptap product from the
> Server AI Toolkit, sold separately. It handles user edits by default and can review AI edits when
> integrated with the Server AI Toolkit.

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

> **Experimental:**
>
> The [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension is currently in Alpha
> phase.

> **Continuation from the AI agent chatbot guide:**
>
> This guide continues the [AI agent chatbot
> guide](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/agents/ai-agent-chatbot.md). Read it first.

## How it works

1. The AI reads the document with `tiptapRead` in `trackedChanges` mode.
2. The AI edits the document with `tiptapEdit` in `trackedChanges` mode.
3. The Server AI Toolkit writes tracked change marks through the Tracked Changes extension instead of directly mutating the document.
4. The client displays the tracked changes with the Tracked Changes extension and lets users accept or reject them.

## Show tracked changes

To display server-side AI edits as tracked changes, configure the `reviewOptions` parameter on the `POST /v3/toolkit/execute-tool` endpoint. Set the review mode to `{mode: 'trackedChanges'}`, when calling both the `tiptapRead` and `tiptapEdit` tools. See the [review options reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md) for all available settings.

### Execute tools with tracked changes

Pass `reviewOptions` when calling `execute-tool`:

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

const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
  }),
})
```

See the [review options reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md) for the full `reviewOptions` shape, including `trackedChangesOptions` and `diffUtilityOptions`.

### Client-side setup

On the client, install and add the `ServerAiToolkit` and `TrackedChanges` extensions.

```tsx
import { useChat } from '@ai-sdk/react'
import { Collaboration } from '@tiptap/extension-collaboration'
import { EditorContent, useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { TrackedChanges, findSuggestions } from '@tiptap-pro/extension-tracked-changes'
import { TiptapCollabProvider } from '@tiptap-pro/provider'
import { ServerAiToolkit, getEditorContext } from '@tiptap/server-ai-toolkit'

export default function Page() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit.configure({ undoRedo: false }),
      Collaboration.configure({ document: doc }),
      TrackedChanges.configure({ enabled: false }),
      ServerAiToolkit,
    ],
  })

  // ... render editor and chat UI
}
```

After the AI edits the document, the changes appear as tracked changes. Users can accept or reject them using the `acceptSuggestion`, `rejectSuggestion`, `acceptAllSuggestions`, and `rejectAllSuggestions` commands from the Tracked Changes extension.

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## Add comments with tracked changes

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

You can make the AI provide a justification for each change. Each justification becomes a comment thread linked to its tracked change, using the [Comments](https://tiptap.dev/docs/comments/getting-started/overview.md) extension.

### API endpoint

When fetching tool definitions, configure the `tiptapEdit` tool so it can include a `meta` field on operations. Then instruct the AI to provide a justification in that `meta` field.

```ts
const response = await fetch(`${apiBaseUrl}/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      tiptapEdit: true,
    },
    operationMeta: 'Brief justification explaining why this change improves the document.',
  }),
})
```

### Execute tools with comments

Pass `experimental_commentsOptions` alongside `reviewOptions` when calling `execute-tool`:

```ts
const result = await fetch(`${apiBaseUrl}/toolkit/execute-tool`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId: 'your-document-id',
      userId: 'ai-assistant',
    },
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
        userMetadata: {
          name: 'AI Assistant',
        },
      },
    },
    experimental_commentsOptions: {
      threadData: { userName: 'Tiptap AI' },
      commentData: { userName: 'Tiptap AI' },
    },
  }),
})
```

Each non-empty `meta` field in the edit operations becomes a comment thread linked to its tracked change. The justification is stored as the thread's first comment content and as `suggestionReason` in the thread data.

### Client-side setup

On the client, add the `CommentsKit` extension with a `TiptapCollabProvider`:

```tsx
import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { ServerAiToolkit } from '@tiptap/server-ai-toolkit'

const editor = useEditor({
  extensions: [
    StarterKit.configure({ undoRedo: false }),
    Collaboration.configure({ document: doc }),
    TrackedChanges.configure({ enabled: false }),
    ServerAiToolkit,
    CommentsKit.configure({
      provider, // Your TiptapCollabProvider instance
    }),
  ],
})
```

Users can review the tracked change and read the AI's justification in the comments sidebar.

> **Interactive demo:** [server ai tracked changes](https://ai-toolkit-demos.vercel.app/server-ai-tracked-changes)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## Next steps

- Learn about all available [tool definitions](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/tools.md)
- Learn more about [review options](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/review-options.md)
- Explore the [REST API reference](https://tiptap.dev/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api.md)
- Learn more about the [Tracked Changes](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md) extension