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.

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
const readResponse = await fetch(`${apiBaseUrl}/toolkit/read/read-document`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  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: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  body: JSON.stringify({
    format: 'shorthand',
  }),
})

const workflow = await workflowResponse.json()

const schemaResponse = await fetch(`${apiBaseUrl}/toolkit/schema-awareness-prompt`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  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: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwtToken}`,
    'X-App-Id': appId,
  },
  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

To run the Tiptap Edit workflow with tracked changes, keep the same setup and change the execute request to use tracked changes instead of direct edits:

In the POST /v3/ai/toolkit/execute-workflow/tiptap-edit request shown in step 3, replace this:

reviewOptions: {
  mode: 'disabled',
}

with this:

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

Then render tracked-changes controls in the editor so users can review and accept or reject the AI changes:

editor.commands.acceptAllSuggestions()
editor.commands.rejectAllSuggestions()

End result

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

See the source code on GitHub.

Next steps

PreviouslyProofreader