文档管理 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/

将 YOUR_APP_ID 替换为您的文档服务器 ID，该 ID 在 Cloud 控制台中标示为“文档服务器 ID”。

身份验证

使用携带 Documents:Api:All 权限的签名令牌对您的 API 请求进行身份验证，并通过 Authorization: Bearer <jwt> 发送。有关如何签名令牌，请参阅身份验证。

将此令牌保留在服务端

Documents:Api:All 可访问每个文档服务器 API 端点，包括受管理的设置。请将携带该权限的令牌视为管理员凭证。请在您的服务器上签名，保持其短期有效，并且绝不要暴露给客户端。

之前的 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 then POST)	通过先检索文档再使用新标识符创建它来复制文档。
加密文档	POST	`/api/documents/:identifier/encrypt`	使用 Base64 加密文档。
列出版本	GET	`/api/documents/:identifier/versions`	获取文档的所有版本。
获取版本	GET	`/api/documents/:identifier/versions/:versionId`	获取特定版本。
创建版本	POST	`/api/documents/:identifier/versions`	创建带有可选名称和元数据的新版本。
更新版本	PATCH	`/api/documents/:identifier/versions/:versionId`	更新版本的名称或元数据。
回退到版本	POST	`/api/documents/:identifier/versions/:versionId/revertTo`	将文档回退到较早版本。
更新文档	PATCH	`/api/documents/:identifier`	将 Yjs 更新消息应用到现有文档。
更新文档（PUT 别名）	PUT	`/api/documents/:identifier`	`PATCH` 端点的别名——以相同的行为应用 Yjs 更新消息。
检查文档是否存在	HEAD	`/api/documents/:identifier`	检查文档是否存在（无响应正文）。
删除文档	DELETE	`/api/documents/:identifier`	从服务器删除文档。
删除版本	DELETE	`/api/documents/:identifier/versions/:versionId`	删除文档的特定版本。
导出文档	GET	`/api/documents/:identifier/export`	将文档及其所有版本导出为 `.zip` 存档。
导入文档	POST	`/api/documents/:identifier/import`	从导出的 `.zip` 存档中导入文档（及其版本）。
发送无状态消息	POST	`/api/documents/:identifier/stateless`	向文档的所有已连接客户端广播一条无状态消息。

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

创建文档

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: Bearer YOUR_JWT' \
--data '@yjsUpdate.binary'

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

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME?format=json' \
--header 'Authorization: Bearer YOUR_JWT' \
--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": "文档-1",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v0"}]}]}
        },
        {
            "created_at": "2024-05-01T11:00:00Z",
            "version": 1,
            "name": "文档-1",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-1 的文本：v1"}]}]}
        }
    ],
    [
        {
            "created_at": "2024-06-01T10:00:00Z",
            "version": 0,
            "name": "文档-2",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v0"}]}]}
        },
        {
            "created_at": "2024-06-01T11:00:00Z",
            "version": 1,
            "name": "文档-2",
            "tiptap_json": {"type": "doc", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "文档-2 的文本：v1"}]}]}
        }
    ]
]'

获取文档

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

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

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

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

当使用 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: 'Bearer YOUR_JWT',
    },
    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: 'Bearer YOUR_JWT',
    },
  },
)

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: Bearer YOUR_JWT'

复制文档

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

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

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

请注意，新文档将不会拥有源文档的版本记录。如果您想保留版本，可以使用导入/导出端点（参见 Postman 集合）。

加密文档

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: Bearer YOUR_JWT' \
--data '{
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": {
          "indent": 0,
          "textAlign": "left"
        },
        "content": [
          {
            "text": "整个文档将被替换为此（除非您将模式参数更改为 '\''append'\''）",
            "type": "text"
          }
        ]
      }
    ]
  }'

版本管理

版本记录了文档在某一时间点的状态。每个版本都有一个 version 编号、date，以及可选的 name 和 meta（任意元数据对象）。

每个版本的 meta 对象会自动包含一个 __tiptap 键，其中包含服务器生成的有关谁贡献了更改以及版本是如何创建的元数据。详情请参见自动版本元数据。

如需查看所有版本端点的完整交互式参考，请参见 Postman 集合。

回退到版本

POST /api/documents/:identifier/versions/:versionId/revertTo

此调用允许您将文档回退到特定的先前版本，通过应用与文档先前状态对应的更新。

如果文档成功回退，该端点将返回 HTTP 状态 200；如果未找到文档或版本，则返回 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: Bearer YOUR_JWT'

更新版本

PATCH /api/documents/:identifier/versions/:versionId

此调用允许您更新版本的名称或元数据。您可以用它来重命名版本或在创建后附加更多上下文。

有关请求体参数和示例，请参阅 Postman 集合。

删除一个版本

DELETE /api/documents/:identifier/versions/:versionId

此调用会删除文档的单个版本。:versionId 是列表/获取版本端点返回的版本编号。

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

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

更新文档

PATCH /api/documents/:identifier

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

同一端点也可通过 PUT /api/documents/:identifier 访问，其行为与 PATCH 完全相同（请求体和查询参数相同）。

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

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

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: Bearer YOUR_JWT'

删除后文档仍然存在

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

检查文档是否存在

HEAD /api/documents/:identifier

此调用会检查具有给定标识符的文档是否存在，而不会传输其内容。响应没有正文。

如果文档存在，则返回 HTTP 状态 200；如果不存在，则返回 404。存在性与文档的启用/停用状态无关。

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

导出和导入文档

使用这些端点可以在服务器之间移动文档（连同其所有版本），或者创建可移植备份。与复制文档不同，导出存档会保留文档的版本历史。

导出文档

GET /api/documents/:identifier/export

此调用会将当前文档及其所有版本导出为一个 .zip 存档（Content-Type: application/zip）。之后可以使用导入端点再次导入该存档。

它会返回 HTTP 状态 200，响应体为该存档；如果文档不存在，则返回 404。

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

导入文档

POST /api/documents/:identifier/import

此调用会从先前通过导出端点创建的存档中导入一个文档（及其版本）。请将存档作为原始请求体发送——服务器会读取原始字节，不需要特定的 Content-Type 头。目标 :identifier 不能已存在。

验证失败的请求会在导入开始前被正常的 HTTP 状态码拒绝：如果目标标识符的文档已存在则返回 409，如果存档超过允许的最大请求体大小则返回 413，如果存档格式错误则返回 400。

一旦导入开始，端点会返回 HTTP 状态 200（Content-Type: application/x-ndjson），并在工作过程中流式传输以换行分隔的 JSON（NDJSON）进度事件。流的结尾会以一个 done 事件结束，其 status 字段报告最终结果：成功时为 201，或者如果在导入运行期间创建了冲突文档，则为 409。如果导入中途失败，流会以带有状态 422 的 error 事件结束。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/import' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: application/zip' \
--data-binary '@export.zip'

发送无状态消息

POST /api/documents/:identifier/stateless

此调用会向当前连接到该文档的所有客户端广播一个自定义负载。客户端会将其作为无状态消息接收，你可以通过 provider 的 onStateless 回调或监听 stateless 事件来处理它。

请求体会原样作为无状态负载发送。该端点在消息广播完成后返回 HTTP 状态 204。

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/DOCUMENT_NAME/stateless' \
--header 'Authorization: YOUR_SECRET_FROM_SETTINGS_AREA' \
--header 'Content-Type: application/json' \
--data '{ "type": "ping", "payload": "hello" }'

Previously概述

Next up快照