Dovetail

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. via DELETE /v1/channels/{channel_id}

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. via DELETE /v1/channels/topic/{topic_id}

Delete a contact. Returns the deleted contact object. via DELETE /v1/contacts/{contact_id}

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. via DELETE /v1/data/{data_id}

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. via DELETE /v1/docs/{doc_id}

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. via DELETE /v1/docs/{doc_id}/comments/{comment_id}

Delete a field by id. This is a soft delete. via DELETE /v1/fields/{field_id}

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. via DELETE /v1/folders/{folder_id}

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. via DELETE /v1/notes/{note_id}

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. via DELETE /v1/projects/{project_id}

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. via DELETE /v1/projects/{project_id}/context/docs/{doc_id}

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. via DELETE /v1/projects/{project_id}/context/keywords

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. via GET /v1/channels

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). via GET /v1/channels/{channel_id}

Get a list of data points for a channel. via GET /v1/channels/{channel_id}/data

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. via GET /v1/channels/{channel_id}/themes

Get a data point by id. via GET /v1/channels/data/{datum_id}

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. via GET /v1/contacts

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. via GET /v1/contacts/{contact_id}

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. via GET /v1/data

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. via GET /v1/data/{data_id}

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 `<file name> - <page number>` 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. via GET /v1/data/{data_id}/export/{type}

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. via GET /v1/docs

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`). via GET /v1/docs/{doc_id}

Get a list of comments on a doc. Comments are returned in chronological order by default. Only published comments are included. via GET /v1/docs/{doc_id}/comments

Get a comment on a doc by id. via GET /v1/docs/{doc_id}/comments/{comment_id}

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. via GET /v1/docs/{doc_id}/export/{type}

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`). via GET /v1/fields

Get a field by id. via GET /v1/fields/{field_id}

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. via GET /v1/files/{file_id}

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. via GET /v1/files/{file_id}/download

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. via GET /v1/folders

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. via GET /v1/folders/{folder_id}

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. via GET /v1/folders/{folder_id}/contents

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. via GET /v1/highlights

Retrieve a single highlight by its unique identifier. Returns the highlight's text content, associated data entry, tags, and time range (for transcript highlights). via GET /v1/highlights/{highlight_id}

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. via GET /v1/notes

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. via GET /v1/notes/{note_id}

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. via GET /v1/notes/{note_id}/export/{type}

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. via GET /v1/projects

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. via GET /v1/projects/{project_id}

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. via GET /v1/projects/{project_id}/context

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. via GET /v1/projects/templates

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 is either a project tag (belonging to a single project) or a workspace tag (belonging to a workspace tag board and usable across all projects linked to that board) — see the `scope` field on each tag. Results can be filtered by project and tag board, and sorted by creation date. They are paginated. via GET /v1/tags

Retrieve tag boards in your workspace. A tag board holds the tags (and tag groups) used to categorize highlights — every project has its own board, and a workspace can additionally have workspace tag boards whose tags are shared across all projects linked to them. By default the workspace's shared tag boards are returned. Pass a `project_id` filter to list a single project's own tag board instead. Each board includes its tag count and its tag groups (with each group's tag count), in display order. Results are paginated and can be sorted by creation date. via GET /v1/tags/boards

Retrieve a single tag by its unique identifier. Returns the tag's title, scope (`project` or `workspace`), the project it belongs to, its workspace tag board (for workspace tags), and its creation date. via GET /v1/tags/{tag_id}

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. via GET /v1/token/info

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. via GET /v1/users

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. via GET /v1/users/{user_id}

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. via PATCH /v1/channels/{channel_id}

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. via PATCH /v1/channels/topic/{topic_id}

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. via PATCH /v1/contacts/{contact_id}

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. via PATCH /v1/data/{data_id}

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. via PATCH /v1/docs/{doc_id}

Update a comment on a doc. Only the comment author can update their own comments. via PATCH /v1/docs/{doc_id}/comments/{comment_id}

Update a field by id. via PATCH /v1/fields/{field_id}

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. via PATCH /v1/folders/{folder_id}

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. via PATCH /v1/notes/{note_id}

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. via PATCH /v1/projects/{project_id}

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. via POST /v1/channels

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. via POST /v1/channels/data

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. via POST /v1/channels/topic

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. via POST /v1/contacts

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. via POST /v1/data

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). > 🚧 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. > 🚧 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). via POST /v1/data/import/file

