openapi: 3.2.0 info: title: Dovetail Public Highlights API version: 0.0.1 description: The Dovetail Public API provides programmatic access to your Dovetail workspace. servers: - url: https://dovetail.com/api - url: https://dovetailapp.com/api security: - bearerAuth: [] tags: - name: Highlights paths: /v1/highlights: get: description: '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.' summary: List highlights tags: - Highlights parameters: - name: page in: query description: See [Pagination](https://developers.dovetail.com/docs/pagination) for details about how to use a cursor to iterate through the list. style: deepObject schema: default: limit: 100 type: object properties: start_cursor: type: string limit: default: 100 type: - integer - 'null' minimum: 0 maximum: 100 - name: sort in: query description: See [Sort](https://developers.dovetail.com/docs/sort) for details on the sort parameter. schema: default: created_at:desc oneOf: - type: string enum: - created_at:asc - created_at:desc - type: array items: type: string enum: - created_at:asc - created_at:desc - name: filter in: query description: You may only use one of project_id, tag_id or highlight_id as a filter parameter. See [Filters](https://developers.dovetail.com/docs/filters) for details on parameter formatting. schema: type: object properties: created_at: type: object properties: gt: type: - string - 'null' format: date-time description: Great than operator gte: type: - string - 'null' format: date-time description: Great than or equal to operator lt: type: - string - 'null' format: date-time description: Less than operator lte: type: - string - 'null' format: date-time description: Less than or equal operator description: Filter results based on dates. When passing in operators, the operator pairs are mutually exclusive. For example, you cannot send both `gt` and `gte` in the same request. updated_at: type: object properties: gt: type: - string - 'null' format: date-time description: Great than operator gte: type: - string - 'null' format: date-time description: Great than or equal to operator lt: type: - string - 'null' format: date-time description: Less than operator lte: type: - string - 'null' format: date-time description: Less than or equal operator description: Filter results based on dates. When passing in operators, the operator pairs are mutually exclusive. For example, you cannot send both `gt` and `gte` in the same request. project_id: oneOf: - type: string - type: array items: type: string description: Unique identifier(s) of the associated project(s) highlight_id: oneOf: - type: string - type: array items: type: string description: Unique identifier(s) of the associated highlight(s) tag_id: oneOf: - type: string - type: array items: type: string description: Unique identifier(s) for associated tag(s) additionalProperties: false responses: '200': description: '200' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string url: type: - string - 'null' description: The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice. note_id: type: - string - 'null' tags: type: array items: type: object properties: id: type: string title: type: string required: - id - title text: type: - string - 'null' type: type: string enum: - highlight start_time: type: - number - 'null' end_time: type: - number - 'null' created_at: type: string updated_at: type: string required: - id - note_id - tags - text - type - start_time - end_time - created_at - updated_at page: type: object properties: total_count: type: number description: Total number of items matching the query. has_more: type: boolean description: Whether there are more items beyond the current page. next_cursor: type: - string - 'null' description: Cursor to pass as `page[start_cursor]` to fetch the next page. Null when there are no more results. required: - total_count - has_more - next_cursor required: - data - page '400': description: '400' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - ValidationError title: type: string enum: - Contract violation message: type: string path: type: string required: - code - title - message - path required: - errors '401': description: '401' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - Unauthorized title: type: string message: type: string required: - code - title required: - errors '403': description: '403' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - Forbidden title: type: string message: type: string required: - code - title - type: object properties: code: type: string enum: - IpNotAllowlisted title: type: string message: type: string decisionId: type: string description: Correlation id quoting this enforcement decision — include it when contacting support. required: - code - title - decisionId required: - errors '404': description: '404' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - NotFound title: type: string message: type: string required: - code - title required: - errors '422': description: '422' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - UnprocessableContent title: type: string message: type: string required: - code - title - message required: - errors '429': description: '429' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - TooManyRequests title: type: string message: type: string required: - code - title required: - errors '500': description: '500' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - InternalError title: type: string enum: - Internal server error message: type: string required: - code - title required: - errors operationId: getV1Highlights x-operation-id-source: derived post: description: '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.' summary: Create transcript highlight tags: - Highlights parameters: [] requestBody: description: Body content: application/json: schema: type: object properties: note_id: type: string description: Unique identifier of the data entry (note) containing the transcript. start_time: type: number minimum: 0 description: Start time in seconds within the transcript to begin the highlight. example: 10.5 end_time: type: number minimum: 0 description: End time in seconds within the transcript to end the highlight. example: 25.3 tag_ids: type: array items: type: string description: Optional list of tag IDs to associate with the highlight. required: - note_id - start_time - end_time responses: '201': description: '201' content: application/json: schema: type: object properties: data: type: object properties: id: type: string url: type: - string - 'null' description: The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice. note_id: type: - string - 'null' tags: type: array items: type: object properties: id: type: string title: type: string required: - id - title text: type: - string - 'null' type: type: string enum: - highlight start_time: type: - number - 'null' end_time: type: - number - 'null' created_at: type: string updated_at: type: string required: - id - note_id - tags - text - type - start_time - end_time - created_at - updated_at required: - data '400': description: '400' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - InvalidOperation title: type: string message: type: string path: type: string required: - code - title - type: object properties: code: type: string enum: - ValidationError title: type: string enum: - Contract violation message: type: string path: type: string required: - code - title - message - path required: - errors '401': description: '401' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - Unauthorized title: type: string message: type: string required: - code - title required: - errors '403': description: '403' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - Forbidden title: type: string message: type: string required: - code - title - type: object properties: code: type: string enum: - IpNotAllowlisted title: type: string message: type: string decisionId: type: string description: Correlation id quoting this enforcement decision — include it when contacting support. required: - code - title - decisionId required: - errors '404': description: '404' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - NotFound title: type: string message: type: string required: - code - title required: - errors '422': description: '422' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - UnprocessableContent title: type: string message: type: string required: - code - title - message required: - errors '429': description: '429' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - TooManyRequests title: type: string message: type: string required: - code - title required: - errors '500': description: '500' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - InternalError title: type: string enum: - Internal server error message: type: string required: - code - title required: - errors operationId: postV1Highlights x-operation-id-source: derived /v1/highlights/{highlight_id}: get: description: '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.' summary: Get highlight tags: - Highlights parameters: - name: highlight_id in: path required: true schema: type: string description: Unique identifier of the highlight. responses: '200': description: '200' content: application/json: schema: type: object properties: data: type: object properties: id: type: string url: type: - string - 'null' description: The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice. note_id: type: - string - 'null' tags: type: array items: type: object properties: id: type: string title: type: string required: - id - title text: type: - string - 'null' type: type: string enum: - highlight start_time: type: - number - 'null' end_time: type: - number - 'null' created_at: type: string updated_at: type: string required: - id - note_id - tags - text - type - start_time - end_time - created_at - updated_at required: - data '400': description: '400' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - ValidationError title: type: string enum: - Contract violation message: type: string path: type: string required: - code - title - message - path required: - errors '401': description: '401' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - Unauthorized title: type: string message: type: string required: - code - title required: - errors '403': description: '403' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - Forbidden title: type: string message: type: string required: - code - title - type: object properties: code: type: string enum: - IpNotAllowlisted title: type: string message: type: string decisionId: type: string description: Correlation id quoting this enforcement decision — include it when contacting support. required: - code - title - decisionId required: - errors '404': description: '404' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - NotFound title: type: string message: type: string required: - code - title required: - errors '422': description: '422' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - UnprocessableContent title: type: string message: type: string required: - code - title - message required: - errors '429': description: '429' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - TooManyRequests title: type: string message: type: string required: - code - title required: - errors '500': description: '500' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - InternalError title: type: string enum: - Internal server error message: type: string required: - code - title required: - errors operationId: getV1HighlightsByHighlightId x-operation-id-source: derived /v1/highlights/{highlight_id}/tags: post: description: '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.' summary: Apply tags to highlight tags: - Highlights parameters: - name: highlight_id in: path required: true schema: type: string description: Unique identifier of the highlight. requestBody: description: Body content: application/json: schema: type: object properties: tag_ids: type: array items: type: string minItems: 1 maxItems: 10 description: Unique identifiers of the tags to apply to the highlight. At most 10 tags can be applied per request. required: - tag_ids responses: '200': description: '200' content: application/json: schema: type: object properties: data: type: object properties: id: type: string url: type: - string - 'null' description: The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice. note_id: type: - string - 'null' tags: type: array items: type: object properties: id: type: string title: type: string required: - id - title text: type: - string - 'null' type: type: string enum: - highlight start_time: type: - number - 'null' end_time: type: - number - 'null' created_at: type: string updated_at: type: string required: - id - note_id - tags - text - type - start_time - end_time - created_at - updated_at required: - data '400': description: '400' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - InvalidOperation title: type: string message: type: string path: type: string required: - code - title - type: object properties: code: type: string enum: - ValidationError title: type: string enum: - Contract violation message: type: string path: type: string required: - code - title - message - path required: - errors '401': description: '401' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - Unauthorized title: type: string message: type: string required: - code - title required: - errors '403': description: '403' content: application/json: schema: type: object properties: errors: type: array items: oneOf: - type: object properties: code: type: string enum: - Forbidden title: type: string message: type: string required: - code - title - type: object properties: code: type: string enum: - IpNotAllowlisted title: type: string message: type: string decisionId: type: string description: Correlation id quoting this enforcement decision — include it when contacting support. required: - code - title - decisionId required: - errors '404': description: '404' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - NotFound title: type: string message: type: string required: - code - title required: - errors '422': description: '422' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - UnprocessableContent title: type: string message: type: string required: - code - title - message required: - errors '429': description: '429' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - TooManyRequests title: type: string message: type: string required: - code - title required: - errors '500': description: '500' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - InternalError title: type: string enum: - Internal server error message: type: string required: - code - title required: - errors operationId: postV1HighlightsByHighlightIdTags x-operation-id-source: derived components: securitySchemes: bearerAuth: type: http scheme: bearer x-provenance: method: searched source: https://developers.dovetail.com/reference harvested: '2026-10-14' tool: harvest-readme-openapi.py note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored. assembled_from: - https://developers.dovetail.com/reference/delete_v1-channels-channel-id.md - https://developers.dovetail.com/reference/delete_v1-channels-topic-topic-id.md - https://developers.dovetail.com/reference/delete_v1-contacts-contact-id.md - https://developers.dovetail.com/reference/delete_v1-data-data-id.md - https://developers.dovetail.com/reference/delete_v1-docs-doc-id-comments-comment-id.md - https://developers.dovetail.com/reference/delete_v1-docs-doc-id.md - https://developers.dovetail.com/reference/delete_v1-fields-field-id.md - https://developers.dovetail.com/reference/delete_v1-folders-folder-id.md - https://developers.dovetail.com/reference/delete_v1-insights-insight-id-comments-comment-id.md - https://developers.dovetail.com/reference/delete_v1-insights-insight-id.md - https://developers.dovetail.com/reference/delete_v1-notes-note-id.md - https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-docs-doc-id.md - https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-keywords.md - https://developers.dovetail.com/reference/delete_v1-projects-project-id.md - https://developers.dovetail.com/reference/get_v1-channels-channel-id-data.md - https://developers.dovetail.com/reference/get_v1-channels-channel-id-themes.md - https://developers.dovetail.com/reference/get_v1-channels-channel-id.md - https://developers.dovetail.com/reference/get_v1-channels-data-datum-id.md - https://developers.dovetail.com/reference/get_v1-channels.md - https://developers.dovetail.com/reference/get_v1-contacts-contact-id.md - https://developers.dovetail.com/reference/get_v1-contacts.md - https://developers.dovetail.com/reference/get_v1-data-data-id-export-type.md - https://developers.dovetail.com/reference/get_v1-data-data-id.md - https://developers.dovetail.com/reference/get_v1-data.md - https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments-comment-id.md - https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments.md - https://developers.dovetail.com/reference/get_v1-docs-doc-id-export-type.md - https://developers.dovetail.com/reference/get_v1-docs-doc-id.md - https://developers.dovetail.com/reference/get_v1-docs-user-user-id.md - https://developers.dovetail.com/reference/get_v1-docs.md - https://developers.dovetail.com/reference/get_v1-fields-field-id.md - https://developers.dovetail.com/reference/get_v1-fields.md - https://developers.dovetail.com/reference/get_v1-files-file-id-download.md - https://developers.dovetail.com/reference/get_v1-files-file-id.md - https://developers.dovetail.com/reference/get_v1-folders-folder-id-contents.md - https://developers.dovetail.com/reference/get_v1-folders-folder-id.md - https://developers.dovetail.com/reference/get_v1-folders.md - https://developers.dovetail.com/reference/get_v1-highlights-highlight-id.md - https://developers.dovetail.com/reference/get_v1-highlights.md - https://developers.dovetail.com/reference/get_v1-insights-insight-id-comments-comment-id.md - https://developers.dovetail.com/reference/get_v1-insights-insight-id-comments.md - https://developers.dovetail.com/reference/get_v1-insights-insight-id-export-type.md - https://developers.dovetail.com/reference/get_v1-insights-insight-id.md - https://developers.dovetail.com/reference/get_v1-insights-user-user-id.md - https://developers.dovetail.com/reference/get_v1-insights.md - https://developers.dovetail.com/reference/get_v1-notes-note-id-export-type.md - https://developers.dovetail.com/reference/get_v1-notes-note-id.md - https://developers.dovetail.com/reference/get_v1-notes.md - https://developers.dovetail.com/reference/get_v1-projects-project-id-context.md - https://developers.dovetail.com/reference/get_v1-projects-project-id.md - https://developers.dovetail.com/reference/get_v1-projects-templates.md - https://developers.dovetail.com/reference/get_v1-projects.md - https://developers.dovetail.com/reference/get_v1-tags-boards.md - https://developers.dovetail.com/reference/get_v1-tags-tag-id.md - https://developers.dovetail.com/reference/get_v1-tags.md - https://developers.dovetail.com/reference/get_v1-token-info.md - https://developers.dovetail.com/reference/get_v1-users-user-id.md - https://developers.dovetail.com/reference/get_v1-users.md - https://developers.dovetail.com/reference/get_v1-workspace-context.md - https://developers.dovetail.com/reference/patch_v1-channels-channel-id.md - https://developers.dovetail.com/reference/patch_v1-channels-topic-topic-id.md - https://developers.dovetail.com/reference/patch_v1-contacts-contact-id.md - https://developers.dovetail.com/reference/patch_v1-data-data-id.md - https://developers.dovetail.com/reference/patch_v1-docs-doc-id-comments-comment-id.md - https://developers.dovetail.com/reference/patch_v1-docs-doc-id.md - https://developers.dovetail.com/reference/patch_v1-fields-field-id.md - https://developers.dovetail.com/reference/patch_v1-folders-folder-id.md - https://developers.dovetail.com/reference/patch_v1-insights-insight-id-comments-comment-id.md - https://developers.dovetail.com/reference/patch_v1-insights-insight-id.md - https://developers.dovetail.com/reference/patch_v1-notes-note-id.md - https://developers.dovetail.com/reference/patch_v1-projects-project-id.md - https://developers.dovetail.com/reference/post_v1-channels-data.md - https://developers.dovetail.com/reference/post_v1-channels-topic.md - https://developers.dovetail.com/reference/post_v1-channels.md - https://developers.dovetail.com/reference/post_v1-contacts.md - https://developers.dovetail.com/reference/post_v1-data-import-file.md - https://developers.dovetail.com/reference/post_v1-data.md - https://developers.dovetail.com/reference/post_v1-dataset-dataset-id-data.md - https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments-resolve.md - https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments-unresolve.md - https://developers.dovetail.com/reference/post_v1-docs-doc-id-comments.md - https://developers.dovetail.com/reference/post_v1-docs-import-file.md - https://developers.dovetail.com/reference/post_v1-docs.md - https://developers.dovetail.com/reference/post_v1-fields.md - https://developers.dovetail.com/reference/post_v1-files.md - https://developers.dovetail.com/reference/post_v1-folders.md - https://developers.dovetail.com/reference/post_v1-highlights-highlight-id-tags.md - https://developers.dovetail.com/reference/post_v1-highlights.md - https://developers.dovetail.com/reference/post_v1-insights-import-file.md - https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments-resolve.md - https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments-unresolve.md - https://developers.dovetail.com/reference/post_v1-insights-insight-id-comments.md - https://developers.dovetail.com/reference/post_v1-insights.md - https://developers.dovetail.com/reference/post_v1-notes-import-file.md - https://developers.dovetail.com/reference/post_v1-notes.md - https://developers.dovetail.com/reference/post_v1-projects-project-id-context-docs.md - https://developers.dovetail.com/reference/post_v1-projects-project-id-context-keywords.md - https://developers.dovetail.com/reference/post_v1-projects-project-id-workspace-field-groups.md - https://developers.dovetail.com/reference/post_v1-projects.md - https://developers.dovetail.com/reference/post_v1-search.md - https://developers.dovetail.com/reference/post_v1-summarize.md - https://developers.dovetail.com/reference/post_v1-tags.md - https://developers.dovetail.com/reference/post_v1-transcripts-data-id-audio.md - https://developers.dovetail.com/reference/post_v1-transcripts-data-id-utterance.md - https://developers.dovetail.com/reference/post_v1-workspace-context-docs.md - https://developers.dovetail.com/reference/post_v2-files-file-id-large-upload-complete.md - https://developers.dovetail.com/reference/post_v2-files-file-id-upload-complete.md - https://developers.dovetail.com/reference/post_v2-files-large-upload.md - https://developers.dovetail.com/reference/post_v2-files-upload.md - https://developers.dovetail.com/reference/post_v2-search.md - https://developers.dovetail.com/reference/put_v1-transcripts-data-id.md merge: pages: 111 deduped: 110 conflicts_kept_first: 0