Comments REST API

The Comments REST API allows users to manage comment threads and individual comments from outside the Tiptap Editor. This includes creating, updating, deleting, and retrieving threads and comments.

Use the Comments Postman Collection for hands-on experimentation with these capabilities.

Access the API

The REST API is exposed directly from your Collaboration app, available at your custom URL:

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

Authentication is done using an API secret which you can find in the settings of your Collaboration app. The secret must be sent as an Authorization header.

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

Thread REST API endpoints

Get threads

Endpoint: GET /api/documents/:identifier/threads

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

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

Get thread

Endpoint: GET /api/documents/:identifier/threads/:threadIdentifier

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

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

Create thread

Endpoint: POST /api/documents/:identifier/threads

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

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

Update thread

Endpoint: PATCH /api/documents/:identifier/threads/:threadIdentifier

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

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

Endpoint: DELETE /api/documents/:identifier/threads/:threadIdentifier

Description: Removes a specific thread from a document, effectively deleting all nested comments.

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

Endpoint: POST /api/documents/:identifier/threads/:threadIdentifier/comments

Description: Adds a new comment to an existing thread. Specify the content and any associated data.

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

Endpoint: PATCH /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier

Description: Updates the content or metadata of an existing comment within a thread.

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

Endpoint: DELETE /api/documents/:identifier/threads/:threadIdentifier/comments/:commentIdentifier

Description: Removes a specific comment from a thread. Use this to manage individual comments.

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 for hands-on experimentation.