A Tiptap schema describes the elements the document can (and cannot) contain. Tiptap's schema awareness capabilities allow AI models to understand the document better.

Why schema awareness?

Without schema awareness, the AI model might generate content that the Tiptap editor does not support. For example, it might generate a table in a document that does not support tables. With schema awareness enabled, the AI model will know that table nodes are not supported and will refuse to generate them.

Guide: give schema awareness to your AI model

Integrate the schema awareness feature to an AI agent like the one built in the AI agent chatbot guide.

Step 1: get the schema awareness string

Get the schema awareness string from the AI Toolkit. This string contains a message describing the document's schema, that is optimized for the AI model.

const toolkit = getAiToolkit(editor)
// Retrieve the schema awareness string
const schemaAwareness = toolkit.getHtmlSchemaAwareness()

Step 2 (optional): configure custom nodes

If your document contains custom Nodes and Marks, add the addHtmlSchemaAwareness option to the extension configuration. This way, the AI model will be able to generate this custom Node or Mark accurately. For example, if you have a custom node called 'alert', you can allow the AI model to generate it by configuring it like this:

import { Node } from '@tiptap/core'

const CustomExtension = Node.configure({
  name: 'alert',

addHtmlSchemaAwareness() {
    return {
      tag: 'div',
      name: 'Alert Box',
      description: `A highlighted box used to display important information, warnings, or tips to the user.\nIt can have inline content inside like text and formatting tags.`,
      attributes: [
        {
          attr: 'data-alert',
          value: '',
          description: 'Indicates that this is an alert box',
        },
        {
          attr: 'data-type',
          description:
            'The type of alert. Can be one of these 4 values: info, warning, error, or success',
        },
      ],
    }
  },

// ... Other extension configuration options
})

Alternatively, you can configure the customNodes option of the getHtmlSchemaAwareness method. Learn more about the configuration options in the API Reference.

What about official Tiptap extensions?

Schema awareness for official Tiptap extensions is automatically supported by the AI Toolkit. They do not need to be configured. You can still override the default schema awareness information for official Tiptap extensions by extending the extension and adding the addHtmlSchemaAwareness option.

Step 3: add the schema awareness string to the system prompt

When you call the AI model, send the schema awareness string as a parameter to the API endpoint that returns the AI model response.

The code below shows an API endpoint built with Next.js and the Vercel AI SDK, like the one in the AI agent chatbot guide.

// app/page.tsx
import { useEditor } from '@tiptap/react'
import { getAiToolkit } from '@tiptap-pro/ai-toolkit'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'

// Inside the React component

const editor = useEditor()
const toolkit = getAiToolkit(editor)

// Get the schema awareness string
const schemaAwareness = toolkit.getHtmlSchemaAwareness()

const { messages } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
    // Send the schema awareness string as a parameter to the API endpoint
    body: { schemaAwareness },
  }),
  // ...
})

Then, inside the API endpoint handler, add the schema awareness string to the end of the system prompt.

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai'
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'
import { createAgentUIStreamResponse, ToolLoopAgent, UIMessage } from 'ai'

export async function POST(req: Request) {
  // Get the schema awareness string from the request body
  const { messages, schemaAwareness }: { messages: UIMessage[]; schemaAwareness: string } =
    await req.json()

const agent = new ToolLoopAgent({
    model: openai('gpt-5.4-mini'),
    // Add the schema awareness string to end of the system prompt
    instructions: `You are an assistant that can edit rich text documents.\n${schemaAwareness}`,
    tools: toolDefinitions(),
  })

return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
  })
}

You've now set up schema awareness for your AI model.

End result

The app below is a variant of the AI agent chatbot demo with schema awareness configured. Try asking the AI to create an alert box: the AI will recognize the custom element and insert it into the document.

User Authentication API

This API endpoint handles user authentication and returns a JWT token for authorized access to protected resources.

Endpoint

POST /api/auth/login

Request Body

The request must include the following parameters:

  • email (string, required): User's email address

  • password (string, required): User's password

  • remember_me (boolean, optional): Keep user logged in for extended period

Response

On successful authentication, the API returns a JSON object with the following structure:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "email": "user@example.com",
    "name": "John Doe"
  },
  "expires_in": 3600
}

Error Handling

The API may return the following error responses:

  • 400 Bad Request: Missing required parameters

  • 401 Unauthorized: Invalid credentials

  • 429 Too Many Requests: Rate limit exceeded

  • 500 Internal Server Error: Server-side error

Rate Limiting

This endpoint is rate-limited to 5 requests per minute per IP address to prevent brute force attacks.

Security Considerations

Always use HTTPS when calling this endpoint. Store the returned JWT token securely and include it in the Authorization header for subsequent API calls.