--- updatedAt: 2026-04-22T06:40:18.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # Import file to doc 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](https://dovetail.com/settings/user/notifications). # OpenAPI definition ```json { "openapi": "3.0.2", "paths": { "/v1/docs/import/file": { "post": { "description": "Create a new doc by importing a file. Provide the file in **exactly one** of two ways:\n\n- `url` — a publicly accessible URL that Dovetail downloads and imports, or\n- `file_id` — the id of a file you have already uploaded via the file upload API (the upload must be complete).\n\nSupported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV).\n\nIf 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.\n\nThe doc can be placed inside a project (via `project_id`) or a folder (via `folder_id`), but not both.\n\n`mime_type` is only used when importing from `url`; it is ignored when importing by `file_id` (the file already carries its own metadata).\n\nReturns the newly created doc object (without content).\n\n> 🚧 Permissions\n>\n> 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.\n\n\n> 🚧 Supported URLs\n>\n> 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.\n\n> 📘 Transcription notifications\n>\n> 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](https://dovetail.com/settings/user/notifications).", "summary": "Import file to doc", "tags": [ "Docs" ], "parameters": [], "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The field's label (name). Must match an existing field label when updating, or will create a new field when creating." }, "value": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ], "nullable": true, "description": "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." }, "type": { "type": "string", "enum": [ "BOOLEAN", "DATETIME", "EMAIL", "NPS", "NUMBER", "PERSON", "PHONE", "SELECT", "TEXT", "URL" ], "description": "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." } }, "required": [ "label", "value" ] }, "description": "The doc's fields." }, "mime_type": { "type": "string", "description": "The nature and format of the file you want to import. Only used when importing from `url`." }, "project_id": { "type": "string", "nullable": true, "description": "Unique identifier of the project that the doc is associated with. Cannot be used together with folder_id." }, "folder_id": { "type": "string", "nullable": true, "description": "Unique identifier of the folder to place the doc in. Cannot be used together with project_id." }, "author_id": { "type": "string", "description": "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." }, "title": { "type": "string", "description": "The doc's title.", "example": "My doc" }, "url": { "type": "string", "format": "uri", "description": "Publicly accessible HTTPS url of the file that you want to import. Provide exactly one of `url` or `file_id`." }, "file_id": { "type": "string", "description": "Unique identifier of a file already uploaded via the file upload API. The upload must be complete. Provide exactly one of `url` or `file_id`." }, "cover_image_file_id": { "type": "string", "nullable": true, "description": "Unique identifier of a file to use as the doc's cover image." } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "description": "The URL of this resource in the Dovetail web app. This field is experimental and may change without notice." }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "doc" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "The field's label (name). Must match an existing field label when updating, or will create a new field when creating." }, "value": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ], "nullable": true, "description": "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." }, "type": { "type": "string", "enum": [ "BOOLEAN", "DATETIME", "EMAIL", "NPS", "NUMBER", "PERSON", "PHONE", "SELECT", "TEXT", "URL" ], "description": "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." } }, "required": [ "label", "value" ] } }, "created_at": { "type": "string" }, "deleted": { "type": "boolean" }, "project": { "type": "object", "properties": { "id": { "type": "string", "nullable": true } }, "required": [ "id" ] }, "folder": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "nullable": true }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the file." }, "name": { "type": "string", "description": "The file's original name." }, "type": { "type": "string", "nullable": true, "description": "The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown." }, "size": { "type": "number", "nullable": true, "description": "Size of the file in bytes. Null if unknown." }, "status": { "type": "string", "enum": [ "completed", "pending", "failed" ], "description": "Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error." }, "author": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, { "type": "string", "format": "null", "nullable": true } ], "nullable": true, "description": "The user who uploaded the file, or null if the author is unknown." }, "created_at": { "oneOf": [ { "type": "string" }, { "type": "string", "format": "null", "nullable": true } ], "nullable": true, "description": "ISO 8601 timestamp when the file was created." }, "url": { "type": "string", "nullable": true, "description": "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." } }, "required": [ "id", "name", "type", "size", "status", "author", "created_at", "url" ] } }, "cover_image": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the file." }, "name": { "type": "string", "description": "The file's original name." }, "type": { "type": "string", "nullable": true, "description": "The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown." }, "size": { "type": "number", "nullable": true, "description": "Size of the file in bytes. Null if unknown." }, "status": { "type": "string", "enum": [ "completed", "pending", "failed" ], "description": "Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error." }, "author": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, { "type": "string", "format": "null", "nullable": true } ], "nullable": true, "description": "The user who uploaded the file, or null if the author is unknown." }, "created_at": { "oneOf": [ { "type": "string" }, { "type": "string", "format": "null", "nullable": true } ], "nullable": true, "description": "ISO 8601 timestamp when the file was created." }, "url": { "type": "string", "nullable": true, "description": "URL to download the cover image. Only available when the file has been fully processed." } }, "required": [ "id", "name", "type", "size", "status", "author", "created_at", "url" ], "nullable": true } }, "required": [ "id", "title", "type", "fields", "created_at", "deleted", "project", "folder", "files", "cover_image" ] } }, "required": [ "data" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "InvalidOperation" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "code", "title" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "ValidationError" ] }, "title": { "type": "string", "enum": [ "Contract violation" ] }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "code", "title", "message", "path" ] } ] } } }, "required": [ "errors" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "Unauthorized" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "Forbidden" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NotFound" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UnprocessableContent" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title", "message" ] } } }, "required": [ "errors" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TooManyRequests" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "InternalError" ] }, "title": { "type": "string", "enum": [ "Internal server error" ] }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } } } } } }, "info": { "title": "Dovetail Public API", "version": "0.0.1", "description": "The Dovetail Public API provides programmatic access to your Dovetail workspace.\n\n## Core concepts\n\n- **Projects** — Containers for organizing qualitative research. They hold data, docs, highlights, tags, and insights.\n- **Data** — Documents within a project that capture raw research data such as interview transcripts, survey responses, and session recordings. Available via `/v1/data`. The legacy `/v1/notes` endpoints access the same underlying resource.\n- **Docs** — Rich-text documents for writing up research reports, sharing findings, and publishing deliverables. Docs replace the deprecated insights resource.\n- **Highlights** — Selected passages of text or time ranges in transcripts that have been marked as significant during analysis.\n- **Tags** — Labels applied to highlights to categorize findings (e.g. 'Usability Issue', 'Feature Request').\n- **Channels** — Automated AI-powered pipelines that continuously analyze high-volume customer feedback (app reviews, NPS, support tickets) into structured topics.\n- **Contacts** — People in your contacts database such as interview participants or customers.\n- **Folders** — Hierarchical containers for organizing projects, docs, channels, and other content.\n- **Files** — Attachments (images, documents, audio, video) that can be embedded in docs, data entries, or insights.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header. Generate API tokens from your Dovetail workspace settings.\n\n## Base URL\n\nAll API endpoints are served under `https://dovetail.com/api`." }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://dovetail.com/api" }, { "url": "https://dovetailapp.com/api" } ] } ```