REST API

Server AI Toolkit REST API 包含用于获取可用工具和执行工具调用的端点

如何提供文档

Tiptap Cloud 的基础 URL 为：

BASE_URL=https://api.tiptap.dev

在本地部署中，基础 URL 可能会有所不同。

在下面的示例中，请求写作 BASE_URL/v4/ai/toolkit/...。

身份验证

所有请求都必须包含以下身份验证头：

• Authorization: Bearer JWT，其中 JWT 是一个 Tiptap 访问控制 JWT。

请使用以下设置在服务器端签名令牌：

• Audience: AI
• Permissions: AI:Toolkit

要自动获取并保存 Tiptap Cloud 文档，请添加 Documents audience 和 Documents:Write permission。Documents:Write 包含读和评论访问权限。

有关如何创建密钥对并签名令牌，请参阅 Authentication；完整设置请参阅 authorization guide。

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)

之前的 App ID + secret 身份验证流程记录在 Legacy authentication 中。

可选字段

可选字段可以省略、null 或 undefined。

端点

获取工具定义

POST /v4/ai/toolkit/fetch-tools

返回你传递给 AI 提供商的提示词和工具定义。

请求体：

• editorContext (object, required): 由 getEditorContext 返回的编辑器上下文。
• tools (Record<string, boolean | ToolConfig>, optional, default: {}): 启用、禁用或 配置工具。默认情况下工具是禁用的。
• format ('json' | 'shorthand', optional, default: 'json'): 工具 定义和模型输出使用的文档格式。参见 Tiptap Shorthand。

tools 可以包含以下键：

• tiptapRead (boolean, optional)
• tiptapEdit (boolean | { meta?: string }, optional): 当你希望 AI 在每次编辑操作中 包含一个额外的元数据字段时设置 meta，例如简短说明。
• getThreads (boolean, optional)
• editThreads (boolean, optional)
• readDocument (boolean, optional)
• proofread (boolean | { meta?: string }, optional): 当你希望 AI 在每次校对编辑中 包含一个额外的元数据字段时设置 meta，例如简短说明。

响应：

• systemPrompt (string): 将其添加到你 AI 请求的 system prompt 中。它会教会 AI Tiptap 文档如何工作、编辑器支持哪些元素，以及应使用哪种文档格式。
• tools (array): AI 或开发者可以调用的工具定义。每个数组元素包含：
  • name (string): 工具名称。
  • description (string): 工具描述。
  • inputSchema (object): AI 生成的工具输入的 JSON schema。

示例：

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": "简要解释此次编辑。"
      }
    },
    "format": "shorthand"
  }'

执行工具

POST /v4/ai/toolkit/execute-tool

执行一个工具。在 AI 模型生成工具调用后使用此端点。

请求体：

• editorContext (object, required): 由 getEditorContext 返回的编辑器上下文。
• document (object, required): 要对其执行工具的文档。使用 { "type": "cloud", "id": "your-document-id" }，当 API 应该从 Tiptap Cloud 文档读取和写入时。使用 { "type": "inline", "content": { /* Tiptap JSON document */ } }，当你想在请求体中提供 Tiptap JSON 文档时。
• user (string, optional): 由 AI 执行的编辑所归属的标识符。
• field (string, optional, default: "default"): 用于定位云 文档内部协作字段。文档存储多个可编辑字段时使用，例如标题和正文。
• tool (object, required): 要执行的工具调用。
  • name (string, required): 工具名称，例如 "tiptapRead"。
  • input (object, required): 由 AI 生成的工具输入。这是一个与 该工具的 schema 和工具定义相匹配的对象。每个工具的 schema 和工具定义可通过 /v4/ai/toolkit/fetch-tools 端点获取。
  • config (unknown, optional): 开发者提供的、工具特定的配置。
• format ('json' | 'shorthand', optional, default: 'json'): 工具输入和 输出使用的文档格式。参见 Tiptap Shorthand。
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): 控制编辑是直接应用还是作为可审阅的更改。

响应：

• tool (object): 已执行的工具及其输出。
  • name (string): 工具名称。
  • output (object): 提供给 AI 的工具输出。
• docChanged (boolean): 文档是否发生了变化。
• document (object | null): 更新后的文档；如果文档未更改则为 null。

示例：

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"
  }'

流式执行工具

POST /v4/ai/toolkit/stream-tool

以流式方式执行工具。tiptapEdit 可以逐步应用编辑，以实现打字效果。其他工具会在接收到完整输入后 运行，并返回一个最终事件，就像 execute-tool 一样。

请求分批发送。第一部分包含：

• editorContext (object, required): 由 getEditorContext 返回的编辑器上下文。
• document (object, required): 要对其执行工具的云文档： { "type": "cloud", "id": "your-document-id" }。流式传输不支持内联文档。
• user (string, optional): 由 AI 执行的编辑所归属的标识符。
• field (string, optional, default: "default"): 用于定位云 文档内部协作字段。
• tool (object, required): 要执行的工具调用，不包含 tool.input。
  • name (string, required): 工具名称，例如 "tiptapEdit"。
  • config (unknown, optional): 开发者提供的、工具特定的配置。
• format ('json' | 'shorthand', optional, default: 'json'): 工具输入和 输出使用的文档格式。参见 Tiptap Shorthand。
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): 控制编辑是直接应用还是作为可审阅的更改。
• delayMs (number, optional, default: 5): 增量 tiptapEdit 输出中每个字符的延迟时间，单位为毫秒。必须介于 0 和 1000 之间。使用 0 可尽快应用编辑。

