REST API

Server AI Toolkit 为工具和 工作流 都提供 REST API 端点。

Postman 集合

浏览用于 Server AI Toolkit REST API 的

Postman 集合

。

认证

所有请求都必须包含：

Authorization: Bearer <JWT>
X-App-Id: <APP_ID>

请在服务端使用你的 AI 密钥生成 JWT。请在 Server AI Toolkit 设置页面获取你的 App ID 和密钥。

const JWT_TOKEN = jwt.sign(
  {
    experimental_document_server_id: 'your-document-server-id',
    experimental_document_server_management_api_secret:
      'your-document-server-management-api-secret',
  },
  'your-ai-secret-key',
  { expiresIn: '1h' },
)

有关更多信息，请参阅授权指南。

Document Server 凭据

当你希望 Server AI Toolkit 自动获取并保存 Tiptap Cloud 文档时，请在 JWT 声明中包含这些 claims：

experimental_document_server_id
experimental_document_server_management_api_secret

如何提供文档

托管的基础 URL 是：

https://api.tiptap.dev

在下面的示例中，请求形式为 BASE_URL/v3/ai/...。

使用 Tiptap Cloud 文档（推荐） — 在请求体中包含带有 documentId 的 experimental_documentOptions。服务器将自动从 Tiptap Document Server 获取文档、处理文档，并保存回修改。此方式要求你的 JWT 声明中包含 Document Server 凭据（见上文【Document Server 凭据】）。

大多数工具和工作流端点只接受一个文档来源：

document: 内联的 Tiptap JSON
experimental_documentOptions: 一个 Tiptap Cloud 文档引用

experimental_documentOptions 具有以下结构：

documentId (string, required): Tiptap Cloud 文档标识符。
userId? (string | null, optional): 归因于 AI 执行编辑操作的用户标识。
field? (string | null, optional, default: "default"): 当省略或为 null 时，定位文档中的特定协作字段（Y.js XML 片段）。当你的文档在同一个 documentId 下存储多个可编辑字段时——例如标题和正文分开存储——请使用此项。

使用 Tiptap Cloud 文档的示例：

{
  "experimental_documentOptions": {
    "documentId": "your-document-id",
    "userId": "ai-assistant"
  }
}

定位到非默认协作字段的示例：

{
  "experimental_documentOptions": {
    "documentId": "your-document-id",
    "userId": "ai-assistant",
    "field": "title"
  }
}

使用内联文档的示例：

{
  "document": {
    "type": "doc",
    "content": []
  }
}

Threads 需要云端文档

线程和评论端点始终需要 experimental_documentOptions.documentId。

Session 机制

读取端点会返回一个 sessionId，用于记录 AI 所看到的节点哈希和内容哈希。在后续的编辑请求中复用同一个 sessionId，以便服务器能拒绝过期的编辑，而不是覆盖更新过的用户更改。

格式

大多数端点接受一个 format 字段：

"json": 标准 JSON 表示
"shorthand": Tiptap Shorthand，一种用于提示和模型输出的高效 token 格式

proofreader 当前仅支持 shorthand。

工具端点

获取工具定义

POST /v3/ai/toolkit/tools

为 AI 代理返回可用的工具定义。

请求体：

schemaAwarenessData (SchemaAwarenessData, required)
tools? (object, optional): 启用或禁用各个工具
operationMeta? (string | null, optional, default: "")
format? ('json' | 'shorthand', optional, default: 'json')

响应：

tools (array)
- name (string)
- description (string)
- inputSchema (object)

执行一个工具

POST /v3/ai/toolkit/execute-tool

执行一个 Server AI Toolkit 工具，例如 tiptapRead、tiptapEdit、getThreads 或 editThreads。

请求体：

toolName (string, required)
input (unknown, required)
schemaAwarenessData (SchemaAwarenessData, required)
sessionId? (string | null, optional): 复用来自先前读取或工具执行的会话，以启用防止读取过期内容的保护。
format? ('json' | 'shorthand', optional, default: 'json')
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
experimental_commentsOptions? ({ threadData?: Record<string, unknown>, commentData?: Record<string, unknown> }, optional): 附加到在线程相关工具执行期间创建的新线程和评论的元数据。
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output (unknown)
docChanged (boolean)
document (object | null)

工作流端点

获取工作流定义

使用以下任意一个端点：

POST /v3/ai/toolkit/workflows/edit
POST /v3/ai/toolkit/workflows/insert-content
POST /v3/ai/toolkit/workflows/proofreader
POST /v3/ai/toolkit/workflows/threads

请求体：

format? ('json' | 'shorthand', optional, default: 'json'). proofreader 工作流仅接受 'shorthand'。

响应：

systemPrompt (string)
outputSchema (object)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/workflows/edit' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "format": "shorthand"
  }'

保留返回的 sessionId，并在发起匹配的工作流执行请求时一并发送。

为工作流读取文档内容

POST /v3/ai/toolkit/read/read-document

读取文档内容，并返回可供工作流使用的内容。

请求体：

range? ({ from: number, to: number }, optional, default: entire document)
schemaAwarenessData (SchemaAwarenessData, required)
format? ('json' | 'shorthand', optional, default: 'json')
sessionId? (string | null, optional)
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output
- success (boolean)
- content? (unknown)
- error? (string)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/read/read-document' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'

保留返回的 sessionId，并在发起匹配的 insert-content 执行请求时一并发送。

读取当前选择

POST /v3/ai/toolkit/read/read-selection

