Tiptap Docs

Create comment threads via the REST API

Available in Team plan

Creating a comment thread on a document from outside the editor takes two steps: you create the thread through the Comments REST API and then link that thread to a position in the document by wrapping the target content with an inlineThread mark in the document's Tiptap JSON.

Calling the REST API alone is not enough. Without the inlineThread mark in the document, the editor has no way to know which content the thread belongs to, and the thread will not render in the editor UI.

Using an editor instance?

If you have an active editor instance, prefer the setThread editor command. It creates the thread and adds the inlineThread mark in one step.

Workflow overview

  1. Create the thread via the REST API. The response contains the thread's id.
  2. Update the document JSON so the content you want to attach the thread to is wrapped in an inlineThread mark whose data-thread-id matches that id.
  3. (Optional) Add more comments to the thread via the REST API.

Step 1: Create the thread

Send a POST request to /api/documents/:identifier/threads. The content field becomes the first comment in the thread, and data can hold any metadata you want to associate with the thread (for example, the author).

curl --location 'https://YOUR_APP_ID.collab.tiptap.cloud/api/documents/{document_id}/threads' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{Authorization}}' \
--data '{
    "content": "Is \"Capabilities\" the correct wording here?",
    "data": { "authorId": "123" }
}'

The response includes the newly created thread, including its id. Keep this ID — you need it for the next step.

Example response:

{
    "comments": [
        {
            "id": "2f5e54cf-cd3e-48a0-994c-48efa064111d",
            "createdAt": "2026-01-01T12:00:00.000Z",
            "updatedAt": "2026-01-01T12:00:00.000Z",
            "data": {
                "authorId": "123"
            },
            "content": "Is \"Capabilities\" the correct wording here?"
        }
    ],
    "id": "f290f5c4-fc22-4a58-b697-f0f2a10d2d95",
    "createdAt": "2026-01-01T12:00:00.000Z",
    "updatedAt": "2026-01-01T12:00:00.000Z"
}

Step 2: Link the thread to content in the document

To render the thread in the editor, wrap the relevant range in the document's Tiptap JSON with an inlineThread mark. The data-thread-id attribute must match the thread id returned by the API.

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [
        { "type": "text", "text": "Welcome to " },
        {
          "type": "text",
          "text": "Tiptap Comments",
          "marks": [
            {
              "type": "inlineThread",
              "attrs": {
                "data-thread-id": "f290f5c4-fc22-4a58-b697-f0f2a10d2d95"
              }
            }
          ]
        }
      ]
    }
  ]
}

How you apply this edit depends on where the document lives:

  • Documents managed by the Document server. Use the Inject Content API to patch the Tiptap JSON with the inlineThread mark while collaboration continues in real time.
  • Documents you are importing or generating. Add the inlineThread mark while you produce the JSON (for example, when converting a source format like DOCX that carries comment anchors), then seed the document server with the resulting JSON.

Step 3: Add further comments to the thread

Additional comments on an existing thread do not require any changes to the document JSON. Post them directly to the thread:

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": "Replying to the thread",
    "data": { "authorId": "123" }
}'

The content field holds the comment body. If your frontend renders comments as rich text, pass Tiptap JSON instead of a plain string.

PreviouslyREST API