Skip to content
Changelog

Report a bug

Dovetail integration: operations for AI agents

Dovetail connects to Type.com as an integration. This page lists the 111 operations documented for Claude and Codex in Type.com: 48 read, 49 write, 14 destructive.

About Dovetail

Dovetail is an Australian software company that provides tools for transcription analysis, coding interpretation of interviews, survey responses, and feedback, enabling users to create summarized insights from their research analysis.

Categories: Analytics & Data

How to connect Dovetail to Type.com

Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

111 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

111 operations listed.

Channels

  • Read

    List channel data points

    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 /v1/channels/{channel_id}/data

  • Read

    List channel themes

    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.

    GET /v1/channels/{channel_id}/themes

  • Read

    Get channel

    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.

    GET /v1/channels/{channel_id}

  • Read

    Get data point

    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.

    GET /v1/channels/data/{datum_id}

  • Read

    List channels

    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 /v1/channels

  • Write

    Patch channel

    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.

    PATCH /v1/channels/{channel_id}

  • Write

    Patch topic

    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.

    PATCH /v1/channels/topic/{topic_id}

  • Write

    Create data point

    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.

    POST /v1/channels/data

  • Write

    Create topic

    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.

    POST /v1/channels/topic

  • Write

    Create channel

    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.

    POST /v1/channels

  • Destructive

    Delete channel

    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.

    DELETE /v1/channels/{channel_id}

  • Destructive

    Delete topic

    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.

    DELETE /v1/channels/topic/{topic_id}

Contacts

  • Read

    Get contact

    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.

    GET /v1/contacts/{contact_id}

  • Read

    List contacts

    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.

    GET /v1/contacts

  • Write

    Update contact

    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.

    PATCH /v1/contacts/{contact_id}

  • Write

    Create contact

    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.

    POST /v1/contacts

  • Destructive

    Delete contact

    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.

    DELETE /v1/contacts/{contact_id}

Data

  • Read

    Export data

    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.

    GET /v1/data/{data_id}/export/{type}

  • Read

    Get 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, attached files, and `speakers` (contacts and workspace users linked as transcript speakers), 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.

    GET /v1/data/{data_id}

  • Read

    List data

    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.

    GET /v1/data

  • Write

    Patch data

    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.

    PATCH /v1/data/{data_id}

  • Write

    Import file to 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). > 🚧 Permissions > > Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates. > 🚧 Supported URLs > > The URL must use HTTPS and resolve to a public address; Dovetail rejects URLs that point to private, loopback, or link-local addresses. Only URLs that link directly to a downloadable file are supported. If the URL does not include a file extension, you must provide the `mime_type` parameter so Dovetail can determine how to process the file. > 🚧 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.

    POST /v1/data/import/file

  • Write

    Create data

    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.

    POST /v1/data

  • Destructive

    Delete data

    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.

    DELETE /v1/data/{data_id}

DocComments

  • Read

    Get doc comment

    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.

    GET /v1/docs/{doc_id}/comments/{comment_id}

  • Read

    List doc comments

    Get a list of page-level and inline comments on a doc. Pass `?include_text_range=true` to include the selected text and surrounding context for inline comments. By default the list returns comment text only. 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.

    GET /v1/docs/{doc_id}/comments

  • Write

    Update doc comment

    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.

    PATCH /v1/docs/{doc_id}/comments/{comment_id}

  • Write

    Resolve comment thread

    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.

    POST /v1/docs/{doc_id}/comments/resolve

  • Write

    Unresolve comment thread

    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.

    POST /v1/docs/{doc_id}/comments/unresolve

  • Write

    Create doc comment

    Create a comment on a doc. If no comment thread exists on the doc, one will be created automatically. Pass optional `thread_id` to reply on an existing page-level or inline thread. 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.

    POST /v1/docs/{doc_id}/comments

  • Destructive

    Delete doc comment

    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.

    DELETE /v1/docs/{doc_id}/comments/{comment_id}

