---
title: "Comments REST API"
description: "Use the Tiptap Comments REST API to manage threads and comments from outside the editor. More in the docs!"
canonical_url: "https://tiptap.dev/docs/comments/integrate/rest-api"
---

# Comments REST API

Use the Tiptap Comments REST API to manage threads and comments from outside the editor. More in the docs!

The Comments REST API lets users manage comment threads and individual comments from outside the Tiptap Editor. It supports creating, updating, deleting, and retrieving threads and comments.

Use the [Comments Postman Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-01d1c110-e913-4d99-b47a-fc95aad877c9) for hands-on experimentation.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Team plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Start Document server**

  To use the Comments REST API [Add an Environment](https://cloud.tiptap.dev/v2/configuration/document-server) in your dashboard and configure your [Document server](https://cloud.tiptap.dev/v2/configuration/document-server).

## Access the API

The REST API is exposed directly from your Document server, available at your custom URL:

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

Replace `YOUR_APP_ID` with your document server ID, which is labeled "Document server ID" in the [Cloud dashboard](https://cloud.tiptap.dev/v2/configuration/document-server).

Authentication is done using an API secret which you can find in
the [settings](https://cloud.tiptap.dev/v2/configuration/document-server) of your Document server. The secret must be sent as
an `Authorization` header.

If your document identifier contains a slash (`/`), encode it as `%2F`, e.g.
using `encodeURIComponent`.

## Review all API endpoints

| Operation      | Method | Endpoint                                                                         | Description                                 |
| -------------- | ------ | -------------------------------------------------------------------------------- | ------------------------------------------- |
| Create thread  | POST   | /api/documents/:identifier/threads                                               | Create a new thread within a document       |
| Get threads    | GET    | /api/documents/:identifier/threads                                               | List all threads and view their details     |
| Get thread     | GET    | /api/documents/:identifier/threads/:threadIdentifier                             | Retrieve a specific thread                  |
| Update thread  | PATCH  | /api/documents/:identifier/threads/:threadIdentifier                             | Modify attributes of an existing thread     |
| Update comment | PATCH  | /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier | Update the content or metadata of a comment |
| Delete thread  | DELETE | /api/documents/:identifier/threads/:threadIdentifier                             | Remove a specific thread from a document    |
| Delete comment | DELETE | /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier | Remove a specific comment from a thread     |

## Thread REST API endpoints

### Get threads

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

Retrieve all comment threads associated with a specific document. Use this endpoint to list all threads and view their details.

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

### Get thread

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

Fetch details of a specific thread using its unique identifier within a document. This is useful for retrieving specific discussion threads.

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

### Create thread

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

Create a new thread within a document. You can specify the initial content and additional data like user metadata.

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

> **Creating a thread is a two-step process:**
>
> Calling this endpoint creates the thread but does not attach it to any content in the document. To make the thread appear in the editor, you also need to wrap the target range in the document's Tiptap JSON with an `inlineThread` mark. See the [Create threads via API guide](https://tiptap.dev/docs/comments/integrate/create-thread-via-api.md) for the full workflow.

### Update thread

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

Modify attributes of an existing thread, such as marking it as resolved or updating its metadata.

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

### Delete thread

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

Remove a specific thread from a document, effectively deleting all nested comments.

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

## Comment REST API endpoints

### Create comment

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

Add a new comment to an existing thread. Specify the content and any associated data.

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

### Update comment

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

Update the content or metadata of an existing comment within a thread.

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

### Delete comment

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

Remove a specific comment from a thread. Use this to manage individual comments.

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

## Review Postman Collection

Use the [Comments Postman Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/folder/33042171-01d1c110-e913-4d99-b47a-fc95aad877c9) for hands-on experimentation.