--- updatedAt: 2026-06-01T04:35:17.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # 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. # OpenAPI definition ```json { "openapi": "3.0.2", "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.\n\nResults 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", "minimum": 0, "maximum": 100, "nullable": true } } } }, { "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", "format": "date-time", "nullable": true, "description": "Great than operator" }, "gte": { "type": "string", "format": "date-time", "nullable": true, "description": "Great than or equal to operator" }, "lt": { "type": "string", "format": "date-time", "nullable": true, "description": "Less than operator" }, "lte": { "type": "string", "format": "date-time", "nullable": true, "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", "format": "date-time", "nullable": true, "description": "Great than operator" }, "gte": { "type": "string", "format": "date-time", "nullable": true, "description": "Great than or equal to operator" }, "lt": { "type": "string", "format": "date-time", "nullable": true, "description": "Less than operator" }, "lte": { "type": "string", "format": "date-time", "nullable": true, "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", "nullable": true, "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", "nullable": true }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ] } }, "text": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "highlight" ] }, "start_time": { "type": "number", "nullable": true }, "end_time": { "type": "number", "nullable": true }, "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", "nullable": true, "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": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "Forbidden" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NotFound" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "UnprocessableContent" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title", "message" ] } } }, "required": [ "errors" ] } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "TooManyRequests" ] }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "InternalError" ] }, "title": { "type": "string", "enum": [ "Internal server error" ] }, "message": { "type": "string" } }, "required": [ "code", "title" ] } } }, "required": [ "errors" ] } } } } } } } }, "info": { "title": "Dovetail Public API", "version": "0.0.1", "description": "The Dovetail Public API provides programmatic access to your Dovetail workspace.\n\n## Core concepts\n\n- **Projects** — Containers for organizing qualitative research. They hold data, docs, highlights, tags, and insights.\n- **Data** — Documents within a project that capture raw research data such as interview transcripts, survey responses, and session recordings. Available via `/v1/data`. The legacy `/v1/notes` endpoints access the same underlying resource.\n- **Docs** — Rich-text documents for writing up research reports, sharing findings, and publishing deliverables. Docs replace the deprecated insights resource.\n- **Highlights** — Selected passages of text or time ranges in transcripts that have been marked as significant during analysis.\n- **Tags** — Labels applied to highlights to categorize findings (e.g. 'Usability Issue', 'Feature Request').\n- **Channels** — Automated AI-powered pipelines that continuously analyze high-volume customer feedback (app reviews, NPS, support tickets) into structured topics.\n- **Contacts** — People in your contacts database such as interview participants or customers.\n- **Folders** — Hierarchical containers for organizing projects, docs, channels, and other content.\n- **Files** — Attachments (images, documents, audio, video) that can be embedded in docs, data entries, or insights.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header. Generate API tokens from your Dovetail workspace settings.\n\n## Base URL\n\nAll API endpoints are served under `https://dovetail.com/api`." }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://dovetail.com/api" }, { "url": "https://dovetailapp.com/api" } ] } ```