---
title: "Start a comment thread on a file, site page, order, or asset. The comment is attributed to the API key's creator."
method: POST
path: "/comment-threads"
tags: ["Comment-threads"]
---

# Start a comment thread on a file, site page, order, or asset. The comment is attributed to the API key's creator.

`POST /comment-threads`

## Request

- Base URL: `https://api.replo.app/v1`
- URL: `https://api.replo.app/v1/comment-threads`
- Auth: HTTP bearer

## Headers

- `Replo-Api-Version` '2026-10-29', required

## Request body

- object
  - `id` string, uuid: Client-generated thread id. Send the same id and commentId on a retry to get the existing thread back.
  - `commentId` string, uuid: Client-generated first-comment id. Required with id.
  - `target` union, required
    - object
      - `kind` 'file', required
      - `fileId` string, uuid, required
    - object
      - `kind` 'sitePage', required
      - `siteId` string, uuid, required
      - `url` string, required: The page path, URL or route pattern the comment is on, e.g. "/about" or "/products/[handle]". Stored without the locale prefix, and a route pattern without its [lang] segment.
      - `locale` string: The locale prefix in url, if any.
    - object
      - `kind` 'order', required
      - `orderId` string, uuid, required
    - object
      - `kind` 'asset', required
      - `assetId` string, uuid, required
  - `anchor` union: Where on the target to start the thread; omit or pass type none for the whole target. Point anchors work only on file and asset targets; site page and order threads must use none.
    - object: The thread is on the whole target.
      - `type` 'none', required
    - object: A point on the target, in fractions of its size. Only file and asset targets take points.
      - `type` 'point', required
      - `page` integer: Zero-based page, for multi-page files such as PDFs.
      - `x` number, required: Fraction of the target's width.
      - `y` number, required: Fraction of the target's height.
  - `body` string, required: Markdown (GFM) parsed as MDX. To mention someone, insert `<Mention data='<mentionable JSON>' />`. Expressions in braces, raw HTML and any other JSX are rejected, so escape a literal `{` or `<` with a backslash. Images must be hosted on assets.replocdn.com.

## Response `201`

Start a comment thread on a file, site page, order, or asset. The comment is attributed to the API key's creator.

- CommentThread
  - `object` 'comment_thread', required
  - `id` string, uuid, required
  - `projectId` string, uuid, required
  - `target` union, required
    - object
      - `kind` 'file', required
      - `fileId` string, uuid, required
    - object
      - `kind` 'sitePage', required
      - `siteId` string, uuid, required
      - `path` string, required: The page the thread is on, without its locale prefix: a path such as /about, or a route pattern such as /products/[handle].
    - object
      - `kind` 'order', required
      - `orderId` string, uuid, required
    - object
      - `kind` 'asset', required
      - `assetId` string, uuid, required
  - `anchor` union, required: Where on the target the thread sits; type none means the whole target.
    - object: The thread is on the whole target.
      - `type` 'none', required
    - object: A point on the target, in fractions of its size. Only file and asset targets take points.
      - `type` 'point', required
      - `page` integer: Zero-based page, for multi-page files such as PDFs.
      - `x` number, required: Fraction of the target's width.
      - `y` number, required: Fraction of the target's height.
    - object: An element on a page, pinned in the Replo app.
      - `type` 'element', required
      - `tagName` string, required
      - `textPreview` string, required: The element's visible text when the thread was started.
      - `quote` string, nullable, required: The text the commenter selected, if any.
    - object: A pin on a canvas, placed in the Replo app.
      - `type` 'canvas', required
  - `status` 'open' | 'resolved', required: CommentThreadStatus
  - `resolvedAt` string, date-time, nullable, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `comments` Comment[], required
    - `object` 'comment', required
    - `id` string, uuid, required
    - `threadId` string, uuid, required
    - `author` object, required
      - `id` string, required
      - `name` string, required
      - `deleted` boolean, required
    - `source` 'ui' | 'agent' | 'mcp' | 'api', required: How the comment was written: ui (the Replo app), agent (a Replo agent session), mcp or api.
    - `body` string, required: Markdown (MDX) written by the commenter, who may be outside the workspace. Mentions this API key can't read appear as `<RedactedMention category="…" />`. Empty when the comment is deleted.
    - `createdAt` string, date-time, required
    - `editedAt` string, date-time, nullable, required
    - `deleted` boolean, required

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid Replo Public API token. Send an active key as `Authorization: Bearer replo_sk_...`; if it was revoked, create a new key in Replo Settings.
- `403`: You are not authorized to access this resource. Ask a workspace owner to perform this action or to grant the key's creator access.
- `404`: Not Found. The resource may not exist, this key may lack the required scope, or the key's creator may have lost access. Check the key's scopes in Replo Settings and the creator's project or workspace access; a workspace owner can grant access.
- `409`: The resource is in a conflicting state.
- `413`: File content exceeds the 10 MiB limit.
- `429`: Too many requests. Please retry after the time indicated by the Retry-After header.
- `500`: An internal error occurred.
- `503`: Service temporarily unavailable.

## Changes

- **2026-11-04** `53d194ba2067`: 9 info
  - added the optional property `error/issues` to the response with the `400` status
  - added the optional property `error/issues` to the response with the `401` status
  - added the optional property `error/issues` to the response with the `403` status
  - added the optional property `error/issues` to the response with the `404` status
  - …5 more
- **2026-10-29** `666c31ceb45c`: 1 breaking, 1 info
  - removed the enum value `2026-10-05` from the `header` request parameter `Replo-Api-Version`
  - added the new enum value `2026-10-29` to the `header` request parameter `Replo-Api-Version`
- **2026-10-29** `c5b824c8d7e9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/replo/apis/replo-public-api/changes/comment-threads/post.md)

---

[API](https://skmtc.dev/replo/apis/replo-public-api.md) - [All operations](https://skmtc.dev/replo/apis/replo-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replo/apis/replo-public-api/revisions/53d194ba2067?raw)