{"openapi":"3.1.0","info":{"title":"Dovetail (BYOK) API","version":"0.1.0","description":"Dovetail (BYOK) lets an AI assistant read your own Dovetail data through the Dovetail API with a key you supply (API token (starts with api.; expires after 30 days)). Read-only: 11 tools (get_token_info, list_projects, get_project, list_data, list_highlights, list_insights, list_tags, list_channels, list_channel_themes, list_folders, list_docs). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-dovetail.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-dovetail/docs"},"termsOfService":"https://connectorbay.com/byok-dovetail/terms"},"servers":[{"url":"https://byok-dovetail.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-dovetail/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_token_info":{"post":{"operationId":"get_token_info","summary":"Show the workspace the API token belongs to (workspace id and subdomain); a quick check that the token works. Use for \"W","description":"Show the workspace the API token belongs to (workspace id and subdomain); a quick check that the token works. Use for \"Which Dovetail workspace is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_token_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List research projects of the workspace with title, author and creation time. Cursor paging, up to 100 per page. Use for","description":"List research projects of the workspace with title, author and creation time. Cursor paging, up to 100 per page. Use for \"Which research projects do we have in Dovetail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_project":{"post":{"operationId":"get_project","summary":"Get one research project by id with its title, overview, author and folder. Use for \"Give me the overview of Dovetail pr","description":"Get one research project by id with its title, overview, author and folder. Use for \"Give me the overview of Dovetail project p_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Project id, taken from list_projects.","maxLength":200,"title":"Project Id","type":"string"}},"required":["project_id"],"title":"get_projectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_data":{"post":{"operationId":"list_data","summary":"List data entries (interview transcripts, survey responses, support tickets) with title, project and creation time. Cont","description":"List data entries (interview transcripts, survey responses, support tickets) with title, project and creation time. Content is not returned. Cursor paging. Use for \"What customer data entries were added to Dovetail recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_highlights":{"post":{"operationId":"list_highlights","summary":"List highlights (selected passages) with text, tags, note id and time range. Cursor paging, up to 100 per page. Use for ","description":"List highlights (selected passages) with text, tags, note id and time range. Cursor paging, up to 100 per page. Use for \"What highlights did the team tag in Dovetail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_highlightsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_insights":{"post":{"operationId":"list_insights","summary":"List insights (polished research findings) with title, folder and creation time. Cursor paging. Use for \"Which insights ","description":"List insights (polished research findings) with title, folder and creation time. Cursor paging. Use for \"Which insights have been published in Dovetail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_insightsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List tags used to label highlights, with scope (project or workspace), board and group. Cursor paging. Use for \"Which ta","description":"List tags used to label highlights, with scope (project or workspace), board and group. Cursor paging. Use for \"Which tags does Dovetail use for highlights\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_channels":{"post":{"operationId":"list_channels","summary":"List channels (automated feedback analysis pipelines) with title and creation time. Cursor paging. Use for \"Which Doveta","description":"List channels (automated feedback analysis pipelines) with title and creation time. Cursor paging. Use for \"Which Dovetail channels analyse customer feedback\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_channel_themes":{"post":{"operationId":"list_channel_themes","summary":"List the AI-generated themes of one channel, each with a title, summary and the number of data points; largest first by ","description":"List the AI-generated themes of one channel, each with a title, summary and the number of data points; largest first by default. Use for \"What are the main themes in Dovetail channel c_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Channel id, taken from list_channels.","maxLength":200,"title":"Channel Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"required":["channel_id"],"title":"list_channel_themesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folders":{"post":{"operationId":"list_folders","summary":"List folders that organise projects, docs and channels. Cursor paging. Use for \"How are Dovetail folders organised\".","description":"List folders that organise projects, docs and channels. Cursor paging. Use for \"How are Dovetail folders organised\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_docs":{"post":{"operationId":"list_docs","summary":"List docs (rich-text documents) with title, folder and creation time; content is not returned. Cursor paging. Use for \"W","description":"List docs (rich-text documents) with title, folder and creation time; content is not returned. Cursor paging. Use for \"Which docs exist in Dovetail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"start_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Opaque cursor from the previous answer's page.next_cursor; leave empty for the first page.","title":"Start Cursor"}},"title":"list_docsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}