Sign in

v1

latestOpenAPI 3.0.22026-07-261040577.4 KB
InsightComments

Create insight comment

Create a comment on an insight.

If no comment thread exists on the insight, one will be created automatically. 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.

post/v1/insights/{insight_id}/comments

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.

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