REST API

The Server AI Toolkit provides REST API endpoints for getting tool definitions and executing tools on Tiptap documents.

Postman collection

Browse the Postman collection for the Server AI Toolkit REST API.

Authentication

All API requests require authentication. Generate a JWT (JSON Web Token) using the secret key from your Tiptap Cloud account. Include this JWT in the Authorization header as a Bearer token, and include your App ID in the X-App-Id header.

Get your App ID and secret key on the Server AI Toolkit settings page.

For production, always create JWTs server-side to keep your secret safe.

--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'X-App-Id: YOUR_APP_ID'

Base URL

In the examples, BASE_URL is the base URL of the Tiptap Cloud AI service. The base URL of the Tiptap Cloud AI service is https://api.tiptap.dev. For on-premises deployments, this URL will be different.

Get tool definitions

Call this endpoint to get the available tool definitions for the Server AI Toolkit.

Endpoint

POST /v3/ai/toolkit/tools

Request

curl --location 'BASE_URL/v3/ai/toolkit/tools' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'X-App-Id: YOUR_APP_ID' \
--data '{
    "schemaAwarenessData": { /* schema awareness data from getSchemaAwarenessData */ },
    "tools": {
      "tiptapRead": true,
      "tiptapEdit": true
    },
    "format": "json"
}'

Request body

schemaAwarenessData (SchemaAwarenessData, required): The schema awareness data obtained from getSchemaAwarenessData. This data describes the document structure for the Server AI Toolkit API.
tools? (EnabledTools, optional): Configuration for enabling/disabling specific tools. Each property can be set to true (enabled) or false (disabled). If not provided, all tools are enabled by default.
- tiptapRead? (boolean, optional): Enable/disable the tiptapRead tool (default: true)
- tiptapEdit? (boolean, optional): Enable/disable the tiptapEdit tool (default: true)
format? (string, optional): The format in which the AI reads and edits the document. Must be one of:
- "json" (default): Standard JSON format
- "shorthand": Tiptap Shorthand format, which reduces AI token costs by up to 80% compared to standard JSON

Response

Returns an object containing an array of tool definitions:

tools (array): An array of tool definitions. Each tool definition includes:
- name (string): The name of the tool (e.g., "tiptapRead", "tiptapEdit")
- description (string): A description of what the tool does
- inputSchema (object): The JSON schema for the tool's input parameters

Example response

{
  "tools": [
    {
      "name": "tiptapRead",
      "description": "Tool description",
      "inputSchema": {
        /* JSON schema for tool input */
      }
    },
    {
      "name": "tiptapEdit",
      "description": "Tool description",
      "inputSchema": {
        /* JSON schema for tool input */
      }
    }
  ]
}

Execute a tool

Call this endpoint to execute a tool on a Tiptap document.

Endpoint

POST /v3/ai/toolkit/execute-tool

Request

curl --location 'BASE_URL/v3/ai/toolkit/execute-tool' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'X-App-Id: YOUR_APP_ID' \
--data '{
    "toolName": "tiptapRead",
    "input": { /* tool input */ },
    "document": { /* Tiptap JSON document */ },
    "schemaAwarenessData": { /* schema awareness data from getSchemaAwarenessData */ },
    "chunkSize": 1000,
    "format": "json"
}'

Request body

toolName (string, required): The name of the tool to execute. Must be one of:
- "tiptapRead": Read part of the document using an efficient format
- "tiptapEdit": Edit the document using an efficient format
input (any, required): The input parameters for the tool, as defined by the tool's input schema. The input format is optimized for efficient reading and editing operations.
document (object, required): The Tiptap JSON document to operate on
schemaAwarenessData (SchemaAwarenessData, required): The schema awareness data obtained from getSchemaAwarenessData
chunkSize? (number, optional): The chunk size for reading operations. Default: 1000
format? (string, optional): The format in which the AI reads and edits the document. Must be one of:
- "json" (default): Standard JSON format
- "shorthand": Tiptap Shorthand format, which reduces AI token costs by up to 80% compared to standard JSON

Response

Returns the result of the tool execution:

output (any): The output of the tool execution. The output format is optimized for efficient reading and editing operations.
hasError (boolean): Whether an error occurred during execution
docChanged (boolean): Whether the document was modified
document (object | null): The updated Tiptap JSON document. Returns null if the document was not modified, or the updated document if docChanged is true

Get schema awareness prompt

Call this endpoint to get a prompt string that describes the document schema for use with AI models.

Endpoint

POST /v3/ai/toolkit/schema-awareness-prompt

Request

curl --location 'BASE_URL/v3/ai/toolkit/schema-awareness-prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--header 'X-App-Id: YOUR_APP_ID' \
--data '{
    "schemaAwarenessData": { /* schema awareness data from getSchemaAwarenessData */ },
    "format": "json"
}'

Request body

schemaAwarenessData (SchemaAwarenessData, required): The schema awareness data obtained from getSchemaAwarenessData. This data describes the document structure for the Server AI Toolkit API.
format? (string, optional): The format in which the AI reads and edits the document. Must be one of:
- "json" (default): Standard JSON format
- "shorthand": Tiptap Shorthand format, which reduces AI token costs by up to 80% compared to standard JSON

Response

Returns a prompt string that describes the document schema:

prompt (string): A text prompt that describes the document schema structure, suitable for inclusion in AI model prompts

Example response

{
  "prompt": "Schema Awareness prompt"
}

Error handling

If an error occurs, the API will return an error response with an appropriate HTTP status code:

400 Bad Request: Invalid request body or parameters
401 Unauthorized: Missing or invalid JWT token or App ID
404 Not Found: Tool not found
500 Internal Server Error: Server error during tool execution

PreviouslySchema awareness

Next upAdvanced guides