Create a new insight in your Dovetail workspace. Insights are polished research deliverables for sharing findings with stakeholders.

Note: This endpoint is deprecated. Use Create doc (POST /v1/docs) instead.

You can provide the initial content as HTML, Markdown, or plain text via the content and content_type fields. An insight can be placed inside a project (via project_id) or a folder (via folder_id), but not both.

HTML content may include inline Dovetail nodes using the data-dovetail-type attribute — see the mention shape below for an example.

Returns the insight object without the content body.

Inline mentions: to reference a Dovetail user, include a span with data-dovetail-type="mn" and data-dovetail-attrs='{"id":"<user-uuid>"}'. The span's inner text is used as the fallback label if the user cannot be resolved. When the id resolves to a live workspace user, the span is replaced with a live mention node on import. Unresolved ids degrade gracefully to plain text — the import does not fail.

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.