Docs

  • Read

    Export doc

    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.

    GET /v1/docs/{doc_id}/export/{type}

  • Read

    Get doc

    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.

    GET /v1/docs/{doc_id}

  • Read

    List personal docs (deprecated)

    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 /v1/docs/user/{user_id}

  • Read

    List docs

    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.

    GET /v1/docs

  • Write

    Patch doc

    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.

    PATCH /v1/docs/{doc_id}

  • Write

    Import file to doc

    Create a new doc by importing a file. Provide the file in **exactly one** of two ways: - `url` β€” a publicly accessible URL that Dovetail downloads and imports, or - `file_id` β€” the id of a file you have already uploaded via the file upload API (the upload must be complete). Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV). If the imported file is audio or video, Dovetail will automatically queue it for transcription. The resulting transcript will be added to the doc body once processing completes. The doc can be placed inside a project (via `project_id`) or a folder (via `folder_id`), but not both. `mime_type` is only used when importing from `url`; it is ignored when importing by `file_id` (the file already carries its own metadata). Returns the newly created doc object (without content). > 🚧 Permissions > > Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates. > 🚧 Supported URLs > > The URL must use HTTPS and resolve to a public address; Dovetail rejects URLs that point to private, loopback, or link-local addresses. Only URLs that link directly to a downloadable file are supported. If the URL does not include a file extension, you must provide the `mime_type` parameter so Dovetail can determine how to process the file. > πŸ“˜ Transcription notifications > > When a transcription completes or fails, the account linked to the API token will receive a notification. You can manage notification preferences in notification settings.

    POST /v1/docs/import/file

  • Write

    Create doc

    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.

    POST /v1/docs

  • Destructive

    Delete doc

    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.

    DELETE /v1/docs/{doc_id}

