---
title: "评论 REST API"
description: "使用 Tiptap 评论 REST API 从编辑器外部管理线程和评论。更多内容请查看文档！"
canonical_url: "https://tiptap.zhcndoc.com/comments/integrate/rest-api"
---

# 评论 REST API

使用 Tiptap 评论 REST API 从编辑器外部管理线程和评论。更多内容请查看文档！

评论 REST API 允许用户从 Tiptap 编辑器外部管理评论线程和单个评论。它支持创建、更新、删除和检索线程与评论。

使用 [评论 Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-01d1c110-e913-4d99-b47a-fc95aad877c9) 进行动手实验。

- **1. 激活试用或订阅**

  在您的账户中[开始免费试用](https://cloud.tiptap.dev/v2?trial=true)或[订阅团队计划](https://cloud.tiptap.dev/v2/billing)。
- **2. 启动文档服务器**

  要使用评论 REST API，请在您的仪表板中 [添加环境](https://cloud.tiptap.dev/v2/configuration/document-server) 并配置您的 [文档服务器](https://cloud.tiptap.dev/v2/configuration/document-server)。

## 访问 API

REST API 直接从您的文档服务器提供，位于您的自定义 URL：

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

将 `YOUR_APP_ID` 替换为您的文档服务器 ID，该 ID 在 [Cloud 仪表板](https://cloud.tiptap.dev/v2/configuration/document-server) 中标记为 "Document server ID"。

使用带有 `Documents:Api:All` 权限的签名 token 进行身份验证，并作为 `Authorization: Bearer <jwt>` 标头发送。有关如何签名，请参见 [身份验证](https://tiptap.zhcndoc.com/authentication.md)。此 token 授予完整的 Document Server API 访问权限，因此请将其保留在服务器端。先前的 API secret 仍然可用，并在 [传统身份验证](https://tiptap.zhcndoc.com/authentication/legacy.md) 中有相关文档。

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

## 查看所有 API 端点

| 操作   | 方法     | 端点                                                                               | 描述             |
| ---- | ------ | -------------------------------------------------------------------------------- | -------------- |
| 创建线程 | POST   | /api/documents/:identifier/threads                                               | 在文档中创建一个新线程    |
| 获取线程 | GET    | /api/documents/:identifier/threads                                               | 列出所有线程并查看其详细信息 |
| 获取线程 | GET    | /api/documents/:identifier/threads/:threadIdentifier                             | 检索特定线程         |
| 更新线程 | PATCH  | /api/documents/:identifier/threads/:threadIdentifier                             | 修改现有线程的属性      |
| 更新评论 | PATCH  | /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier | 更新评论的内容或元数据    |
| 删除线程 | DELETE | /api/documents/:identifier/threads/:threadIdentifier                             | 从文档中删除特定线程     |
| 删除评论 | DELETE | /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier | 从线程中删除特定评论     |

## 线程 REST API 端点

### 获取线程

```bash
GET /api/documents/:identifier/threads
```

检索与特定文档相关的所有评论线程。使用此端点列出所有线程并查看它们的详细信息。

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads' \
--header 'Authorization: {{Authorization}}'
```

### 获取线程

```bash
GET /api/documents/:identifier/threads/:threadIdentifier
```

使用文档中唯一标识符获取特定线程的详细信息。这对于检索特定讨论线程很有用。

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}' \
--header 'Authorization: {{Authorization}}'
```

### 创建线程

```bash
POST /api/documents/:identifier/threads
```

在文档中创建一个新线程。您可以指定初始内容和用户元数据等附加数据。

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{Authorization}}' \
--data '{
    "content": "moin",
    "data": { "key": "ttt"}
}'
```

> **创建线程是一个两步过程:**
>
> 调用此端点会创建线程，但不会将其附加到文档中的任何内容。要使线程在编辑器中显示，您还需要在文档的 Tiptap JSON 中使用 `inlineThread` 标记包裹目标范围。完整工作流程请参见 [通过 API 创建线程指南](https://tiptap.zhcndoc.com/comments/integrate/create-thread-via-api.md)。

### 更新线程

```bash
PATCH /api/documents/:identifier/threads/:threadIdentifier
```

修改现有线程的属性，例如将其标记为已解决或更新其元数据。

```bash
curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{Authorization}}' \
--data '{
    "resolvedAt": null
}'
```

### 删除线程

```bash
DELETE /api/documents/:identifier/threads/:threadIdentifier
```

从文档中删除特定线程，有效地删除所有嵌套评论。

```bash
curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}' \
--header 'Authorization: {{Authorization}}'
```

## 评论 REST API 端点

### 创建评论

```bash
POST /api/documents/:identifier/threads/:threadIdentifier/comments
```

向现有线程添加新评论。指定内容和任何相关数据。

```bash
curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}/comments' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{Authorization}}' \
--data '{
    "content": "test",
    "data": { "key": "ttt"}
}'
```

### 更新评论

```bash
PATCH /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier
```

更新线程中现有评论的内容或元数据。

```bash
curl --location --request PATCH 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}/comments/{comment_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{Authorization}}' \
--data '{
    "content": "UPDATED!"
}'
```

### 删除评论

```bash
DELETE /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier
```

从线程中删除特定评论。使用此功能来管理单个评论。

```bash
curl --location --request DELETE 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads/{thread_id}/comments/{comment_id}' \
--header 'Authorization: {{Authorization}}'
```

## 查看 Postman 集合

使用 [评论 Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-01d1c110-e913-4d99-b47a-fc95aad877c9) 进行动手实验。