--- updatedAt: 2026-06-01T04:35:17.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # Add utterance Add a finalised utterance to a data entry's transcript and broadcast it to connected clients. If the entry has no transcript, one is created automatically. Send finalised utterances only. # OpenAPI definition ```json { "openapi": "3.0.2", "paths": { "/v1/transcripts/{data_id}/utterance": { "post": { "description": "Add a finalised utterance to a data entry's transcript and broadcast it\nto connected clients. If the entry has no transcript, one is created\nautomatically. Send finalised utterances only.", "summary": "Add utterance", "tags": [ "Transcripts" ], "parameters": [ { "name": "data_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the data entry." } ], "requestBody": { "description": "Body", "content": { "application/json": { "schema": { "type": "object", "properties": { "speaker_label": { "type": "string", "minLength": 1, "maxLength": 36, "description": "Speaker label for this utterance, such as \"A\" or \"B\".", "example": "A" }, "words": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "start": { "type": "number", "minimum": 0, "description": "Word start time, in seconds, relative to the recording's start." }, "end": { "type": "number", "minimum": 0, "description": "Word end time, in seconds, relative to the recording's start." } }, "required": [ "text", "start", "end" ] }, "minItems": 1, "maxItems": 1000, "description": "Finalised words in this utterance, in order. Word start/end timestamps are in seconds." } }, "required": [ "speaker_label", "words" ] } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "written": { "type": "number", "description": "Number of words saved." } }, "required": [ "written" ] } }, "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" } ] } ```