文档管理 API

协作管理 API 提供了一套 RESTful 接口，用于管理文档。此 API 可用于文档的创建、列出、检索、更新、删除和复制。

您可以通过访问我们的 Postman 集合来体验 REST API。

速率限制

为维护系统的完整性并防止错误配置的客户端，我们的基础设施——包括管理 API 和通过 TiptapCollabProvider 的 websocket 连接——受到速率限制。

默认速率限制（每个源 IP）：

请求数： 100
时间窗口： 5 秒
突发容量： 最多 200 个请求

如果您在正常操作下遇到这些限制，请给我们发邮件。

访问 API

REST API 直接从您的文档服务器以自定义 URL 公开：

https://YOUR_APP_ID.collab.tiptap.cloud/

认证

通过在 Authorization 头中包含您的 API 密钥来验证您的 API 请求。您可以在 Tiptap Cloud 控制面板的设置中找到您的 API 密钥。

文档标识符

如果您的文档标识符包含斜杠 (/)，请将其编码为 %2F，例如，使用 encodeURIComponent。

API 端点概述

访问协作管理 API 以高效管理您的文档。有关 Tiptap 产品中所有端点的全面视图，请查看我们的 Postman 集合，其中包括详细示例和配置。

操作	方法	端点	描述
创建文档	POST	`/api/documents/:identifier`	使用 `yjs` 或 `json` 更新消息创建文档。
批量导入文档	PUT	`/api/admin/batch-import`	批量导入多个文档。
获取文档	GET	`/api/documents/:identifier`	以 `json` 或 `yjs` 格式导出文档。
列出文档	GET	`/api/documents`	检索带有分页选项的所有文档列表。
复制文档	POST + GET	`/api/documents/:identifier` (GET 然后 POST)	通过检索文档然后使用新标识符创建文档来复制文档。
加密文档	POST	`/api/documents/:identifier/encrypt`	使用 Base64 加密文档。
回退到版本	POST	`/api/documents/:identifier/versions`	批量导入多个文档。
更新文档	PATCH	`/api/documents/:identifier`	将 Yjs 更新消息应用于现有文档。
删除文档	DELETE	`/api/documents/:identifier`	从服务器中删除文档。
搜索文档	POST	`/api/search`	对所有文档执行搜索。

同时查看指标和统计端点!

创建文档

POST /api/documents/:identifier

此调用允许您使用二进制 Yjs 或 JSON 格式（默认：yjs）创建文档。它可用于在用户连接到 Tiptap 协作服务器之前预置文档。

如果文档成功创建，该端点返回 HTTP 状态 204，如果文档已存在，则返回 409。要覆盖现有文档，您必须首先删除它。

Yjs 格式：要使用 Yjs 二进制更新消息创建文档，首先使用 Y.encodeStateAsUpdate 编码 Yjs 文档。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

JSON 格式：要使用 JSON 创建文档，传递查询参数 format=json 并在 Tiptap JSON 格式中包含文档的内容。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: application/json' \
--data '{
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "这是您的内容。"
          }
        ]
      }
    ]
}'

批量导入文档

PUT /api/admin/batch-import

此调用允许您使用预定义的 JSON 结构批量导入多个文档。每个文档必须包含其元数据（如 created_at、name 和 version）以及 Tiptap JSON 格式的内容。

如果文档成功导入，该端点返回 HTTP 状态 204，如果请求包含无效数据，则返回 400。

curl --location --request PUT 'https://YOUR_APP_ID.collab.tiptap.cloud/api/admin/batch-import' \
--header 'Content-Type: application/json' \
--data '[
    [
        {
            "created_at": "2024-05-01T10:00:00Z",
            "version": 0,
            "name": "document-1",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v0"}]}]}
        },
        {
            "created_at": "2024-05-01T11:00:00Z",
            "version": 1,
            "name": "document-1",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v1"}]}]}
        }
    ],
    [
        {
            "created_at": "2024-06-01T10:00:00Z",
            "version": 0,
            "name": "document-2",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v0"}]}]}
        },
        {
            "created_at": "2024-06-01T11:00:00Z",
            "version": 1,
            "name": "document-2",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v1"}]}]}
        }
    ]
]'

获取文档

GET /api/documents/:identifier?format=:format&fragment=:fragment

此调用允许您以 JSON 或 Yjs 格式导出指定文档及其所有片段。如果文档当前在您的服务器上打开，我们将返回内存中的版本；否则，我们将从数据库读取。

