REST API

The Server AI Toolkit REST API contains endpoints for getting the available tools and executing tool calls

Base URL

The Tiptap Cloud base URL is:

BASE_URL=https://api.tiptap.dev

In on-premises deployments, the base URL may differ.

In the examples below, requests are written as BASE_URL/v4/ai/toolkit/....

Authentication

All requests must include this authentication header:

• Authorization: Bearer JWT, where JWT is a Tiptap Access Control JWT.

Sign the token server-side with these settings:

• Audience: AI
• Permissions: AI:Toolkit

To fetch and save Tiptap Cloud documents automatically, add the Documents audience and the Documents:Write permission. Documents:Write includes read and comment access.

See Authentication for how to create a key pair and sign tokens, and the authorization guide for the full setup.

import { SignJWT, importPKCS8 } from 'jose'

const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY, 'ES256')

const JWT_TOKEN = await new SignJWT({
  permissions: [
    { action: 'AI:Toolkit', resource: '*' },
    { action: 'Documents:Write', resource: 'your-document-id' },
  ],
})
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID)
  .setAudience(['AI', 'Documents'])
  .setExpirationTime('30m')
  .sign(privateKey)

The previous App ID + secret authentication flow is documented under Legacy authentication.

Optional fields

Optional fields can be omitted, null, or undefined.

Endpoints

Fetch tool definitions

POST /v4/ai/toolkit/fetch-tools

Returns the prompt and tool definitions that you pass to your AI provider.

Request body:

• editorContext (object, required): The editor context returned by getEditorContext.
• tools (Record<string, boolean | ToolConfig>, optional, default: {}): Enables, disables, or configures tools. Tools are disabled by default.
• format ('json' | 'shorthand', optional, default: 'json'): Document format used by tool definitions and model output. See Tiptap Shorthand.

tools can contain these keys:

• tiptapRead (boolean, optional)
• tiptapEdit (boolean | { meta?: string }, optional): Set meta when you want the AI to include an extra metadata field on every edit operation, such as a short explanation.
• getThreads (boolean, optional)
• editThreads (boolean, optional)
• readDocument (boolean, optional)
• proofread (boolean | { meta?: string }, optional): Set meta when you want the AI to include an extra metadata field on every proofreading edit, such as a short explanation.

Response:

• systemPrompt (string): Add this to the system prompt for your AI request. It teaches the AI how Tiptap documents work, what elements the editor supports, and which document format to use.
• tools (array): Tool definitions the AI or developer can call. Each array element contains:
  • name (string): Tool name.
  • description (string): Tool description.
  • inputSchema (object): JSON schema for the AI-generated tool input.

Example:

curl --location 'BASE_URL/v4/ai/toolkit/fetch-tools' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "editorContext": { /* editor context data */ },
    "tools": {
      "tiptapRead": true,
      "tiptapEdit": {
        "meta": "Briefly explain the edit."
      }
    },
    "format": "shorthand"
  }'

Execute a tool

POST /v4/ai/toolkit/execute-tool

Executes a tool. Use this endpoint after the AI model has generated the tool call.

Request body:

• editorContext (object, required): The editor context returned by getEditorContext.
• document (object, required): Document to execute the tool against. Use { "type": "cloud", "id": "your-document-id" } when the API should read from and write to a Tiptap Cloud document. Use { "type": "inline", "content": { /* Tiptap JSON document */ } } when you want to provide the Tiptap JSON document in the request body.
• user (string, optional): Identifier attributed to edits the AI performs.
• field (string, optional, default: "default"): Collaborative field to target inside a cloud document. Use this when a document stores multiple editable fields, such as a title and body.
• tool (object, required): Tool call to execute.
  • name (string, required): Tool name, for example "tiptapRead".
  • input (object, required): Tool input generated by the AI. This is an object that matches the schema and the tool definition for that tool. The schemas and tool definitions of each tool are obtained from the /v4/ai/toolkit/fetch-tools endpoint.
  • config (unknown, optional): Tool-specific configuration provided by the developer.
• format ('json' | 'shorthand', optional, default: 'json'): Document format for tool input and output. See Tiptap Shorthand.
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): Controls whether edits are applied directly or as reviewable changes.

Response:

• tool (object): Executed tool and its output.
  • name (string): Tool name.
  • output (object): Tool output for the AI.
• docChanged (boolean): Whether the document changed.
• document (object | null): Updated document, or null when the document did not change.

Example:

curl --location 'BASE_URL/v4/ai/toolkit/execute-tool' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "editorContext": { /* editor context data */ },
    "document": {
      "type": "cloud",
      "id": "your-document-id"
    },
    "user": "ai-assistant",
    "tool": {
      "name": "tiptapRead",
      "input": {
        "from": 0
      }
    },
    "format": "shorthand"
  }'

Stream a tool

POST /v4/ai/toolkit/stream-tool

Streams tool execution. tiptapEdit can apply edits incrementally for a typing effect. Other tools run after the full input is received and return one final event, like execute-tool.

