Create a new doc by importing a file. Provide the file in exactly one of two ways:

• url — a publicly accessible URL that Dovetail downloads and imports, or
• file_id — the id of a file you have already uploaded via the file upload API (the upload must be complete).

Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV).

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

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

mime_type is only used when importing from url; it is ignored when importing by file_id (the file already carries its own metadata).

Returns the newly created doc 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

{
  "title": "My doc"
}