--- updatedAt: 2026-08-26T09:26:35.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # 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. # OpenAPI definition ```json { "openapi": "3.0.2", "paths": { "/v1/tags/boards": { "get": { "description": "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.\n\nBy default the workspace's shared tag boards are returned. Pass a `project_id` filter to list a single project's own tag board instead.\n\nEach 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.", "summary": "List tag boards", "tags": [ "Tags" ], "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": "See [Filters](https://developers.dovetail.com/docs/filters) for details on parameter formatting.", "style": "deepObject", "schema": { "type": "object", "properties": { "project_id": { "type": "string", "description": "Unique identifier of the project whose tag boards to list. When omitted, the workspace's shared tag boards are returned. A workspace board's backing extension project ID (returned as `project_id` on workspace boards) resolves to that board." } }, "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", "description": "The URL of this tag board in the Dovetail web app. This field is experimental and may change without notice." }, "title": { "type": "string" }, "scope": { "type": "string", "enum": [ "project", "workspace" ], "description": "`workspace` — a workspace tag board whose tags can be applied to highlights in every project linked to the board. `project` — a project's own tag board." }, "project_id": { "type": "string", "description": "For `project` boards, the project the board belongs to. For `workspace` boards, the board's backing extension project, which is not listed by the projects endpoints." }, "tag_count": { "type": "number", "description": "The number of tags on this board." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "tag_count": { "type": "number", "description": "The number of tags in this group." } }, "required": [ "id", "title", "tag_count" ] }, "description": "The board's tag groups, in display order. At most 100 groups are returned per board." }, "created_at": { "type": "string" } }, "required": [ "id", "title", "scope", "project_id", "tag_count", "groups", "created_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" } ] } ```