Install

First, contact our team to get access to the AI Toolkit.

Then, install the open-source AI Toolkit package:

npm install @tiptap/ai-toolkit

Get editor context

First, install the ServerAiToolkit extension in your editor. This will modify your editor schema so that your documents are compatible with the AI Toolkit.

Start by getting the editor context. This JSON object contains the data that the AI Toolkit needs to know about the Tiptap editor.

// Run this on the client app
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getEditorContext, ServerAiToolkit } from '@tiptap/ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit, ServerAiToolkit],
})

// Get the editor context
const editorContext = getEditorContext(editor)

Pass the editorContext on every request you make to the AI Toolkit.

Set up authorization

The Server AI Toolkit is a cloud or on-premises service. To authenticate:

Create a secret in the Tiptap Cloud dashboard (Authentication → Secrets → Add Secret). Generate an ES256 key pair and copy the private key, which is shown only once. Store it as the TIPTAP_PRIVATE_KEY environment variable.
Copy your environment ID from the dashboard (Authentication → Environment ID). Store it as the TIPTAP_ENVIRONMENT_ID environment variable.
Generate a Tiptap Access Control JWT (see the JWT guide below) and pass it in the Authorization: Bearer JWT header on every request.

Example .env file:

# ES256 private key (PKCS#8 PEM) from the Tiptap dashboard. Used to sign tokens server-side.
TIPTAP_PRIVATE_KEY=your-private-key-pem
# Environment ID from the Tiptap dashboard. Used as the `iss` claim when signing tokens.
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id

# Base URL for the AI Toolkit API.
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev

Create a JWT token

Sign a JWT token for the AI Toolkit API, with these properties:

Issuer: TIPTAP_ENVIRONMENT_ID
Permissions
- { action: 'AI:Toolkit', resource: '*' } to access the AI Toolkit
- { action: 'Documents:Write', resource: 'document-id' } to access a Tiptap Cloud document
Audience: ['AI', 'Documents']

The createJwtToken creates a JWT token for accessing the AI Toolkit. Pass the documentId when the AI Toolkit should read and edit a Tiptap Cloud document.

// lib/server-ai-toolkit/create-jwt-token.ts
import { SignJWT, importPKCS8 } from 'jose'

export async function createJwtToken(documentId?: string) {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions = [{ action: 'AI:Toolkit', resource: '*' }]

  if (documentId) {
    permissions.push({ action: 'Documents:Write', resource: documentId })
  }

  return new SignJWT({ permissions })
    .setProtectedHeader({ alg: 'ES256' })
    .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID!)
    .setAudience(documentId ? ['AI', 'Documents'] : ['AI'])
    .setIssuedAt()
    .setExpirationTime('30m')
    .sign(privateKey)
}

For the full JWT format and signing examples, see the Authentication reference.

Authentication headers

Pass the Authorization: Bearer JWT header to every API request.

The getAuthHeaders function creates the headers:

// lib/server-ai-toolkit/get-auth-headers.ts
import { createJwtToken } from './create-jwt-token'

export async function getAuthHeaders(documentId?: string) {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${await createJwtToken(documentId)}`,
  }
}

Call API endpoints

Call the /fetch-tools API endpoint to get the list of tools:

import { getAuthHeaders } from './lib/server-ai-toolkit/get-auth-headers'

const apiBaseUrl = process.env.TIPTAP_CLOUD_AI_API_URL || 'https://api.tiptap.dev'

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      tiptapRead: true,
      tiptapEdit: true,
    },
  }),
})

Next steps

Now that you've set up the AI Toolkit, start building your AI integration:

AI agent chatbot

Build a conversational AI capable of editing documents and interacting through chat.

PreviouslyOverview

Next upAgents