format 支持 yjs、base64、text 或 json（默认：json）。如果您选择 yjs 格式，您将获得使用 Y.encodeStateAsUpdate 创建的二进制 Yjs 更新消息。
fragment 可以是一个数组（例如，fragment=a&fragment=b）或您想要导出的单个片段。默认情况下，我们只导出 default 片段。此参数仅在使用 json 或 text 格式时适用；在使用 yjs 时，您将始终获得整个 Yjs 文档。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

当使用 axios 时，您需要在请求选项中指定 responseType: arraybuffer。

import * as Y from 'yjs'

const ydoc = new Y.Doc()

const axiosResult = await axios.get(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
    responseType: 'arraybuffer',
  },
)

Y.applyUpdate(ydoc, axiosResult.data)

当使用 node-fetch 时，您需要使用 .arrayBuffer() 并从中创建一个 Buffer：

import * as Y from 'yjs'

const ydoc = new Y.Doc()

const fetchResult = await fetch(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
  },
)

Y.applyUpdate(ydoc, Buffer.from(await fetchResult.arrayBuffer()))

列出文档

GET /api/documents?take=100&skip=0

此调用返回存储中所有文档的分页列表。默认情况下，我们返回前 100 个文档。传递 take 和 skip 参数以调整分页。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

复制文档

此调用允许您复制或重复文档。首先，使用 GET 端点检索文档，然后使用 POST 调用创建一个新文档。以下是 TypeScript 的示例：

const docUpdateAsBinaryResponse = await axios.get(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=yjs',
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
    responseType: 'arraybuffer',
  },
)

await axios.post(
  'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME-duplicated',
  docUpdateAsBinaryResponse.data,
  {
    headers: {
      Authorization: 'YOUR_SECRET_FROM_SETTINGS_AREA',
    },
  },
)

加密文档

POST /api/documents/:identifier/encrypt

此调用允许您使用 Base64 加密指定标识符的文档。

如果文档成功加密，该端点返回 HTTP 状态 204，如果文档不存在，则返回 404。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/encrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '{
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": {
          "indent": 0,
          "textAlign": "left"
        },
        "content": [
          {
            "text": "整个文档将被替换为此（除非您将模式参数更改为 '\''append'\''）",
            "type": "text"
          }
        ]
      }
    ]
  }'

回退到版本

POST /api/documents/:identifier/versions

此调用允许您通过应用与文档的先前状态相对应的更新将文档回退到特定的先前版本。您必须在请求体中指定要回退到的版本。

如果文档成功回退，该端点返回 HTTP 状态 204，如果文档或版本未找到，则返回 404。

curl --location --request POST 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/versions/VERSION_ID/revertTo' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

更新文档

PATCH /api/documents/:identifier

此调用接受一个 Yjs 更新消息并将其应用于服务器上现有文档。

如果文档成功更新，该端点返回 HTTP 状态 204，如果文档不存在，则返回 404，如果有效负载无效或无法应用更新，则返回 422。

curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--data '@yjsUpdate.binary.txt'

API 端点还支持 JSON 文档更新、用于跟踪更改的文档历史记录以及特定节点的更新。

有关使用 JSON 而不是 Yjs 操作文档的更详细信息，请参阅我们的内容注入页面。

删除文档

DELETE /api/documents/:identifier

此调用在关闭与文档的任何连接后从服务器中删除文档。

如果文档成功删除，它返回 HTTP 状态 204，如果文档未找到，则返回 404。

curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA'

删除后文档仍然存在

如果端点返回 204 但文档仍然存在，请确保没有用户正在从提供者重新创建文档。在删除文档之前，我们会关闭所有连接，但您的错误处理可能会重新创建提供者，从而再次创建文档。

搜索文档

POST /api/search

当 Tiptap 语义搜索启用时，您可以在所有文档中执行上下文相关的搜索。

保持您的 API 密钥秘密

请在后端处理搜索请求以保持您的 API 密钥安全。考虑根据需要在您的应用程序中强制执行速率限制。

查询参数

您可以使用以下查询参数来调整搜索结果：

查询参数	类型	默认	描述
`threshold`	float	`0.5`	描述文档的相似性因子。值可以在 `0` 和 `1` 之间。
`limit`	int	`20`	限制结果数。值可以在 `1` 和 `100` 之间。

请求体参数

请求体参数	类型	默认	描述
`content`	string	-	您的搜索词。

curl -X POST https://YOUR_APP_ID.collab.tiptap.cloud/api/search \
  -H "Authorization: YOUR_SECRET_FROM_SETTINGS_AREA" \
  -H "Content-Type: application/json" \
  -d '{"content": "您的搜索词"}'