Dovetail Files API
The Files API from Dovetail — 3 operation(s) for files.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dovetailapp-com:dovetailapp-com-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Dovetail Public Files API
version: 0.0.1
description: 'The Dovetail Public API provides programmatic access to your Dovetail workspace.
## Core concepts
- **Projects** — Containers for organizing qualitative research. They hold data, docs, highlights, tags, and insights.
- **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.
- **Docs** — Rich-text documents for writing up research reports, sharing findings, and publishing deliverables. Docs replace the deprecated insights resource.
- **Highlights** — Selected passages of text or time ranges in transcripts that have been marked as significant during analysis.
- **Tags** — Labels applied to highlights to categorize findings (e.g. ''Usability Issue'', ''Feature Request'').
- **Channels** — Automated AI-powered pipelines that continuously analyze high-volume customer feedback (app reviews, NPS, support tickets) into structured topics.
- **Contacts** — People in your contacts database such as interview participants or customers.
- **Folders** — Hierarchical containers for organizing projects, docs, channels, and other content.
- **Files** — Attachments (images, documents, audio, video) that can be embedded in docs, data entries, or insights.
## Authentication
All requests require a Bearer token in the `Authorization` header. Generate API tokens from your Dovetail workspace settings.
## Base URL
All API endpoints are served under `https://dovetail.com/api`.'
servers:
- url: https://dovetail.com/api
- url: https://dovetailapp.com/api
security:
- bearerAuth: []
tags:
- name: Files
paths:
/v1/files/:
post:
description: '**Deprecated** — use the v2 upload endpoints for new integrations: `POST /v2/files/upload` for files up to 5 GB and `POST /v2/files/large-upload` for files up to 10 GB. This endpoint is capped at 100 MB.
Existing callers keep working. Each response carries a `Deprecation: true` header and a `Link` header pointing at the successor. A sunset date will be announced once v2 adoption is broad.
---
Upload a file for embedding in docs, data entries, or insights. The request must use `multipart/form-data` encoding with a single `file` field containing the file data.
After uploading, use the returned file ID to reference the file in document content (e.g. as a cover image via `cover_image_file_id` on the **Create doc** or **Patch doc** endpoints).
**Limits:** Maximum file size is 100 MB. Orphaned files that are not embedded in any document within 24 hours are automatically cleaned up.
Returns the file metadata including its processing status.'
summary: Upload a file (deprecated)
deprecated: true
tags:
- Files
parameters: []
requestBody:
description: Body
content:
multipart/form-data:
schema:
type: object
properties:
file: {}
responses:
'201':
description: '201'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Unique identifier of the file.
name:
type: string
description: The file's original name.
type:
type:
- string
- 'null'
description: The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
size:
type:
- number
- 'null'
description: Size of the file in bytes. Null if unknown.
status:
type: string
enum:
- completed
- pending
- failed
description: Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
author:
oneOf:
- type: object
properties:
id:
type: string
name:
type: string
required:
- id
- type:
- string
- 'null'
format: 'null'
description: The user who uploaded the file, or null if the author is unknown.
created_at:
oneOf:
- type: string
- type:
- string
- 'null'
format: 'null'
description: ISO 8601 timestamp when the file was created.
url:
type:
- string
- 'null'
description: Permanent URL pointing at the **Download a file** endpoint. Safe to cache and store — the URL itself never expires, but calling it requires the same authentication as other API endpoints and returns a short-lived presigned URL each time. The endpoint performs its own readiness and access checks.
required:
- id
- name
- type
- size
- status
- author
- created_at
- url
required:
- data
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
enum:
- InvalidOperation
title:
type: string
message:
type: string
path:
type: string
required:
- code
- title
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:
oneOf:
- type: object
properties:
code:
type: string
enum:
- Forbidden
title:
type: string
message:
type: string
required:
- code
- title
- type: object
properties:
code:
type: string
enum:
- IpNotAllowlisted
title:
type: string
message:
type: string
decisionId:
type: string
description: Correlation id quoting this enforcement decision — include it when contacting support.
required:
- code
- title
- decisionId
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
operationId: postV1Files
x-operation-id-source: derived
/v1/files/{file_id}:
get:
description: 'Retrieve metadata for a single file by its unique identifier. Returns the file''s name, MIME type, size in bytes, processing status (`pending`, `completed`, or `failed`), author, and creation date.
Files are attachments (images, documents, audio, video) that can be embedded in docs, data entries, or other content. Use this endpoint to check a file''s processing status after upload.'
summary: Get file by id
tags:
- Files
parameters:
- name: file_id
in: path
required: true
schema:
type: string
title: File id
description: Unique identifier of the file.
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Unique identifier of the file.
name:
type: string
description: The file's original name.
type:
type:
- string
- 'null'
description: The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown.
size:
type:
- number
- 'null'
description: Size of the file in bytes. Null if unknown.
status:
type: string
enum:
- completed
- pending
- failed
description: Processing status of the file. 'pending' while being processed, 'completed' when ready, or 'failed' if processing encountered an error.
author:
oneOf:
- type: object
properties:
id:
type: string
name:
type: string
required:
- id
- type:
- string
- 'null'
format: 'null'
description: The user who uploaded the file, or null if the author is unknown.
created_at:
oneOf:
- type: string
- type:
- string
- 'null'
format: 'null'
description: ISO 8601 timestamp when the file was created.
url:
type:
- string
- 'null'
description: Permanent URL pointing at the **Download a file** endpoint. Safe to cache and store — the URL itself never expires, but calling it requires the same authentication as other API endpoints and returns a short-lived presigned URL each time. The endpoint performs its own readiness and access checks.
required:
- id
- name
- type
- size
- status
- author
- created_at
- url
required:
- data
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
enum:
- InvalidOperation
title:
type: string
message:
type: string
path:
type: string
required:
- code
- title
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:
oneOf:
- type: object
properties:
code:
type: string
enum:
- Forbidden
title:
type: string
message:
type: string
required:
- code
- title
- type: object
properties:
code:
type: string
enum:
- IpNotAllowlisted
title:
type: string
message:
type: string
decisionId:
type: string
description: Correlation id quoting this enforcement decision — include it when contacting support.
required:
- code
- title
- decisionId
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
operationId: getV1FilesByFileId
x-operation-id-source: derived
/v1/files/{file_id}/download:
get:
description: 'Get a presigned URL to download the content of a file by its unique identifier.
The response includes a short-lived URL that can be used to download the file directly from cloud storage without additional authentication. The URL is valid for 1 hour; call this endpoint again to mint a fresh URL when needed.
Download availability is based on upload completion and redaction/obfuscation readiness. It is separate from processing status: a file can still report `pending` or `failed` from the **Get file by id** endpoint while the original bytes are available for download.'
summary: Download a file
tags:
- Files
parameters:
- name: file_id
in: path
required: true
schema:
type: string
title: File id
description: Unique identifier of the file.
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
url:
type: string
format: uri
description: Short-lived presigned URL pointing at cloud storage. Fetch this URL with no extra authentication to download the file bytes. Valid for 1 hour.
expires_at:
type: string
description: ISO 8601 timestamp when the presigned URL expires.
format: date-time
required:
- url
- expires_at
required:
- data
'400':
description: '400'
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
enum:
- InvalidOperation
title:
type: string
message:
type: string
path:
type: string
required:
- code
- title
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:
oneOf:
- type: object
properties:
code:
type: string
enum:
- Forbidden
title:
type: string
message:
type: string
required:
- code
- title
- type: object
properties:
code:
type: string
enum:
- IpNotAllowlisted
title:
type: string
message:
type: string
decisionId:
type: string
description: Correlation id quoting this enforcement decision — include it when contacting support.
required:
- code
- title
- decisionId
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
operationId: getV1FilesByFileIdDownload
x-operation-id-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
x-provenance:
method: searched
source: https://developers.dovetail.com/reference
harvested: '2026-10-21'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.dovetail.com/reference/delete_v1-channels-channel-id.md
- https://developers.dovetail.com/reference/delete_v1-channels-topic-topic-id.md
- https://developers.dovetail.com/reference/delete_v1-contacts-contact-id.md
- https://developers.dovetail.com/reference/delete_v1-data-data-id.md
- https://developers.dovetail.com/reference/delete_v1-docs-doc-id-comments-comment-id.md
- https://developers.dovetail.com/reference/delete_v1-docs-doc-id.md
- https://developers.dovetail.com/reference/delete_v1-fields-field-id.md
- https://developers.dovetail.com/reference/delete_v1-folders-folder-id.md
- https://developers.dovetail.com/reference/delete_v1-insights-insight-id-comments-comment-id.md
- https://developers.dovetail.com/reference/delete_v1-insights-insight-id.md
- https://developers.dovetail.com/reference/delete_v1-notes-note-id.md
- https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-docs-doc-id.md
- https://developers.dovetail.com/reference/delete_v1-projects-project-id-context-keywords.md
- https://developers.dovetail.com/reference/delete_v1-projects-project-id.md
- https://developers.dovetail.com/reference/get_v1-channels-channel-id-data.md
- https://developers.dovetail.com/reference/get_v1-channels-channel-id-themes.md
- https://developers.dovetail.com/reference/get_v1-channels-channel-id.md
- https://developers.dovetail.com/reference/get_v1-channels-data-datum-id.md
- https://developers.dovetail.com/reference/get_v1-channels.md
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://artifacts.apis.io/dovetailapp-com/openapi/dovetailapp-com-files-api-openapi.yml