DOdovetail
InsightComments

Create insight comment

Changed on

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

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

Path parameters

insight_idstring required

Unique identifier of the insight.

Request body

bodystring 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_idstring

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_atstring 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_atstring 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_idstring

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.

Example request

{
  "body": "Great insight! We should follow up on this.",
  "created_at": "2024-01-15T10:30:00Z",
  "published_at": "2024-01-15T10:30:00Z"
}

Response

201

Changes

  • 8abea327e6b9Revision changes
    • breaking

      added subschema #1 subschema #2 to the / response property oneOf list for the response status

    • breaking

      the / response's property type changed from object to no type for status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status