DOdovetail
Insights

Import file to insight

Changed on

Create a new insight by importing a file from a publicly accessible URL. Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV).

Note: This endpoint is deprecated. Use Import file to doc (POST /v1/docs/import/file) instead.

If the imported file is audio or video, Dovetail will automatically queue it for transcription. The resulting transcript will be added to the insight body once processing completes.

The insight can be placed inside a project (via project_id) or a folder (via folder_id), but not both.

Returns the newly created insight object (without content).

🚧 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.

🚧 Supported URLs

The URL must use HTTPS and resolve to a public address; Dovetail rejects URLs that point to private, loopback, or link-local addresses. Only URLs that link directly to a downloadable file are supported. If the URL does not include a file extension, you must provide the mime_type parameter so Dovetail can determine how to process the file.

📘 Transcription notifications

When a transcription completes or fails, the account linked to the API token will receive a notification. You can manage notification preferences in notification settings.

Required scope: doc:file_import

post/v1/insights/import/file

Request

Request body

mime_typestring

The nature and format of file want to import.

project_idstring nullable

Unique identifier of the project that the insight is associated with. Cannot be used together with folder_id.

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

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. The author is also recorded as a contributor, alongside 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.

titlestring required

The insight's title.

urlstring uri required

Publicly accessible HTTPS url of the file that you want to import.

cover_image_file_idstring nullable

Unique identifier of a file to use as the insight's cover image.

Example request

{
  "title": "My insight"
}

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