---
title: "Create insight"
method: POST
path: "/v1/insights"
tags: ["Insights"]
deprecated: true
---

# Create insight

`POST /v1/insights`

> **Deprecated.**

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.

## Request body

- object
  - `title` string — The insight's title.
  - `fields` object[] — The insight's fields.
    - `label` string, required — The field's label (name). Must match an existing field label when updating, or will create a new field when creating.
    - `value` union, required — The field's value. Type depends on the field type: string for TEXT/EMAIL/URL/PHONE, boolean for BOOLEAN, number for NUMBER/NPS, string (ISO 8601) for DATETIME, string array for SELECT, or string (contact name) for PERSON. Null to clear the value.
      - string
      - boolean
      - number
      - string[]
    - `type` 'BOOLEAN' | 'DATETIME' | 'EMAIL' | 'NPS' | 'NUMBER' | 'PERSON' | 'PHONE' | 'SELECT' | 'TEXT' | 'URL' — Include the desired type when creating a new field. If omitted or left empty, the field type defaults to TEXT. Do not include this property when referencing an existing field.
  - `content` string — The initial content of the insight. Interpreted according to the content_type field (defaults to HTML).
  - `content_type` 'html' | 'markdown' | 'text' — The format of the content field. Defaults to "html". Use "markdown" for Markdown-formatted content (supports headings, lists, bold, italic, code blocks, tables, task lists, links, and blockquotes). Use "text" for plain text.
  - `project_id` string, nullable — Unique identifier of the project that the insight is associated with. Cannot be used together with folder_id.
  - `folder_id` string, nullable — Unique identifier of the folder to place the insight in. Cannot be used together with project_id. Cannot be combined with fields in the same request.
  - `author_id` string — Unique identifier of the user to set as the author. Only workspace admins can use this field. If omitted, defaults to the authenticated user. Can only be set at creation time. 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.
  - `cover_image_file_id` string, nullable — Unique identifier of a file to use as the insight's cover image.
  - `created_at` string, date-time — ISO 8601 datetime to set as the insight's creation date. Only workspace admins can use this field. If omitted, defaults to the current time. Can only be set at creation time.

## Response `201`

201

- object
  - `data` object, required
    - `id` string, required
    - `url` string — The URL of this resource in the Dovetail web app. This field is experimental and may change without notice.
    - `title` string, required
    - `type` 'insight', required
    - `fields` object[], required
      - `label` string, required — The field's label (name). Must match an existing field label when updating, or will create a new field when creating.
      - `value` union, required — The field's value. Type depends on the field type: string for TEXT/EMAIL/URL/PHONE, boolean for BOOLEAN, number for NUMBER/NPS, string (ISO 8601) for DATETIME, string array for SELECT, or string (contact name) for PERSON. Null to clear the value.
        - string
        - boolean
        - number
        - string[]
      - `type` 'BOOLEAN' | 'DATETIME' | 'EMAIL' | 'NPS' | 'NUMBER' | 'PERSON' | 'PHONE' | 'SELECT' | 'TEXT' | 'URL' — Include the desired type when creating a new field. If omitted or left empty, the field type defaults to TEXT. Do not include this property when referencing an existing field.
    - `created_at` string, required
    - `deleted` boolean, required
    - `project` object, required
      - `id` string, nullable, required
    - `folder` object, nullable, required
      - `id` string, required
    - `files` object[], required
      - `id` string, required — Unique identifier of the file.
      - `name` string, required — The file's original name.
      - `type` string, nullable, required — The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
      - `size` number, nullable, required — Size of the file in bytes. Null if unknown.
      - `status` 'completed' | 'pending' | 'failed', required — Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
      - `author` union, required — The user who uploaded the file, or null if the author is unknown.
        - object
          - `id` string, required
          - `name` string
        - string, null, nullable
      - `created_at` union, required — ISO 8601 timestamp when the file was created.
        - string
        - string, null, nullable
      - `url` string, nullable, required — Permanent URL pointing at the **Download a file** endpoint. Safe to cache and store — the URL itself never expires, but calling it requires the same authentication as other API endpoints and returns a short-lived presigned URL each time. The endpoint performs its own readiness and access checks.
    - `cover_image` object, nullable, required
      - `id` string, required — Unique identifier of the file.
      - `name` string, required — The file's original name.
      - `type` string, nullable, required — The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
      - `size` number, nullable, required — Size of the file in bytes. Null if unknown.
      - `status` 'completed' | 'pending' | 'failed', required — Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
      - `author` union, required — The user who uploaded the file, or null if the author is unknown.
        - object
          - `id` string, required
          - `name` string
        - string, null, nullable
      - `created_at` union, required — ISO 8601 timestamp when the file was created.
        - string
        - string, null, nullable
      - `url` string, nullable, required — URL to download the cover image. Only available when the file has been fully processed.

## Other responses

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

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/versions/4107f5fdf8b2/schema)