Fields

  • Read

    Get field

    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.

    GET /v1/fields/{field_id}

  • Read

    List fields

    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`).

    GET /v1/fields

  • Write

    Update field

    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.

    PATCH /v1/fields/{field_id}

  • Write

    Create field

    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.

    POST /v1/fields

  • Destructive

    Delete field

    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.

    DELETE /v1/fields/{field_id}

Folders

  • Read

    Get folder contents

    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.

    GET /v1/folders/{folder_id}/contents

  • Read

    Get folder

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

  • Read

    List folders

    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 /v1/folders

  • Write

    Patch folder

    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.

    PATCH /v1/folders/{folder_id}

  • Write

    Create folder

    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.

    POST /v1/folders

  • Destructive

    Delete folder

    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.

    DELETE /v1/folders/{folder_id}

InsightComments

  • Read

    Get insight comment (deprecated)

    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.

    GET /v1/insights/{insight_id}/comments/{comment_id}

  • Read

    List insight comments (deprecated)

    Get a list of page-level and inline comments on an insight. Pass `?include_text_range=true` to include the selected text and surrounding context for inline comments. By default the list returns comment text only. 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.

    GET /v1/insights/{insight_id}/comments

  • Write

    Update insight comment (deprecated)

    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.

    PATCH /v1/insights/{insight_id}/comments/{comment_id}

  • Write

    Resolve comment thread (deprecated)

    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.

    POST /v1/insights/{insight_id}/comments/resolve

  • Write

    Unresolve comment thread (deprecated)

    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.

    POST /v1/insights/{insight_id}/comments/unresolve

  • Write

    Create insight comment (deprecated)

    Create a comment on an insight. If no page-level comment thread exists on the insight, one will be created automatically unless `thread_id` is set. Pass `thread_id` from list or get comments to append a reply to that page-level or inline thread. 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.

    POST /v1/insights/{insight_id}/comments

  • Destructive

    Delete insight comment (deprecated)

    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.

    DELETE /v1/insights/{insight_id}/comments/{comment_id}

Insights

  • Read

    Export insight (deprecated)

    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.

    GET /v1/insights/{insight_id}/export/{type}

  • Read

    Get insight (deprecated)

    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.

    GET /v1/insights/{insight_id}

  • Read

    List personal insights (deprecated)

    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 /v1/insights/user/{user_id}

  • Read

    List insights (deprecated)

    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.

    GET /v1/insights

  • Write

    Patch insight (deprecated)

    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.

    PATCH /v1/insights/{insight_id}

  • Write

    Import file to insight (deprecated)

    Create a new insight by importing a file from a publicly accessible URL. Supported file types include documents (PDF, DOCX), audio files (MP3, WAV, M4A), and video files (MP4, MOV). **Note:** This endpoint is deprecated. Use **Import file to doc** (`POST /v1/docs/import/file`) instead. If the imported file is audio or video, Dovetail will automatically queue it for transcription. The resulting transcript will be added to the insight body once processing completes. The insight can be placed inside a project (via `project_id`) or a folder (via `folder_id`), but not both. Returns the newly created insight object (without content). > 🚧 Permissions > > Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates. > 🚧 Supported URLs > > The URL must use HTTPS and resolve to a public address; Dovetail rejects URLs that point to private, loopback, or link-local addresses. Only URLs that link directly to a downloadable file are supported. If the URL does not include a file extension, you must provide the `mime_type` parameter so Dovetail can determine how to process the file. > πŸ“˜ Transcription notifications > > When a transcription completes or fails, the account linked to the API token will receive a notification. You can manage notification preferences in notification settings.

    POST /v1/insights/import/file

  • Write

    Create insight (deprecated)

    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.

    POST /v1/insights

  • Destructive

    Delete insight (deprecated)

    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.

    DELETE /v1/insights/{insight_id}

Notes

  • Read

    Export note

    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.

    GET /v1/notes/{note_id}/export/{type}

  • Read

    Get note

    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.

    GET /v1/notes/{note_id}

  • Read

    List notes

    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.

    GET /v1/notes

  • Write

    Patch note

    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.

    PATCH /v1/notes/{note_id}

  • Write

    Import file to note

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

    POST /v1/notes/import/file

  • Write

    Create note

    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.

    POST /v1/notes

  • Destructive

    Delete note

    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.

    DELETE /v1/notes/{note_id}

Projects

  • Read

    Get project context

    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.

    GET /v1/projects/{project_id}/context

  • Read

    Get project

    Retrieve a single project by its unique identifier. Returns the project's metadata including title, author, creation date, folder location, and overview content in Markdown format. 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.

    GET /v1/projects/{project_id}

  • Read

    List project templates

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

  • Read

    List projects

    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.

    GET /v1/projects

  • Write

    Patch project

    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.

    PATCH /v1/projects/{project_id}

  • Write

    Add project context doc

    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.

    POST /v1/projects/{project_id}/context/docs

  • Write

    Add project context keywords

    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.

    POST /v1/projects/{project_id}/context/keywords

  • Write

    Link workspace field group

    Link a workspace field group to a project so the group's fields are available on that project's data and docs. For callers with write permission, linking the same group twice is a no-op. Returns `200` when the preflight lookup finds an existing link. Otherwise, returns `201` after the create attempt succeeds; concurrent first-time requests may therefore both return `201`. > 🚧 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.

    POST /v1/projects/{project_id}/workspace-field-groups

  • Write

    Create project

    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.

    POST /v1/projects

  • Destructive

    Remove project context doc

    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.

    DELETE /v1/projects/{project_id}/context/docs/{doc_id}

  • Destructive

    Remove project context keywords

    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.

    DELETE /v1/projects/{project_id}/context/keywords

  • Destructive

    Delete project

    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.

    DELETE /v1/projects/{project_id}

Files

  • Read

    Download a file

    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.

    GET /v1/files/{file_id}/download

  • Read

    Get file by 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.

    GET /v1/files/{file_id}

  • Write

    Upload a file (deprecated) (deprecated)

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

    POST /v1/files/

Highlights

  • Read

    Get highlight

    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.

    GET /v1/highlights/{highlight_id}

  • Read

    List highlights

    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 /v1/highlights

  • Write

    Apply tags to highlight

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

    POST /v1/highlights/{highlight_id}/tags

  • Write

    Create transcript highlight

    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.

    POST /v1/highlights

Tags

  • Read

    List tag boards

    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.

    GET /v1/tags/boards

  • Read

    Get tag

    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. > 🚧 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 /v1/tags/{tag_id}

  • Read

    List tags

    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.

    GET /v1/tags

  • Write

    Create tag

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

    POST /v1/tags

Authentication

  • Read

    Token info

    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.

    GET /v1/token/info

Users

  • Read

    Get user

    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.

    GET /v1/users/{user_id}

  • Read

    List users

    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.

    GET /v1/users

Workspace

  • Read

    Get workspace context

    Retrieve the AI context for the workspace: linked insight docs used as source material for workspace-wide AI features.

    GET /v1/workspace/context

  • Write

    Add workspace context doc

    Add an insight to the workspace's AI context. A workspace can have at most 10 context docs. If the insight is already linked, this is a no-op. Requires a workspace administrator. 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.

    POST /v1/workspace/context/docs

Datasets

  • Write

    Create data point on a dataset

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

    POST /v1/dataset/{dataset_id}/data

Search

  • Read

    Magic Search

    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.

    POST /v1/search

Summarize

  • Read

    Magic Summarize

    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.

    POST /v1/summarize

Transcripts

  • Write

    Attach audio

    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.

    POST /v1/transcripts/{data_id}/audio

  • Write

    Add utterance

    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.

    POST /v1/transcripts/{data_id}/utterance

  • Write

    Set transcript from download URL

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

    PUT /v1/transcripts/{data_id}

FilesV2

  • Write

    Finalize a large (multipart) file upload

    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.

    POST /v2/files/{file_id}/large-upload/complete

  • Write

    Finalize a single-PUT file upload

    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.

    POST /v2/files/{file_id}/upload/complete

  • Write

    Initiate a large (multipart) file upload

    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.

    POST /v2/files/large-upload

  • Write

    Initiate a single-PUT file 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 " " \ -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.

    POST /v2/files/upload

SearchV2

  • Read

    Search V2

    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.

    POST /v2/search

See How connections work for access and permissions, or browse all integrations.