读取选区内容，并返回要么是一个选区载荷，要么是一个明确的空状态。

请求体：

range ({ from: number, to: number }, required)
schemaAwarenessData (SchemaAwarenessData, required)
format? ('json' | 'shorthand', optional, default: 'json')
sessionId? (string | null, optional)
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output
- 当选区为空时：
  - isEmpty (true)
- 当选区包含内容时：
  - isEmpty (false)
  - content (unknown)
  - nodeHashes (string[])
  - nodeRange ({ from: number, to: number })
  - prompt (string)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/read/read-selection' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "range": { "from": 10, "to": 42 },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id"
    }
  }'

读取线程

POST /v3/ai/toolkit/read/threads

为一个 Tiptap Cloud 文档读取全部线程和评论。

请求体：

schemaAwarenessData (SchemaAwarenessData, 必填)
format ('json' | 'shorthand', 必填)
experimental_documentOptions ({ documentId: string, userId?: string, field?: string | null }, 必填)

响应：

output
- threads? (unknown[])
- error? (string)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/read/threads' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'

执行 insert-content 工作流

POST /v3/ai/toolkit/execute-workflow/insert-content

请求体：

input (unknown, required): 生成的 insert-content 载荷
range? ({ from: number, to: number }, optional)
schemaAwarenessData (SchemaAwarenessData, required)
format? ('json' | 'shorthand', optional, default: 'json')
sessionId? (string | null, optional)
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output
- error? (string)
- range? ({ from: number, to: number })
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/insert-content' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": "This is the replacement content.",
    "range": { "from": 10, "to": 42 },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'

执行 Tiptap Edit 工作流

POST /v3/ai/toolkit/execute-workflow/tiptap-edit

请求体：

input (object, required): Edit workflow operations
schemaAwarenessData (SchemaAwarenessData, required)
format? ('json' | 'shorthand', optional, default: 'json')
sessionId? (string | null, optional)
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output
- operationResults? (array)
- reason? ('validationError' | 'unexpectedError')
- error? (string)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/tiptap-edit' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": [
        {
          "type": "replace",
          "target": "abc123",
          "content": "# Updated heading\n\nUpdated paragraph content."
        }
      ]
    },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "disabled"
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    }
  }'

执行 proofreader 工作流

POST /v3/ai/toolkit/execute-workflow/proofreader

请求体：

input (object, required): Proofreader operations
schemaAwarenessData (SchemaAwarenessData, required)
format ('shorthand', required)
sessionId? (string | null, optional)
chunkSize? (number, optional, default: 32000)
reviewOptions? (ReviewOptions, optional, default: { mode: 'disabled' })
exactly one of:
- document
- experimental_documentOptions

响应：

sessionId (string)
output
- operationResults (array)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/proofreader' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": []
    },
    "format": "shorthand",
    "reviewOptions": {
      "mode": "trackedChanges",
      "trackedChangesOptions": {
        "userId": "ai-assistant"
      }
    },
    "experimental_documentOptions": {
      "documentId": "your-document-id"
    }
  }'

执行 comments 工作流

POST /v3/ai/toolkit/execute-workflow/threads

请求体：

input (object, required): 线程操作
schemaAwarenessData (SchemaAwarenessData, required)
format? ('json' | 'shorthand', optional, default: 'json')
experimental_documentOptions ({ documentId: string, userId?: string, field?: string | null }, required)
experimental_commentsOptions? ({ threadData?: Record<string, unknown>, commentData?: Record<string, unknown> }, optional): 工作流创建的新线程和评论所附加的元数据。

响应：

output
- operations? (array)
- error? (string)
docChanged (boolean)
document (object | null)

示例：

curl --location 'BASE_URL/v3/ai/toolkit/execute-workflow/threads' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'X-App-Id: YOUR_APP_ID' \
  --data '{
    "schemaAwarenessData": { /* 模式感知数据 */ },
    "input": {
      "operations": [
        {
          "type": "createComment",
          "threadId": "thread-123",
          "content": "Please clarify this point."
        }
      ]
    },
    "format": "shorthand",
    "experimental_documentOptions": {
      "documentId": "your-document-id",
      "userId": "ai-assistant"
    },
    "experimental_commentsOptions": {
      "threadData": {
        "source": "ai"
      },
      "commentData": {
        "source": "ai"
      }
    }
  }'

架构感知提示（架构感知提示）

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

返回一个提示，用于描述所请求格式的编辑器架构。

请求体：

schemaAwarenessData（SchemaAwarenessData，必填）
format?（'json' | 'shorthand'，可选）

响应：

prompt（string）

错误处理

该 API 使用标准的 HTTP 错误代码：

400 错误请求：无效的请求体、无效的格式、缺少文档源，或缺少 Document 服务器凭证
401 未授权：缺少或无效的 JWT 或应用程序 ID
404 未找到：未知的端点或工具
422 无法处理的实体：验证失败
429 请求过多：重复请求或触发了速率限制保护
500 内部服务器错误：意外的服务器错误
502 错误网关：无法加载或保存 Tiptap Cloud 文档

Postman 集合

认证

Document Server 凭据

如何提供文档

Threads 需要云端文档

Session 机制

格式

工具端点

获取工具定义

执行一个工具

工作流端点

获取工作流定义

为工作流读取文档内容

读取当前选择

读取线程

执行 insert-content 工作流

执行 Tiptap Edit 工作流

执行 proofreader 工作流

执行 comments 工作流

架构感知提示（架构感知提示）

错误处理

相关页面