Install

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

Then, install the open-source Server AI Toolkit package:

npm install @tiptap/server-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 Server AI Toolkit.

To use the Server AI Toolkit API, get the editor context from your Tiptap editor. This JSON object contains the editor schema and other data that the AI server needs to understand valid document content.

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getEditorContext, ServerAiToolkit } from '@tiptap/server-ai-toolkit'

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

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

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

Store the editor context

The editor context returned by getEditorContext is JSON-serializable. You can store it in your database and update it only when your editor extensions or schema change.

Using custom nodes?

If your editor includes custom nodes or marks, configure them with addJsonSchemaAwareness. See the custom nodes guide.

For more details, see the Editor context API reference.

Set up authorization

The Server AI Toolkit is a cloud or on-premises service. Authenticate to access its REST API.

Create a secret in the Tiptap Cloud dashboard. Go to Authentication > Secrets > Add Secret. The dashboard generates an ES256 key pair and shows you the private key once. Store the private key.
Copy your environment ID from the dashboard. Go to Authentication > Environment ID. Use it as the JWT iss claim.
Generate a Tiptap Access Control JWT on your server. See the JWT token guide below.
Use the JWT in API requests. Pass it in the Authorization: Bearer JWT header.

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

Environment variables

Configure the following environment variables:

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id
TIPTAP_PRIVATE_KEY=your-private-key-pem

TIPTAP_CLOUD_AI_API_URL: The base URL for the Server AI Toolkit API.
TIPTAP_ENVIRONMENT_ID: Your environment hash ID from the Tiptap dashboard. Used as the iss claim when signing tokens.
TIPTAP_PRIVATE_KEY: Your ES256 private key (PKCS#8 PEM) from the Tiptap dashboard. Used to sign tokens server-side.

Create a JWT token

The createJwtToken function signs a token for the Server AI Toolkit API. Pass a 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'

/**
 * Signs a JWT for authenticating with the Server AI Toolkit API
 */
export async function createJwtToken(documentId?: string): Promise<string> {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions: { action: string; resource: string }[] = [
    { 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)
}

Get authentication headers

This function returns the authentication headers required for Server AI Toolkit API requests. It is asynchronous because it signs a fresh JWT, so all examples use await getAuthHeaders(...).

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

/**
 * Returns the authentication headers for the Server AI Toolkit API
 */
export async function getAuthHeaders(documentId?: string): Promise<Record<string, string>> {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${await createJwtToken(documentId)}`,
  }
}

Alternative: provide documents directly

If you manage documents in your own storage instead of Tiptap Cloud, omit the documentId option and pass documents directly via the document field in API requests. The token then only needs the AI:Toolkit permission.

Maintaining an existing integration?

The previous App ID and secret (HS256) flow, which sent the App ID in X-App-Id and embedded document server credentials as JWT claims, is documented under Legacy authentication.

Call API endpoints

Once authenticated, call the Server AI Toolkit API endpoints using the getAuthHeaders function:

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,
    },
  }),
})

const tools = await response.json()

For complete API documentation, see the REST API reference.

Next steps

Now that you've set up the Server 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