--- updatedAt: 2026-06-01T04:35:17.000Z agentTools: projectIndex: https://developers.dovetail.com/llms.txt --- # Get file by id 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. # OpenAPI definition ```json { "openapi": "3.0.2", "paths": { "/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.\n\nFiles 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", "nullable": true, "description": "The file's MIME type (e.g. 'image/png', 'video/mp4'). Null if unknown." }, "size": { "type": "number", "nullable": true, "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", "format": "null", "nullable": true } ], "nullable": true, "description": "The user who uploaded the file, or null if the author is unknown." }, "created_at": { "oneOf": [ { "type": "string" }, { "type": "string", "format": "null", "nullable": true } ], "nullable": true, "description": "ISO 8601 timestamp when the file was created." }, "url": { "type": "string", "nullable": true, "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": { "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" } ] } ```