Tiptap Docs

Tiptap Edit

Build a general-purpose editing workflow that reads a document, generates edit operations, and applies them on the server.

See the source code on GitHub.

Use this workflow when the AI should rewrite existing content

The Tiptap Edit workflow is the most flexible Server AI Toolkit workflow. Use it for tasks like rewriting paragraphs, inserting new blocks near a target node, or transforming an entire document.

Reuse the same session across read and execute

The read step returns a sessionId. Send that same sessionId with the execute request so the server can reject stale edits when the document changed after the AI read it.

Before starting, set up authentication by following the authorization guide.

1. Read the document from the AI Server

Read the part of the document you want the model to work on. Call:

  • POST /v3/ai/toolkit/read/read-document
import { getAuthHeaders } from '@/lib/server-ai-toolkit/get-auth-headers'

const readResponse = await fetch(`${apiBaseUrl}/toolkit/read/read-document`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
    sessionId,
    format: 'shorthand',
    reviewOptions: {
      mode: 'disabled',
    },
    experimental_documentOptions: {
      documentId,
      userId: 'ai-assistant',
    },
  }),
})

const readResult = await readResponse.json()

2. Generate edit operations

Get the workflow definition from the AI Server and ask the model for structured edit operations.

const workflowResponse = await fetch(`${apiBaseUrl}/toolkit/workflows/edit`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    format: 'shorthand',
  }),
})

const workflow = await workflowResponse.json()

const schemaResponse = await fetch(`${apiBaseUrl}/toolkit/schema-awareness-prompt`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
  }),
})

const { prompt: schemaAwarenessPrompt } = await schemaResponse.json()

const result = streamText({
  model,
  system: `${workflow.systemPrompt}\n\n${schemaAwarenessPrompt}`,
  prompt: JSON.stringify({
    content: readResult.output.content,
    task,
  }),
  output: Output.object({ schema: z.fromJSONSchema(workflow.outputSchema) }),
})

const output = await result.output

3. Execute the edit workflow

Send the generated operations back to the Server AI Toolkit. When you use a Tiptap Cloud document, the server updates the collaborative document automatically. Call:

  • POST /v3/ai/toolkit/execute-workflow/tiptap-edit
const executeResponse = await fetch(`${apiBaseUrl}/toolkit/execute-workflow/tiptap-edit`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
    format: 'shorthand',
    input: output,
    sessionId: readResult.sessionId,
    reviewOptions: {
      mode: 'disabled',
    },
    experimental_documentOptions: {
      documentId,
      userId: 'ai-assistant',
    },
  }),
})

const executeResult = await executeResponse.json()

4. Trigger the workflow from the editor UI

The client should keep the latest sessionId and send it with the next request.

const response = await fetch('/api/server-edit-workflow', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentId,
    schemaAwarenessData: getSchemaAwarenessData(editor),
    task,
    sessionId,
  }),
})

const result: { sessionId: string } = await response.json()
setSessionId(result.sessionId)

Tracked changes

Integrate this workflow with the Tracked Changes extension to show a review UI after the AI edits the document, and allow users to accept and reject changes.

In the request to POST /v3/ai/toolkit/execute-workflow/tiptap-edit, configure the reviewOptions parameter:

reviewOptions: {
  mode: 'trackedChanges',
  trackedChangesOptions: {
    userId: 'ai-assistant',
  },
}

See the AI Toolkit demos for examples on how to integrate Server AI Toolkit workflows with Tracked Changes.

Tracked changes with comments

See the source code on GitHub.

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 extension.

Workflow definition with operationMeta

When fetching the edit workflow definition, pass operationMeta to require each operation to include a meta field. The string you provide describes what should go in the meta field.

const workflowResponse = await fetch(`${apiBaseUrl}/toolkit/workflows/edit`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    format: 'shorthand',
    operationMeta:
      'Specific reason for this edit (what is changing in this exact operation).',
  }),
})

The returned outputSchema now requires a meta field on every operation, and the systemPrompt instructs the AI to fill it.

Execute the workflow with comments

Pass experimental_commentsOptions alongside reviewOptions when executing the workflow:

const executeResponse = await fetch(`${apiBaseUrl}/toolkit/execute-workflow/tiptap-edit`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    schemaAwarenessData,
    format: 'shorthand',
    input: output,
    sessionId: readResult.sessionId,
    reviewOptions: {
      mode: 'trackedChanges',
      trackedChangesOptions: {
        userId: 'ai-assistant',
      },
    },
    experimental_commentsOptions: {
      threadData: { userName: 'Tiptap AI' },
      commentData: { userName: 'Tiptap AI' },
    },
    experimental_documentOptions: {
      documentId,
      userId: 'ai-assistant',
    },
  }),
})

Each non-empty meta field in the 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:

import { CommentsKit } from '@tiptap-pro/extension-comments'
import { TrackedChanges } from '@tiptap-pro/extension-tracked-changes'
import { ServerAiToolkit } from '@tiptap-pro/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 each tracked change and read the AI's justification in the comments sidebar.

End result

The finished demo rewrites the collaborative document entirely on the server:

See the source code on GitHub.

Next steps

PreviouslyProofreader