Comments REST API

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

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 (/), 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

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.

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

Get thread

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.

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

Create thread

POST /api/documents/:identifier/threads

Create 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

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

Modify 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

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

Remove 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

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

Add 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

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

Update 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

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

Remove 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.