--- updatedAt: 2026-09-01T01:12:23.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # 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. # OpenAPI definition ```json { "openapi": "3.0.2", "paths": { "/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\").\n\nEach 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**.\n\nIf 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.\n\nOnly 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.\n\n> 🚧 Permissions\n>\n> 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.\n", "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", "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" ] } }, "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": { "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" } ] } ```