The request is sent in parts. The first part contains:

• editorContext (object, required): The editor context returned by getEditorContext.
• document (object, required): Cloud document to execute the tool against: { "type": "cloud", "id": "your-document-id" }. Inline documents are not supported for streaming.
• user (string, optional): Identifier attributed to edits the AI performs.
• field (string, optional, default: "default"): Collaborative field to target inside a cloud document.
• tool (object, required): Tool call to execute, without tool.input.
  • name (string, required): Tool name, for example "tiptapEdit".
  • config (unknown, optional): Tool-specific configuration provided by the developer.
• format ('json' | 'shorthand', optional, default: 'json'): Document format for tool input and output. See Tiptap Shorthand.
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): Controls whether edits are applied directly or as reviewable changes.
• delayMs (number, optional, default: 5): Per-character delay in milliseconds for incremental tiptapEdit output. Must be between 0 and 1000. Use 0 to apply edits as fast as possible.

Then send:

• Following parts: The value of tool.input, streamed as the AI generates it.

Response:

• tiptapEdit: Incremental events while edits are applied, followed by a final event with the updated document.
• Other tools: One final event with the same result shape as execute-tool.

Available tools

These tools can be provided to an AI agent. The agent decides which tool to call.

All tools are disabled by default. We recommend starting with tiptapRead and tiptapEdit, then enabling additional tools as needed.

You can also call these tools directly from your application code to build custom workflows.

tiptapRead

Reads the document in chunks to avoid overflowing the context window.

Tool config (tool.config):

• chunkSize (number, optional): Maximum number of characters to read in each tool call. Default: 32000

Tool output (tool.output):

Success response:

• success (true): Indicates that the read request was successful.
• totalNodeCount (number): Total number of top-level nodes in the document.
• nodeRange ([number, number]): Top-level node range that was read.
• content (JSONContent[] | string): Document content for the returned range. When format is json, this is a Tiptap JSON fragment. When format is shorthand, this is a Tiptap Shorthand string.

Error response:

• success (false): Indicates that the read request failed.
• error (string): Error message.
• totalNodeCount? (number): Total number of top-level nodes.

tiptapEdit

Edits document content.

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Whether all operations completed successfully.
• operationResults (array): Result for each operation.
  • success (boolean): Whether the operation completed successfully.
  • target (string): String identifier of the element targeted by the operation.
  • error (string | null): Failure reason, or null if the operation succeeded.

Error response:

• success (false): Indicates that the edit request failed.
• reason ('validationError' | 'unexpectedError'): Error category.
• error (string): Error message.

getThreads

Reads comment threads from a cloud document.

Tool config (tool.config):

• chunkSize (number, optional): Maximum number of characters to read in each tool call. Default: 32000

Tool output (tool.output):

Success response:

• success (true): Indicates that the read request was successful.
• totalThreadCount (number): Total number of threads in the document.
• threadRange ([number, number]): Thread range that was read, as [from, to).
• threads (array): Returned thread objects.
  • id (string): Unique thread identifier.
  • nodeRange ([number, number] | null): Node range where the thread is located, or null if the thread is not annotated in the document.
  • content (JSONContent[] | string | null): Content marked by the thread. When format is json, this is a Tiptap JSON fragment. When format is shorthand, this is a Tiptap Shorthand string. null means the thread is not annotated in the document.
  • comments (array): Comments in the thread.
    • id (string): Unique comment identifier.
    • content (string): Comment text.
    • userId (string): ID of the user who created the comment.
    • createdAt (string): ISO timestamp when the comment was created.
    • updatedAt (string): ISO timestamp when the comment was last updated.
  • resolvedAt? (string | null): ISO timestamp when the thread was resolved, or null if unresolved.
  • createdAt (string): ISO timestamp when the thread was created.
  • updatedAt (string): ISO timestamp when the thread was last updated.
  • data? (Record<string, unknown>): Public thread metadata.

Error response:

• success (false): Indicates that the read request failed.
• error (string): Error message.
• totalThreadCount? (number): Total number of persisted threads, when known.

editThreads

Creates and updates comment threads.

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Indicates whether all operations completed successfully.
• operations (array): Result for each operation.
  • type (string): Operation type that was executed.
  • success (boolean): Whether the operation completed successfully.
  • message (string): Human-readable operation result.
  • threadId? (string): Thread ID for operations that create or reference a thread.

Error response:

• success (false): Indicates that the request failed before operations were processed.
• error (string): Error message.

readDocument

Reads the entire document.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that the document was read successfully.
• content (JSONContent[] | string): Whole effective document content. When format is json, this is a Tiptap JSON fragment. When format is shorthand, this is a Tiptap Shorthand string.

proofread

Applies proofreading edits.

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Indicates whether all operations completed successfully.
• operationResults (array): Result for each operation.
  • target (string): String identifier of the element targeted by the operation.
  • success (boolean): Whether the operation completed successfully.
  • error (string | null): Failure reason, or null when the operation succeeded.

Related pages

• Review options
• Editor context