Send a new data point to a dataset, without it having to belong to a channel. A dataset is one connection under a source — the same thing shown as a dataset in the Dovetail UI. Sending data here lets a push-based source (such as the API or Zapier) ingest before any channel subscribes to it. Field values are captured against the source as the data arrives, so once a channel does subscribe, the data is already filterable. No `url` is returned. Until a channel subscribes to the source, the data point has no page in Dovetail to link to. via POST /v1/dataset/{data_connector_id}/data

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":"<user-uuid>"}'`. The span's inner text is used as the fallback label if the user cannot be resolved. When the id resolves to a live workspace user, the span is replaced with a live mention node on import. Unresolved ids degrade gracefully to plain text — the import does not fail. via POST /v1/docs

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. via POST /v1/docs/{doc_id}/comments

Resolve the comment thread on a doc. This marks the conversation as resolved. via POST /v1/docs/{doc_id}/comments/resolve

Unresolve the comment thread on a doc. This reopens the conversation. via POST /v1/docs/{doc_id}/comments/unresolve

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). > 🚧 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). via POST /v1/docs/import/file

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`. via POST /v1/fields

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. via POST /v1/folders

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 `<span>` 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. via POST /v1/highlights

Apply one or more tags (up to 10 per request) to a highlight. Tags are labels used to categorize highlights during qualitative analysis (e.g. "Usability Issue", "Feature Request"). Each tag must belong to the highlight's project, or to a workspace tag board linked to that project. Discover tag IDs via **List tags** (or create one via **Create tag**) and highlight IDs via **List highlights**. If any tag ID is invalid or does not belong to the highlight's project, the request fails and no tags are applied — the response names the offending tag IDs. Applying a tag the highlight already has is a no-op. Only highlights on data entries can be tagged: a range carried by a doc/insight, or one that is an inline comment rather than a highlight, is rejected with a 400 and will never become taggable — do not retry it. Returns the updated highlight, including its full tag list. via POST /v1/highlights/{highlight_id}/tags

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. via POST /v1/notes

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). > 🚧 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. > 🚧 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). via POST /v1/notes/import/file

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. via POST /v1/projects

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. via POST /v1/projects/{project_id}/context/docs

Add one or more keywords to the project's AI context. Duplicate keywords are ignored. Returns the full updated list of keywords. via POST /v1/projects/{project_id}/context/keywords

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. via POST /v1/search

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. via POST /v1/summarize

Create a new tag. Tags are labels used to categorize highlights — for example "Usability Issue", "Feature Request", or "Positive Feedback". Pass `project_id` to create a project tag in that project. Omit it to create a workspace tag on a workspace tag board — workspace tags can be applied to highlights in every project linked to that board. Creating workspace tags requires a plan with workspace tags enabled. By default the tag is created in the first group of the first tag board in the project or workspace. Pass `tag_board_id` and/or `group_id` to target a specific board or group (discover IDs via **List tag boards**). If the workspace has no tag board, create one in the Dovetail web app first. 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. via POST /v1/tags

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. via POST /v1/transcripts/{data_id}/audio

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. via POST /v1/transcripts/{data_id}/utterance

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. via POST /v2/files/{file_id}/large-upload/complete

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. via POST /v2/files/{file_id}/upload/complete

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. via POST /v2/files/large-upload

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 "<upload_url>" \ -H "x-amz-server-side-encryption: aws:kms" \ -H "Content-Type: <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. via POST /v2/files/upload

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. via POST /v2/search

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). via PUT /v1/transcripts/{data_id}