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.

Get your App ID and secret key on the Tiptap Cloud AI settings page.
Get your Document Server credentials (ID and management API secret) on the Document Server settings page. These are included as JWT claims so the Server AI Toolkit can automatically fetch and save your Tiptap Cloud documents.
Generate a JWT using a library like jsonwebtoken. In production, always create JWTs server-side to keep your secret safe.
Use the JWT in your API requests. Pass it in the Authorization header as a Bearer token and the App ID in X-App-Id.

Environment variables

Configure the following environment variables:

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_CLOUD_AI_SECRET=your-secret-key
TIPTAP_CLOUD_AI_APP_ID=your-app-id
TIPTAP_CLOUD_DOCUMENT_SERVER_ID=your-tiptap-cloud-document-server-id
TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET=your-tiptap-cloud-document-management-api-secret

TIPTAP_CLOUD_AI_API_URL: The base URL for the Server AI Toolkit API.
TIPTAP_CLOUD_AI_SECRET: Your "Content AI Secret" from the Content AI settings page. Used to sign the JWT.
TIPTAP_CLOUD_AI_APP_ID: Your "Content AI App ID" from the Content AI settings page.
TIPTAP_CLOUD_DOCUMENT_SERVER_ID: Your Tiptap Cloud Document Server ID from the Document Server settings page. Included as the experimental_document_server_id JWT claim so the Server AI Toolkit can fetch and save documents automatically.
TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET: Your Document Server management API secret. Included as the experimental_document_server_management_api_secret JWT claim for document access.

Create a JWT token

This function generates a JWT from TIPTAP_CLOUD_AI_SECRET for authenticating with the Server AI Toolkit API. It includes Document Server credentials so the Server AI Toolkit can automatically fetch and save your Tiptap Cloud documents.

// lib/server-ai-toolkit/create-jwt-token.ts
import jwt from 'jsonwebtoken'

/**
 * Generates a JWT from TIPTAP_CLOUD_AI_SECRET for authenticating with the Server AI Toolkit API
 */
export function createJwtToken(): string {
  return jwt.sign(
    {
      // Document Server credentials for automatic document fetching/saving
      experimental_document_server_id: process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_ID,
      experimental_document_server_management_api_secret:
        process.env.TIPTAP_CLOUD_DOCUMENT_SERVER_MANAGEMENT_API_SECRET,
    },
    process.env.TIPTAP_CLOUD_AI_SECRET,
    { expiresIn: '1h' },
  )
}

Get authentication headers

This function returns the authentication headers required for all Server AI Toolkit API requests.

// 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 function getAuthHeaders(): Record<string, string> {
  return {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${createJwtToken()}`,
    'X-App-Id': process.env.TIPTAP_CLOUD_AI_APP_ID,
  }
}

Alternative: provide documents directly

If you manage documents in your own storage instead of Tiptap Cloud, you can omit the experimental_document_server_id and experimental_document_server_management_api_secret JWT claims and pass documents directly via the document field in API requests. See the REST API reference.

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}/v3/ai/toolkit/tools`, {
  method: 'POST',
  headers: getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
  }),
})

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