First, [contact our team](/content/contact-sales?form=server-ai-toolkit/index.html) to get access to the Server AI Toolkit.

After getting access, configure your package manager by following the [private registry guide](/content/docs/guides/pro-extensions/index.html).

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](/content/docs/content-ai/capabilities/server-ai-toolkit/advanced-guides/custom-nodes/index.html).

For more details, see the [Schema awareness API reference](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/schema-awareness/index.html).

## Set up authorization

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

1. **Get your App ID and secret key** on the [Tiptap Cloud AI settings](https://cloud.tiptap.dev/v2/cloud/ai) page.
2. **Get your Document Server credentials** (ID and management API secret) on the [Document Server settings](https://cloud.tiptap.dev/v2/configuration/document-server) page. These are included as JWT claims so the Server AI Toolkit can automatically fetch and save your Tiptap Cloud documents.
3. **Generate a JWT** using a library like `jsonwebtoken`. In production, always create JWTs **server-side** to keep your secret safe.
4. **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](https://cloud.tiptap.dev/v2/cloud/ai) page. Used to sign the JWT.
- **TIPTAP_CLOUD_AI_APP_ID**: Your "Content AI App ID" from the [Content AI settings](https://cloud.tiptap.dev/v2/cloud/ai) page.
- **TIPTAP_CLOUD_DOCUMENT_SERVER_ID**: Your Tiptap Cloud Document Server ID from the [Document Server settings](https://cloud.tiptap.dev/v2/configuration/document-server) 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.

```typescript
// 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.

```typescript
// 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](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api/index.html).

## 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](/content/docs/content-ai/capabilities/server-ai-toolkit/api-reference/rest-api/index.html).

## Next steps

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

[**AI agent chatbot** More → Build a conversational AI capable of editing documents and interacting through chat.](/content/docs/content-ai/capabilities/server-ai-toolkit/agents/ai-agent-chatbot/index.html)

[Previously Overview](/content/docs/content-ai/capabilities/server-ai-toolkit/overview/index.html)

[Next up Agents](/content/docs/content-ai/capabilities/server-ai-toolkit/agents/index.html)

Trusted by Axios, PostHog, Beehiiv, GitLab and more.