Install

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

After getting access, configure your package manager by following the private registry guide.

Then, install the package:

npm install @tiptap-pro/server-ai-toolkit

Get schema awareness data

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, you need to get schema awareness data from your Tiptap editor. This data describes the document structure and helps the AI understand what content is valid.

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

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

// Get schema awareness data from the editor
const schemaAwarenessData = getSchemaAwarenessData(editor)

The getSchemaAwarenessData function returns schema awareness data that describes the document structure for the Server AI Toolkit API.

Store the schema awareness data

The schema awareness data returned by getSchemaAwarenessData is a JSON-serializable object that you can store in your database. You don't need to generate it every time—only update it 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 Schema awareness 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({
    schemaAwarenessData,
  }),
})

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