# Dovetail Documentation > Documentation for Dovetail Append .md to any documentation page URL to get its markdown version. ## Guides - [Introduction](https://developers.dovetail.com/docs/introduction.md): Learn how to build your own integrations with Dovetail. - [Authorization](https://developers.dovetail.com/docs/authorization.md): This guide describes the authorization flows for Dovetail’s Public API. - [Rate Limits](https://developers.dovetail.com/docs/rate-limits.md): This guide provides details about rate limiting in Dovetail to help you anticipate and manage rate limiting - [Pagination](https://developers.dovetail.com/docs/pagination.md): This guide describes how list resources are paginated. - [Filters](https://developers.dovetail.com/docs/filters.md): This guide describes how list resources can be filtered. - [Sort](https://developers.dovetail.com/docs/sort.md): This guide describes how list resources can be sorted. - [OAuth 2.0](https://developers.dovetail.com/docs/oauth-2.md): Learn how to authenticate users through third party applications. - [Content Formats](https://developers.dovetail.com/docs/content-formats.md): Learn how to create docs with Markdown, HTML, or plain text content. - [Comments](https://developers.dovetail.com/docs/comments-1.md): Manage comments on docs and insights. - [Comments](https://developers.dovetail.com/docs/comments.md): Manage comments on docs and insights. - [Dovetail MCP server](https://developers.dovetail.com/docs/mcp.md): Connect AI agents to your Dovetail workspace. - [Self-hosted MCP server](https://developers.dovetail.com/docs/mcp-self-hosted.md): Run the Dovetail MCP server locally for STDIO-based clients. ## API Reference - [Token info](https://developers.dovetail.com/reference/get_v1-token-info.md): Retrieve information about the API token used to authenticate this request. Use this endpoint to verify that your token is valid and to determine which workspace it belongs to. Returns the token's unique identifier and the subdomain of the associated Dovetail workspace. This is useful for confirming connectivity before making further API calls, or for identifying which workspace a token grants access to in multi-workspace setups. - [Magic Search](https://developers.dovetail.com/reference/post_v1-search.md): Perform a full-text search across your workspace's content. Returns matching highlights, data (notes), insights, channels, tags, and themes in a single response. Use the `query` field for keyword search, or provide structured `filter` objects to narrow results by specific entity types and their attributes. To include a content type with no filter constraints, pass an empty array for that type (e.g. `"notes": []`). Types omitted from the filter are excluded from results. The `notes` key in the filter and response corresponds to the "data" resource in the Dovetail product. Results are paginated using `offset` and `limit` (default 50, max 250). Each content type is returned in its own array within the response. > πŸ“˜ Prefer Search V2 > > For more advanced filtering including location-based search, contributor filters, and additional content types (projects, folders, people, dashboards, agents), use the **Search V2** (`POST /v2/search`) endpoint. - [Search V2](https://developers.dovetail.com/reference/post_v2-search.md): Perform an advanced search across your entire Dovetail workspace. This is the recommended search endpoint, supporting all content types: agents, highlights, data (notes), insights, channels, dashboards, tags, themes, projects, folders, and people (contacts). **Filtering options:** - **`types`** β€” Restrict results to specific content types (defaults to all types). - **`query`** β€” Full-text search string matched against titles and content. - **`location`** β€” Scope results to specific projects or folders using their IDs. - **`user`** β€” Filter by contributor or author. - **`tags`** / **`themes`** β€” Filter by tag or theme IDs. - **`people`** β€” Filter by contacts (people) mentioned in content. - **`fields`** β€” Filter by custom field values. - **`date`** β€” Filter by creation date range. - **`archived`** β€” Include archived items (default: `false`). Results can be sorted by relevance (default) or other criteria, and are paginated using `offset` and `limit` (default 20, max 100). Each content type is returned in its own array within the response. - [Magic Summarize](https://developers.dovetail.com/reference/post_v1-summarize.md): Generate an AI-powered summary from a collection of highlights, data entries (notes), insights, themes, and/or tags. Provide one or more arrays of IDs and Dovetail will synthesize the content into a concise summary. At least one of `highlight_ids`, `note_ids`, `insight_ids`, `theme_ids`, or `tag_ids` must contain at least one item. The `note_ids` field accepts data entry IDs (the product now calls these "data" rather than "notes"). Set `with_citations` to `true` (default) to include citation references in the summary. Each citation links back to the specific source item (highlight, data entry, insight, theme, or tag) that contributed to that part of the summary. Returns a summary string and an array of citations with their source IDs and types. - [Create channel](https://developers.dovetail.com/reference/post_v1-channels.md): Create a new channel in your workspace. A channel is an automated pipeline for analyzing customer feedback at scale. You must specify a `content_type` (e.g. `APP_REVIEW`, `NPS_FEEDBACK`, `SUPPORT_TICKETS`) that tells Dovetail what kind of data will flow through this channel. Optionally place the channel in a folder via `project_category_id`. Once created, send data to the channel using the **Create data point** (`POST /v1/channels/data`) endpoint. Dovetail will automatically classify each data point into topics. Returns the channel object with its initial set of AI-generated topics. - [Patch channel](https://developers.dovetail.com/reference/patch_v1-channels-channel-id.md): Update a channel's properties. Supports updating the title and the context (a description of the channel's main goal or purpose, which helps Dovetail's AI better classify incoming data). Only the fields you include in the request body will be modified. Returns the updated channel object. > 🚧 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. - [Delete channel](https://developers.dovetail.com/reference/delete_v1-channels-channel-id.md): Delete a channel. Deleted channel end up in your specific project's trash, but can be restored for up to 30 days before they’re automatically and permanently deleted. Returns the deleted channel object. > 🚧 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. - [Create topic](https://developers.dovetail.com/reference/post_v1-channels-topic.md): Create a new topic within a channel. Topics are categories used by Dovetail's AI to classify incoming data points. Each topic has a title and description that guide how data is sorted. You must specify the `channel_id` that this topic belongs to. After creating a topic, new data points sent to the channel will be evaluated against it during classification. Returns the newly created topic object. - [Patch topic](https://developers.dovetail.com/reference/patch_v1-channels-topic-topic-id.md): Update a topic's title and/or description. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. Updating a topic's description can change how future data points are classified against it. Returns the updated topic object. > 🚧 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. - [Delete topic](https://developers.dovetail.com/reference/delete_v1-channels-topic-topic-id.md): Delete a topic. Deleted topic end up in your specific project's trash, but can be restored for up to 30 days before they’re automatically and permanently deleted. Returns the deleted topic object. > 🚧 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. - [Create data point](https://developers.dovetail.com/reference/post_v1-channels-data.md): Send a new data point to a channel for automated AI analysis. Each data point represents a single piece of customer feedback (e.g. an app review, a support ticket, or an NPS response). The `text` field contains the content to analyze, and `timestamp` records when the feedback was originally received (in ISO 8601 format). You can optionally attach `source_title` and `source_url` to track provenance, and include `metadata` key-value pairs for additional context. Once created, Dovetail will automatically classify the data point against the channel's topics. Returns the data point object without the text content. - [List channels](https://developers.dovetail.com/reference/get_v1-channels.md): Retrieve all channels in your workspace. Channels are automated analysis pipelines that continuously process high-volume unstructured customer feedback (e.g. app reviews, NPS responses, support tickets) into structured, categorized insights using AI-powered topic classification. Results can be filtered by folder and sorted by creation date or title. They are paginated. - [Get channel](https://developers.dovetail.com/reference/get_v1-channels-channel-id.md): Retrieve a single channel's metadata by its unique identifier. Returns title, creation date, folder location, and a list of its topics (AI-generated categories used to classify incoming data points). > 🚧 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. - [List channel themes](https://developers.dovetail.com/reference/get_v1-channels-channel-id-themes.md): Retrieve all themes for a channel. Themes are AI-generated clusters of data points that share a common subject within a topic. Each theme has a `title` (a short label summarising the cluster), an optional `summary` (a longer AI-generated description of what data points in the theme share in common), and a `datum_count` (the number of data points currently classified into the theme). Results are sorted by `datum_count:desc` by default and are paginated using cursor-based pagination. > 🚧 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. - [List channel data points](https://developers.dovetail.com/reference/get_v1-channels-channel-id-data.md): Get a list of data points for a channel. > 🚧 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. - [Get data point](https://developers.dovetail.com/reference/get_v1-channels-data-datum-id.md): Get a data point by id. > 🚧 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. - [List folders](https://developers.dovetail.com/reference/get_v1-folders.md): Retrieve all folders in your workspace. Folders are used to organize projects, docs, channels, dashboards, agents, and other folders into a hierarchical structure β€” similar to a file system. Results can be filtered by title or parent folder, sorted by creation date or title, and are paginated. **Tip:** To list only root-level folders, filter with `filter[parent_folder_id]=null`. To list children of a specific folder, set `filter[parent_folder_id]` to that folder's ID. **Note:** The `folders` field (containing child folder IDs) is only populated when filtering by `parent_folder_id`. Without this filter, `folders` will be `null` for performance reasons. To retrieve child folders for a specific folder, either use `filter[parent_folder_id]` or call the **Get folder** (`GET /v1/folders/:folder_id`) endpoint. - [Get folder](https://developers.dovetail.com/reference/get_v1-folders-folder-id.md): Retrieve a single folder by its unique identifier. Returns the folder's metadata including title, parent folder, creation date, and a list of immediate child folder IDs. Use this endpoint to inspect a folder's position in the hierarchy or to discover its children. > 🚧 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. - [Get folder contents](https://developers.dovetail.com/reference/get_v1-folders-folder-id-contents.md): Retrieve all items contained within a specific folder. Returns a paginated list of projects, docs, channels, dashboards, agents, and child folders that are direct children of the specified folder. Each item includes its type, title, creation date, and author. Use this endpoint to browse a folder's contents or build a file-explorer-style navigation for your workspace. Results can be sorted by creation date or title and are paginated. > 🚧 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. - [Create folder](https://developers.dovetail.com/reference/post_v1-folders.md): Create a new folder in your Dovetail workspace. Folders organize projects, docs, channels, and other content into a hierarchical structure. Optionally provide a `parent_folder_id` to nest the folder inside an existing folder. If omitted, the folder is created at the workspace root level. Returns the newly created folder object. > 🚧 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. - [Patch folder](https://developers.dovetail.com/reference/patch_v1-folders-folder-id.md): Update a folder's properties. Currently supports updating the folder title. Only the fields you include in the request body will be modified. Returns the updated folder object. > 🚧 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. - [Delete folder](https://developers.dovetail.com/reference/delete_v1-folders-folder-id.md): Delete a folder. Deleted folders end up in your workspace's trash, but can be restored for up to 30 days before they're automatically and permanently deleted. Returns the deleted folder object. > 🚧 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. - [List projects](https://developers.dovetail.com/reference/get_v1-projects.md): Retrieve all projects in your workspace. Projects are containers for organizing qualitative research β€” they hold data, docs, highlights, tags, and insights related to a specific research initiative. Results can be filtered by folder or title, sorted by creation date or title, and are paginated. Use this endpoint to browse workspace content or build project selectors in your integration. - [Create project](https://developers.dovetail.com/reference/post_v1-projects.md): Create a new project in your Dovetail workspace. Projects are the primary container for organizing research β€” they hold data, docs, highlights, tags, and insights. Optionally provide a `template_id` to create the project from an existing workspace template. The new project will inherit the template's fields, views, tags, and other structural elements. Retrieve available templates using the **List project templates** (`GET /v1/projects/templates`) endpoint. Optionally provide a `folder_id` to create the project inside an existing folder. If omitted, the project is created at the workspace root level. Returns the newly created project object. > 🚧 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. - [Get project](https://developers.dovetail.com/reference/get_v1-projects-project-id.md): Retrieve a single project by its unique identifier. Returns the project's metadata including title, author, creation date, and folder location. Use this endpoint to fetch details about a specific project, for example to display project information or verify a project exists before creating content within it. > 🚧 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. - [Patch project](https://developers.dovetail.com/reference/patch_v1-projects-project-id.md): Update a project's properties. Currently supports updating the project title. Only the fields you include in the request body will be modified. Returns the updated project object. > 🚧 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. - [Delete project](https://developers.dovetail.com/reference/delete_v1-projects-project-id.md): Delete a project. Deleted projects end up in your workspace's trash, but can be restored for up to 30 days before they're automatically and permanently deleted. Returns the deleted project object. > 🚧 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. - [List project templates](https://developers.dovetail.com/reference/get_v1-projects-templates.md): Retrieve all project templates available in your workspace. Templates are reusable blueprints that define a project's fields, views, tags, and structural layout. Use the returned template IDs with the **Create project** (`POST /v1/projects`) endpoint to create a new project pre-populated with the template's configuration. This is useful for standardizing research workflows across your team. Results are paginated and can be sorted by creation date or title. - [Get project context](https://developers.dovetail.com/reference/get_v1-projects-project-id-context.md): Retrieve the AI context for a project, including its keywords and linked insight docs. Keywords guide AI features such as highlighting and tagging suggestions. Docs are insights used as source material for those features. - [Add project context keywords](https://developers.dovetail.com/reference/post_v1-projects-project-id-context-keywords.md): Add one or more keywords to the project's AI context. Duplicate keywords are ignored. Returns the full updated list of keywords. > 🚧 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. - [Remove project context keywords](https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-keywords.md): Remove one or more keywords from the project's AI context. Keywords not present in the current list are ignored. Returns the full updated list of keywords. > 🚧 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. - [Add project context doc](https://developers.dovetail.com/reference/post_v1-projects-project-id-context-docs.md): Add an insight to the project's AI context. A project can have at most 10 context docs. If the insight is already linked, this is a no-op. Returns the full updated list of context docs. > 🚧 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. - [Remove project context doc](https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-docs-doc-id.md): Remove an insight from the project's AI context. If the insight is not linked, this is a no-op. Returns the full updated list of context docs. > 🚧 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. - [List data](https://developers.dovetail.com/reference/get_v1-data.md): Retrieve all data entries in your workspace. Data entries are documents within a project that capture raw research data such as interview transcripts, survey responses, support tickets, and session recordings. They are the primary place where highlights and tags are applied during qualitative analysis. This is the recommended endpoint for listing research data. The legacy `/v1/notes` endpoints provide the same underlying content but the product now refers to this resource as "data". Each item in the response is **metadata only**: identifiers, title, project, folder, creation time, and deletion flag. The research **content body** (transcript, notes text, etc.) is not included. Use **Export data** (`GET /v1/data/:data_id/export/:type`) to read content for a specific entry. Results can be filtered by folder, project, title, or creation date. They can be sorted by creation date or title and are paginated. - [Create data](https://developers.dovetail.com/reference/post_v1-data.md): Create a new data entry within a Dovetail project. Data entries capture raw research data β€” interview transcripts, survey responses, support tickets, or CRM records. They must be associated with a project via `project_id`. You can provide the initial content as plain text or HTML via the `content` field, and attach custom field data via the `fields` array. Returns the data object without the content body. > 🚧 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. - [Get data](https://developers.dovetail.com/reference/get_v1-data-data-id.md): Retrieve a single data entry by its unique identifier. The response is **metadata only** with respect to the entry body: it includes title, custom fields, associated project, folder, and attached files, but **not** the main text/content body (transcript, imported document text, etc.). To retrieve the actual text content, use the **Export data** (`GET /v1/data/:data_id/export/:type`) endpoint. > 🚧 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. - [Patch data](https://developers.dovetail.com/reference/patch_v1-data-data-id.md): Update a data entry's properties. Supports updating the title and custom fields. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. Returns the updated data object. > 🚧 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. - [Delete data](https://developers.dovetail.com/reference/delete_v1-data-data-id.md): Delete a data. Deleted data end up in your specific project's trash, but can be restored for up to 30 days before they’re automatically and permanently deleted. Returns the updated data object. > 🚧 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. - [Export data](https://developers.dovetail.com/reference/get_v1-data-data-id-export-type.md): Export the content body of a data entry in either HTML or Markdown format. Use the `type` path parameter to specify the desired format: `html` or `markdown`. This is the only GET endpoint that returns the **content body** of a data entry. **List data** and **Get data** return metadata only (no body text). Returns the same identifying fields as **Get data**, plus either `content_html` or `content_markdown` with the full text content. **Including file content**: pass `?include_file_content=true` to also read the extracted text of attached document files (PDF, DOCX, PPTX, XLSX) from the search index β€” in the plain export, attached files appear only as links. The response then additionally includes: - `content_text` β€” the entry's full indexed body: its own text with file text inlined, plus any survey content. Each file's pages are preceded by a ` - ` header, so content can be attributed to its source file. - `files` β€” the entry's attached files with a per-file `text_status` (`ready` / `pending` / `failed` / `unsupported` / `unavailable`). - `indexed` β€” when `false`, the entry has not reached the search index yet and `content_text` is empty; retry shortly. - `truncated` β€” when `true`, the indexed body exceeded the search index's size limit and `content_text` is incomplete. Attached file text is returned under `note:read`: files are part of the data entry, and their visibility is implied by the entry's visibility. (`file:read` gates binary file egress via the file download API, not extracted text.) With `include_file_content=true`, returns 403 when the workspace has export disabled (HIPAA restriction), and when any attached file is past its retention window: retention removes the file's bytes but its extracted text remains in the search index, so the flag is refused rather than returning content the `files` list would label `unavailable`. The plain export (without the flag) is unaffected in both cases. - [Import file to data](https://developers.dovetail.com/reference/post_v1-data-import-file.md): Create a new data entry from 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). The data entry must be associated with a project via `project_id`. Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV). If the file is audio or video, Dovetail will automatically queue it for transcription. The resulting transcript will be added to the data body once processing completes. When importing from `url`, optionally set `created_at` to backdate the entry and `author_id` to attribute it to a specific user. These, along with `mime_type`, are ignored when importing by `file_id` (the file already carries its own metadata). Returns the newly created data 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 > > Only publicly accessible 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. > 🚧 Fields > > Only existing and unique fields can be referenced. This endpoint will not create new fields, or attempt to differentiate between duplicate field labels. > πŸ“˜ 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). - [List fields](https://developers.dovetail.com/reference/get_v1-fields.md): Get a list of fields for a project or workspace field group. You must provide either `project_id` or `workspace_field_group_id` in the filter, along with `field_set_type` (`data` or `doc`). - [Create field](https://developers.dovetail.com/reference/post_v1-fields.md): Create a field in a project or workspace field group. You must provide either `project_id` or `workspace_field_group_id`, along with `field_set_type`. > 🚧 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. - [Get field](https://developers.dovetail.com/reference/get_v1-fields-field-id.md): Get a field by id. > 🚧 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. - [Update field](https://developers.dovetail.com/reference/patch_v1-fields-field-id.md): Update a field by id. > 🚧 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. - [Delete field](https://developers.dovetail.com/reference/delete_v1-fields-field-id.md): Delete a field by id. This is a soft delete. > 🚧 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. - [Get file by id](https://developers.dovetail.com/reference/get_v1-files-file-id.md): Retrieve metadata for a single file by its unique identifier. Returns the file's name, MIME type, size in bytes, processing status (`pending`, `completed`, or `failed`), author, and creation date. Files are attachments (images, documents, audio, video) that can be embedded in docs, data entries, or other content. Use this endpoint to check a file's processing status after upload. - [Upload a file (deprecated)](https://developers.dovetail.com/reference/post_v1-files.md): **Deprecated** β€” use the v2 upload endpoints for new integrations: `POST /v2/files/upload` for files up to 5 GB and `POST /v2/files/large-upload` for files up to 10 GB. This endpoint is capped at 100 MB. Existing callers keep working. Each response carries a `Deprecation: true` header and a `Link` header pointing at the successor. A sunset date will be announced once v2 adoption is broad. --- Upload a file for embedding in docs, data entries, or insights. The request must use `multipart/form-data` encoding with a single `file` field containing the file data. After uploading, use the returned file ID to reference the file in document content (e.g. as a cover image via `cover_image_file_id` on the **Create doc** or **Patch doc** endpoints). **Limits:** Maximum file size is 100 MB. Orphaned files that are not embedded in any document within 24 hours are automatically cleaned up. Returns the file metadata including its processing status. - [Initiate a single-PUT file upload](https://developers.dovetail.com/reference/post_v2-files-upload.md): Initiate a single-PUT upload for files **up to 5 GB**. The response includes a pre-signed `upload_url` that the client should `PUT` the full file body to. After the `PUT` succeeds, call **Complete upload** at `POST /v2/files/{file_id}/upload/complete`. The pre-signed `upload_url` is signed for server-side encryption with AWS KMS, so the `PUT` request **must** include the header `x-amz-server-side-encryption: aws:kms`. Omitting it (or sending a different value) fails the request with a signature mismatch (HTTP `403`). ```bash curl -X PUT "" \ -H "x-amz-server-side-encryption: aws:kms" \ -H "Content-Type: " \ --data-binary @/path/to/file ``` Files larger than 5 GB must use the large-upload endpoint (`POST /v2/files/large-upload`) instead. Once finalized, inspect the file with `GET /v1/files/{file_id}` and download it with `GET /v1/files/{file_id}/download` β€” no v2 read surface exists yet. Returns `201` with the upload session details. Orphaned uploads that are not completed are eventually cleaned up. - [Finalize a single-PUT file upload](https://developers.dovetail.com/reference/post_v2-files-file-id-upload-complete.md): Finalize an upload session created by **Initiate single-PUT upload** (`POST /v2/files/upload`). The server `HEAD`s the S3 object to confirm bytes are present and that the size matches the declared value, then flips the file row to `DONE`. On success the file is marked as uploaded and returned in the response. The file's processing `status` may still be `pending` while downstream processing runs. Idempotent for already-DONE files: a retry of a previously-successful complete call (or a complete call arriving after the auto-finalize backstop has already finalised the row) returns `200` with the file metadata instead of `409`. `FAILED` / `CANCELLED` still return `409`. To cancel an in-progress upload, simply stop calling the API: abandoned file records are garbage-collected after 24 hours. - [Initiate a large (multipart) file upload](https://developers.dovetail.com/reference/post_v2-files-large-upload.md): Initiate a multipart upload for files **up to 10 GB**. The response includes an opaque `upload_id` and a fully populated `urls` array containing one pre-signed `PUT` URL per part the client should upload. After uploading every part, call **Complete large upload** at `POST /v2/files/{file_id}/large-upload/complete` with the resulting part `etag` values. The client may optionally specify the desired number of `parts` (1 to 10000). If omitted, the server picks a value based on the declared `size` and the recommended part size β€” for most uploads this is the right default. Every URL in `urls` expires roughly **3 hours** after issue. If a part `PUT` fails after that window, abandon the upload and initiate a fresh session. Once finalized, inspect the file with `GET /v1/files/{file_id}` and download it with `GET /v1/files/{file_id}/download` β€” no v2 read surface exists yet. Returns `201` with the upload session details. Orphaned uploads that are not completed are eventually cleaned up. - [Finalize a large (multipart) file upload](https://developers.dovetail.com/reference/post_v2-files-file-id-large-upload-complete.md): Finalize an upload session created by **Initiate large upload** (`POST /v2/files/large-upload`). The `parts` array must include every part that was uploaded, with the `etag` returned by the storage backend for each part `PUT`. On success the file is marked as uploaded and returned in the response. The file's processing `status` may still be `pending` while downstream processing runs. A `502` response indicates the storage backend rejected the finalization (for example, a part `etag` mismatch) β€” the client may retry. Idempotent for already-DONE files: a retry of a previously-successful complete call (or a complete call arriving after the auto-finalize backstop has already finalised the row) returns `200` with the file metadata instead of `409`. `FAILED` / `CANCELLED` still return `409`. To cancel an in-progress upload, simply stop calling the API: abandoned file records are garbage-collected after 24 hours, and any incomplete S3 multipart parts are reaped by an S3 bucket lifecycle rule. - [Download a file](https://developers.dovetail.com/reference/get_v1-files-file-id-download.md): Get a presigned URL to download the content of a file by its unique identifier. The response includes a short-lived URL that can be used to download the file directly from cloud storage without additional authentication. The URL is valid for 1 hour; call this endpoint again to mint a fresh URL when needed. Download availability is based on upload completion and redaction/obfuscation readiness. It is separate from processing status: a file can still report `pending` or `failed` from the **Get file by id** endpoint while the original bytes are available for download. - [List highlights](https://developers.dovetail.com/reference/get_v1-highlights.md): Retrieve all highlights in your workspace. Highlights are selected passages of text (or time ranges in audio/video transcripts) within data entries that have been marked as significant during qualitative analysis. They can be tagged with one or more tags to categorize findings. Results can be filtered by project, tag, specific highlight ID, creation date, or update date. **Only one** of `project_id`, `tag_id`, or `highlight_id` can be used per request. Results are sortable by creation date and are paginated. - [Get highlight](https://developers.dovetail.com/reference/get_v1-highlights-highlight-id.md): Retrieve a single highlight by its unique identifier. Returns the highlight's text content, associated data entry, tags, and time range (for transcript highlights). > 🚧 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. - [Create transcript highlight](https://developers.dovetail.com/reference/post_v1-highlights.md): Create a highlight on a transcript by specifying start and end timestamps in seconds. The data entry (referenced by `note_id`) must contain an audio or video transcript for the highlight to be created. If the entry contains multiple audio/video elements, the first transcript is used. **Tip:** to get word-level timestamps for picking `start_time` and `end_time`, pair this endpoint with **Export data** (`GET /v1/data/:data_id/export/html`). The HTML export wraps each transcript word in a `` carrying `data-monologue-start-time` and `data-monologue-end-time` attributes; the markdown export only includes paragraph-level timestamps. Bounds are snapped to the nearest word, so `start_time` / `end_time` returned by **Get highlight** / **List highlights** can be sent back here unchanged. Returns the created highlight. > 🚧 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. - [List tags](https://developers.dovetail.com/reference/get_v1-tags.md): Retrieve all tags in your workspace. Tags are labels used to categorize highlights during qualitative analysis (e.g. "Usability Issue", "Feature Request", "Positive Feedback"). Each tag belongs to a specific project. Results can be filtered by project and sorted by creation date. They are paginated. - [Get tag](https://developers.dovetail.com/reference/get_v1-tags-tag-id.md): Retrieve a single tag by its unique identifier. Returns the tag's title, the project it belongs to, and its creation date. > 🚧 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. - [Create tag](https://developers.dovetail.com/reference/post_v1-tags.md): Create a new tag within a project. Tags are labels used to categorize highlights β€” for example "Usability Issue", "Feature Request", or "Positive Feedback". Each tag must belong to a specific project (via `project_id`). Once created, the tag can be applied to highlights using the **Create transcript highlight** endpoint or in the Dovetail web app. Returns the newly created tag object. > 🚧 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. - [List docs](https://developers.dovetail.com/reference/get_v1-docs.md): Retrieve all docs in your workspace. Docs are rich-text documents used to write up research reports, share findings, and publish deliverables. They can exist within a project, inside a folder, or at the workspace root. Each item in the response is **metadata only**: identifiers, title, folder, and creation time. The document **content body** is not included. Use **Export doc** (`GET /v1/docs/:doc_id/export/:type`) to read content for a specific doc. Results can be filtered by folder, project, title, or creation date. They can be sorted by creation date or title and are paginated. - [Create doc](https://developers.dovetail.com/reference/post_v1-docs.md): Create a new doc in your Dovetail workspace. Docs are rich-text documents used to write up research reports, share findings, and publish deliverables. You can provide the initial content as HTML, Markdown, or plain text via the `content` and `content_type` fields. Markdown support enables importing content from Confluence, Notion, and other wiki or document stores. HTML content may include inline Dovetail nodes using the `data-dovetail-type` attribute β€” see the mention shape below for an example. A doc can be placed inside a project (via `project_id`) or a folder (via `folder_id`), but not both. If neither is specified, the doc is created at the workspace root level. Returns the doc 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":""}'`. 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. - [List personal docs](https://developers.dovetail.com/reference/get_v1-docs-user-user-id.md): Retrieve all docs owned by a specific user. Returns docs that were created by or assigned to the specified user. **Note:** This endpoint is deprecated. Docs are no longer owned by individual users β€” they belong to the workspace. Use **List docs** (`GET /v1/docs`) to enumerate docs across your workspace. Each item is **metadata only** (same shape as **List docs**): no document content body. Use **Export doc** to read the body for a given doc. Results support the same filtering (folder, project, title, creation date), sorting, and pagination as the **List docs** endpoint. - [Get doc](https://developers.dovetail.com/reference/get_v1-docs-doc-id.md): Retrieve a single doc by its unique identifier. The response is **metadata only** with respect to the document body: it includes title, custom fields, project reference, folder, files, and cover image, but **not** the rich-text **content body**. Unlike **List docs**, this returns the full detail view for one doc. To retrieve the actual document text, use **Export doc** (`GET /v1/docs/:doc_id/export/:type`). > 🚧 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. - [Delete doc](https://developers.dovetail.com/reference/delete_v1-docs-doc-id.md): Delete a doc. Deleted docs end up in your specific project's trash. They can be restored for up to 30 days before they're automatically and permanently deleted. Returns the updated doc object. > 🚧 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. - [Patch doc](https://developers.dovetail.com/reference/patch_v1-docs-doc-id.md): Update a doc's properties. Supports updating the title, custom fields, cover image, and folder location. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. **Note:** `folder_id` and `fields` cannot be updated in the same request. To update the doc content body, create a new doc or use the Dovetail web app. Returns the updated doc object. > 🚧 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. - [Import file to doc](https://developers.dovetail.com/reference/post_v1-docs-import-file.md): 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 > > Only publicly accessible 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). - [Export doc](https://developers.dovetail.com/reference/get_v1-docs-doc-id-export-type.md): Export the content body of a doc in either HTML or Markdown format. Use the `type` path parameter to specify the desired format: `html` or `markdown`. This is the only GET endpoint that returns the **content body** of a doc. **List docs**, **List personal docs**, and **Get doc** return metadata only (no body text). Returns the same identifying fields as **Get doc**, plus either `content_html` or `content_markdown` with the full document content. - [Resolve comment thread](https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments-resolve.md): Resolve the comment thread on a doc. This marks the conversation as resolved. > 🚧 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. - [Unresolve comment thread](https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments-unresolve.md): Unresolve the comment thread on a doc. This reopens the conversation. > 🚧 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. - [List doc comments](https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments.md): Get a list of comments on a doc. Comments are returned in chronological order by default. Only published comments are included. > 🚧 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. - [Create doc comment](https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments.md): Create a comment on a doc. If no comment thread exists on the doc, one will be created automatically. The comment is attributed to the authenticated user. > 🚧 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. - [Get doc comment](https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments-comment-id.md): Get a comment on a doc by id. > 🚧 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. - [Update doc comment](https://developers.dovetail.com/reference/patch_v1-docs-doc-id-comments-comment-id.md): Update a comment on a doc. Only the comment author can update their own comments. > 🚧 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. - [Delete doc comment](https://developers.dovetail.com/reference/delete_v1-docs-doc-id-comments-comment-id.md): Delete a comment on a doc. Only the comment author can delete their own comments. Deleted comments can be restored for up to 30 days. Returns the deleted comment. > 🚧 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. - [List insights](https://developers.dovetail.com/reference/get_v1-insights.md): Retrieve all insights in your workspace. Insights are polished research deliverables β€” written reports that synthesize findings from data entries, highlights, and other sources into actionable recommendations. They can be shared with stakeholders. **Note:** The insights resource is deprecated. New integrations should use **docs** (`/v1/docs`) instead, which provide the same functionality. Existing insight endpoints continue to work but responses include a `Deprecation` header. Results can be filtered by folder, project, title, or creation date. They can be sorted by creation date or title and are paginated. - [Create insight](https://developers.dovetail.com/reference/post_v1-insights.md): 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":""}'`. 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. - [List personal insights](https://developers.dovetail.com/reference/get_v1-insights-user-user-id.md): Retrieve all insights owned by a specific user. Returns insights that were created by or assigned to the specified user. **Note:** This endpoint is deprecated. Insights are no longer owned by individual users β€” they belong to the workspace. Use **List docs** (`GET /v1/docs`) instead. Results support the same filtering, sorting, and pagination as the **List insights** endpoint. - [Get insight](https://developers.dovetail.com/reference/get_v1-insights-insight-id.md): Retrieve a single insight by its unique identifier. Returns the insight's full metadata including title, custom fields, associated project, folder, files, and cover image. **Note:** This endpoint is deprecated. Use **Get doc** (`GET /v1/docs/:doc_id`) instead. To retrieve the actual content body, use the **Export insight** endpoint. > 🚧 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. - [Delete insight](https://developers.dovetail.com/reference/delete_v1-insights-insight-id.md): Delete an insight. The insight is soft-deleted and moved to the project's trash. **Note:** This endpoint is deprecated. Use **Delete doc** (`DELETE /v1/docs/:doc_id`) instead. Deleted insights can be restored for up to 30 days before they are automatically and permanently deleted. Returns the deleted insight object. > 🚧 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. - [Patch insight](https://developers.dovetail.com/reference/patch_v1-insights-insight-id.md): Update an insight's properties. Supports updating the title, custom fields, cover image, and folder location. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. **Note:** This endpoint is deprecated. Use **Patch doc** (`PATCH /v1/docs/:doc_id`) instead. **Note:** `folder_id` and `fields` cannot be updated in the same request. Returns the updated insight object. > 🚧 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. - [Import file to insight](https://developers.dovetail.com/reference/post_v1-insights-import-file.md): 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 > > Only publicly accessible 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). - [Export insight](https://developers.dovetail.com/reference/get_v1-insights-insight-id-export-type.md): Export the content body of an insight in either HTML or Markdown format. Use the `type` path parameter to specify the desired format: `html` or `markdown`. **Note:** This endpoint is deprecated. Use **Export doc** (`GET /v1/docs/:doc_id/export/:type`) instead. This is the only way to retrieve the actual text content of an insight via the API. The **Get insight** endpoint returns metadata only. Returns the insight object with an additional `content_html` or `content_markdown` field containing the full content. - [Resolve comment thread](https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments-resolve.md): Resolve the comment thread on an insight. This marks the conversation as resolved. > 🚧 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. - [Unresolve comment thread](https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments-unresolve.md): Unresolve the comment thread on an insight. This reopens the conversation. > 🚧 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. - [List insight comments](https://developers.dovetail.com/reference/get_v1-insights-insight-id-comments.md): Get a list of comments on an insight. Comments are returned in chronological order by default. Only published comments are included. > 🚧 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. - [Create insight comment](https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments.md): Create a comment on an insight. If no comment thread exists on the insight, one will be created automatically. The comment is attributed to the authenticated user. > 🚧 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. - [Get insight comment](https://developers.dovetail.com/reference/get_v1-insights-insight-id-comments-comment-id.md): Get a comment on an insight by id. > 🚧 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. - [Update insight comment](https://developers.dovetail.com/reference/patch_v1-insights-insight-id-comments-comment-id.md): Update a comment on an insight. Only the comment author can update their own comments. > 🚧 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. - [Delete insight comment](https://developers.dovetail.com/reference/delete_v1-insights-insight-id-comments-comment-id.md): Delete a comment on an insight. Only the comment author can delete their own comments. Deleted comments can be restored for up to 30 days. Returns the deleted comment. > 🚧 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. - [Get contact](https://developers.dovetail.com/reference/get_v1-contacts-contact-id.md): Retrieve a single contact by its unique identifier. Contacts represent people in your contacts database (e.g. interview participants, customers, or research subjects). Returns the contact's name, creation date, and any custom fields. > 🚧 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. - [List contacts](https://developers.dovetail.com/reference/get_v1-contacts.md): Retrieve all contacts in your workspace's contacts database. Contacts represent people such as interview participants, customers, or research subjects. Results can be filtered by name and sorted by creation date or name. They are paginated. > 🚧 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. - [Update contact](https://developers.dovetail.com/reference/patch_v1-contacts-contact-id.md): Update an existing contact's properties. Supports updating the name, email, and custom fields. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. Returns the updated contact object. > 🚧 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. - [Create contact](https://developers.dovetail.com/reference/post_v1-contacts.md): Create a new contact in your workspace's contacts database. Provide a name and email, and optionally attach custom field data (e.g. a Salesforce ID or company name). Contacts can later be linked to data entries and highlights within Dovetail to track which research insights came from which participants. Returns the newly created contact object. > 🚧 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. - [Delete contact](https://developers.dovetail.com/reference/delete_v1-contacts-contact-id.md): Delete a contact. Returns the deleted contact object. > 🚧 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. - [List notes](https://developers.dovetail.com/reference/get_v1-notes.md): Retrieve all data entries (notes) in your workspace. These are documents within a project that capture raw research data such as interview transcripts, survey responses, and session recordings. They are the primary place where highlights and tags are applied. **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use the equivalent **data** endpoints (`/v1/data`) instead, which provide the same functionality with additional features like title filtering. Results can be filtered by folder, project, or creation date. They can be sorted by creation date or title and are paginated. - [Create note](https://developers.dovetail.com/reference/post_v1-notes.md): Create a new data entry (note) within a Dovetail project. Data entries capture raw research data β€” interview transcripts, survey responses, or session recordings. They must be associated with a project via `project_id`. **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use **Create data** (`POST /v1/data`) instead. You can provide the initial content as plain text or HTML via the `content` field, and attach custom field data via the `fields` array. Returns the note object without the content body. > 🚧 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. - [Get note](https://developers.dovetail.com/reference/get_v1-notes-note-id.md): Retrieve a single data entry (note) by its unique identifier. Returns the entry's full metadata including title, custom fields, associated project, folder, and attached files. **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use **Get data** (`GET /v1/data/:data_id`) instead. To retrieve the actual text content, use the **Export note** (`GET /v1/notes/:note_id/export/:type`) endpoint. > 🚧 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. - [Patch note](https://developers.dovetail.com/reference/patch_v1-notes-note-id.md): Update a data entry's (note's) properties. Supports updating the title and custom fields. Only the fields you include in the request body will be modified β€” omitted fields are left unchanged. **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use **Patch data** (`PATCH /v1/data/:data_id`) instead. Returns the updated note object. > 🚧 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. - [Delete note](https://developers.dovetail.com/reference/delete_v1-notes-note-id.md): Delete a note. The note is soft-deleted and moved to the project's trash, but can be restored for up to 30 days before they’re automatically and permanently deleted. Returns the updated note object. > 🚧 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. - [Export note](https://developers.dovetail.com/reference/get_v1-notes-note-id-export-type.md): Export the content body of a data entry (note) in either HTML or Markdown format. Use the `type` path parameter to specify the desired format: `html` or `markdown`. **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use **Export data** (`GET /v1/data/:data_id/export/:type`) instead. This is the only way to retrieve the actual text content of a data entry via the API. The **Get note** endpoint returns metadata only. Returns the note object with an additional `content_html` or `content_markdown` field containing the full content. - [Import file to note](https://developers.dovetail.com/reference/post_v1-notes-import-file.md): Create a new data entry (note) by importing a file from a publicly accessible URL. The entry must be associated with a project via `project_id`. Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV). **Note:** The notes resource has been renamed to **data** in Dovetail. New integrations should use **Import file to data** (`POST /v1/data/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 entry body once processing completes. Returns the newly created note 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 > > Only publicly accessible 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. > 🚧 Fields > > Only existing and unique fields can be referenced. This endpoint will not create new fields, or attempt to differentiate between duplicate field labels. > πŸ“˜ 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). - [Add utterance](https://developers.dovetail.com/reference/post_v1-transcripts-data-id-utterance.md): Add a finalised utterance to a data entry's transcript and broadcast it to connected clients. If the entry has no transcript, one is created automatically. Send finalised utterances only. - [Attach audio](https://developers.dovetail.com/reference/post_v1-transcripts-data-id-audio.md): Attach an already-uploaded audio file to the live transcript on a data entry. The transcript node currently being written to via `appendLiveTranscriptUtterance` or `setLiveTranscript` is wrapped in an audio/video block carrying the supplied `file_id`, giving the editor audio playback + transcript-sync. Idempotent for the same `file_id` (returns 200). Returns 409 if the transcript is already wrapped with a different `file_id`. Returns 404 if the data entry does not exist. - [Set transcript from download URL](https://developers.dovetail.com/reference/put_v1-transcripts-data-id.md): Create or replace a data entry's live transcript by fetching a Recall async transcript JSON from `download_url`, mapping participant names to speaker labels, and writing the result in a single commit. Broadcasts the change to connected clients. A transcript with no usable speech writes a "no speech detected" transcript and returns 200 with `written: 0`, so media can still be attached. Returns 400 if the URL is unsafe, unreachable, or the payload cannot be read. Returns 409 if the transcript is already wrapped in an audio/video block (media has been attached). - [Get user](https://developers.dovetail.com/reference/get_v1-users-user-id.md): Retrieve a single workspace member by their unique identifier. Returns the user's profile information including name, email, job title, role (CONTRIBUTOR, MANAGER, or VIEWER), and whether they are a workspace admin. Use this endpoint to look up details about a specific team member β€” for example, to display author information or resolve user IDs returned by other endpoints. > 🚧 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. - [List users](https://developers.dovetail.com/reference/get_v1-users.md): Retrieve all members of your workspace. Returns each user's profile information including name, email, job title, role, and admin status. Results can be filtered by name or email and sorted by creation date or name. They are paginated. > 🚧 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.