---
title: "Create comment threads via the REST API"
description: "Learn the full workflow for creating comment threads on a Tiptap document from outside the editor using the REST API."
canonical_url: "https://tiptap.dev/docs/comments/integrate/create-thread-via-api"
---

# Create comment threads via the REST API

Learn the full workflow for creating comment threads on a Tiptap document from outside the editor using the REST API.

Creating a comment thread on a document from outside the editor takes two steps: you create the thread through the [Comments REST API](https://tiptap.dev/docs/comments/integrate/rest-api.md) 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](https://tiptap.dev/docs/comments/integrate/editor-commands.md#setthread-content-data-commentdata). 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).

```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": "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:

```json
{
    "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.

```json
{
  "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](https://tiptap.dev/docs/collaboration/documents/content-injection.md) 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:

```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": "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.

## Related

- [Comments REST API reference](https://tiptap.dev/docs/comments/integrate/rest-api.md) — full list of endpoints.
- [Editor commands](https://tiptap.dev/docs/comments/integrate/editor-commands.md) — create threads and comments from an active editor instance.
- [Manage threads](https://tiptap.dev/docs/comments/core-concepts/manage-threads.md) — concepts and patterns for working with threads.