---
title: "Create insight comment"
method: POST
path: "/v1/insights/{insight_id}/comments"
tags: ["InsightComments"]
deprecated: true
---

# Create insight comment

`POST /v1/insights/{insight_id}/comments`

## Request

- Base URL: `https://dovetail.com/api`
- URL: `https://dovetail.com/api/v1/insights/{insight_id}/comments`
- Auth: HTTP bearer

> **Deprecated.**

Create a comment on an insight.

If no page-level comment thread exists on the insight, one will be created automatically unless `thread_id` is set. Pass `thread_id` from list or get comments to append a reply to that page-level or inline thread. The comment is attributed to the authenticated user.

> 🚧 Permissions
>
> Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

**Required scope:** `comment:write`

## Path parameters

- `insight_id` string, required

## Request body

- object
  - `body` string, required: The comment content. Interpreted according to body_type (defaults to plain text).
  - `body_type` 'text' | 'html': Format of the body field. Defaults to "text". Use "html" for rich text content.
  - `author_id` string: Workspace user to attribute this comment to. **Workspace admins only** — useful when importing comments from another tool. The target user must be an active member of the same workspace. If omitted, the comment is attributed to the authenticated user. When an admin sets this field, the author change is recorded in workspace audit logs with the API user as the actor, so overrides remain traceable. Once set, only the target user can edit or delete the comment.
  - `created_at` string, date-time: ISO 8601 datetime to set as the comment's creation date. Only workspace admins can use this field. If omitted, defaults to the current time. Can only be set at creation time. When an admin sets this field, the timestamp change is recorded in workspace audit logs with the API user as the actor, so overrides remain traceable.
  - `published_at` string, date-time: ISO 8601 datetime to set as the comment's publication date. This is the timestamp shown in the Dovetail UI for the comment. Only workspace admins can use this field. If omitted, defaults to the current time. Can only be set at creation time. Must be >= created_at and not in the future. When an admin sets this field, the timestamp change is recorded in workspace audit logs with the API user as the actor, so overrides remain traceable.
  - `thread_id` string: Existing comment thread on this doc. When set, the comment is appended to that page-level or inline thread. When omitted, posts on the page-level thread.

## Response `201`

201

- object
  - `data` object, required
    - `id` string, required
    - `url` string: The URL of the doc this comment belongs to in the Dovetail web app.
    - `body` string, required
    - `author` object, required
      - `id` string, required
      - `name` string, required
    - `created_at` string, required
    - `updated_at` string, required
    - `comment_type` 'page' | 'inline', required: The type of comment: "page" for page-level comments, "inline" for comments on text selections.
    - `thread_id` string, required: Identifier of the comment thread. Comments that share a thread_id are replies in the same conversation.
    - `text_range` object, nullable: The selected text and surrounding context for inline comments. Present on POST, GET, PATCH, and DELETE of a single comment. On list, omitted unless `include_text_range=true`. Null for page-level comments when included.
      - `text` string, required: The selected text that this inline comment is attached to.
      - `text_before` string, nullable, required: Text context before the selection.
      - `text_after` string, nullable, required: Text context after the selection.

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `404`: 404
- `422`: 422
- `429`: 429
- `500`: 500

## Changes

- **2026-11-03** `8abea327e6b9`: 4 breaking, 1 warning, 4 info
  - added `subschema #1, subschema #2` to the `errors/items/` response property `oneOf` list for the response status `403`
  - the `errors/items/` response's property type changed from `object` to no type for status `403`
  - removed the required property `errors/items/code` from the response with the `403` status
  - removed the required property `errors/items/title` from the response with the `403` status
  - …5 more

[Operation history](https://skmtc.dev/dovetail/apis/dovetail-public-api/changes/v1/insights/:insight_id/comments/post.md)

---

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