然后发送：

• 后续部分：tool.input 的值，在 AI 生成时以流式方式发送。

响应：

• tiptapEdit：在编辑被应用时返回增量事件，随后返回一个包含 更新后 document 的最终事件。
• 其他工具：返回一个最终事件，结果结构与 execute-tool 相同。

可用工具

这些工具可以提供给 AI 代理。代理决定调用哪个工具。

所有工具默认都处于禁用状态。我们建议先使用 tiptapRead 和 tiptapEdit，然后 根据需要启用其他工具。

你也可以直接从应用程序代码中调用这些工具，以构建自定义工作流。

tiptapRead

分块读取文档，以避免上下文窗口溢出。

工具配置（tool.config）：

• chunkSize（number，可选）：每次工具调用中读取的最大字符数。默认值：32000

工具输出（tool.output）：

成功响应：

• success（true）：表示读取请求成功。
• totalNodeCount（number）：文档中顶层节点的总数。
• nodeRange（[number, number]）：读取的顶层节点范围。
• content（JSONContent[] | string）：所返回范围内的文档内容。当 format 为 json 时，这是一个 Tiptap JSON 片段。当 format 为 shorthand 时，这是一个 Tiptap Shorthand 字符串。

错误响应：

• success（false）：表示读取请求失败。
• error（string）：错误信息。
• totalNodeCount?（number）：顶层节点总数。

tiptapEdit

编辑文档内容。

工具配置（tool.config）：

• threadData（object，可选）：添加到新建线程的元数据。
• commentData（object，可选）：添加到新建评论的元数据。

工具输出（tool.output）：

成功或部分成功响应：

• success（boolean）：所有操作是否都已成功完成。
• operationResults（array）：每个操作的结果。
  • success（boolean）：该操作是否已成功完成。
  • target（string）：操作所针对元素的字符串标识符。
  • error（string | null）：失败原因；如果操作成功则为 null。

错误响应：

• success（false）：表示编辑请求失败。
• reason（'validationError' | 'unexpectedError'）：错误类别。
• error（string）：错误信息。

getThreads

从云文档中读取评论线程。

工具配置（tool.config）：

• chunkSize（number，可选）：每次工具调用中读取的最大字符数。默认值：32000

工具输出（tool.output）：

成功响应：

• success（true）：表示读取请求成功。
• totalThreadCount（number）：文档中的线程总数。
• threadRange（[number, number]）：读取的线程范围，格式为 [from, to)。
• threads（array）：返回的线程对象。
  • id（string）：唯一线程标识符。
  • nodeRange（[number, number] | null）：线程所在的节点范围；如果线程未在文档中标注，则为 null。
  • content（JSONContent[] | string | null）：线程标记的内容。当 format 为 json 时，这是一个 Tiptap JSON 片段。当 format 为 shorthand 时，这是一个 Tiptap Shorthand 字符串。null 表示线程未在文档中标注。
  • comments（array）：线程中的评论。
    • id（string）：唯一评论标识符。
    • content（string）：评论文本。
    • userId（string）：创建该评论的用户 ID。
    • createdAt（string）：评论创建时的 ISO 时间戳。
    • updatedAt（string）：评论最后更新时间的 ISO 时间戳。
  • resolvedAt?（string | null）：线程被解决时的 ISO 时间戳；如果未解决，则为 null。
  • createdAt（string）：线程创建时的 ISO 时间戳。
  • updatedAt（string）：线程最后更新时间的 ISO 时间戳。
  • data?（Record<string, unknown>）：公开线程元数据。

错误响应：

• success（false）：表示读取请求失败。
• error（string）：错误信息。
• totalThreadCount?（number）：已持久化线程的总数（如已知）。

editThreads

创建和更新评论线程。

工具配置（tool.config）：

• threadData（object，可选）：添加到新建线程的元数据。
• commentData（object，可选）：添加到新建评论的元数据。

工具输出（tool.output）：

成功或部分成功响应：

• success（boolean）：表示所有操作是否都已成功完成。
• operations（array）：每个操作的结果。
  • type（string）：已执行的操作类型。
  • success（boolean）：该操作是否已成功完成。
  • message（string）：人类可读的操作结果。
  • threadId?（string）：用于创建或引用线程的操作对应的线程 ID。

错误响应：

• success（false）：表示请求在处理操作之前就已失败。
• error（string）：错误信息。

readDocument

读取整个文档。

工具配置（tool.config）：

null

工具输出（tool.output）：

成功响应：

• success（true）：表示文档读取成功。
• content（JSONContent[] | string）：整个有效文档内容。当 format 为 json 时， 这是一个 Tiptap JSON 片段。当 format 为 shorthand 时，这是一个 Tiptap Shorthand 字符串。

proofread

应用校对编辑。

工具配置（tool.config）：

• threadData（object，可选）：添加到新建线程的元数据。
• commentData（object，可选）：添加到新建评论的元数据。

工具输出（tool.output）：

成功或部分成功响应：

• success（boolean）：表示所有操作是否都已成功完成。
• operationResults（array）：每个操作的结果。
  • target（string）：操作所针对元素的字符串标识符。
  • success（boolean）：该操作是否已成功完成。
  • error（string | null）：失败原因；如果操作成功则为 null。

相关页面

• 审查选项
• 编辑器上下文