Dovetail Files API

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.
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-14'
  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
  - https://developers.dovetail.com/reference/get_v1-contacts-contact-id.md
  - https://developers.dovetail.com/reference/get_v1-contacts.md
  - https://developers.dovetail.com/reference/get_v1-data-data-id-export-type.md
  - https://developers.dovetail.com/reference/get_v1-data-data-id.md
  - https://developers.dovetail.com/reference/get_v1-data.md
  - https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments-comment-id.md
  - https://developers.dovetail.com/reference/get_v1-docs-doc-id-comments.md
  - https://developers.dovetail.com/reference/get_v1-docs-doc-id-export-type.md
  - https://developers.dovetail.com/reference/get_v1-docs-doc-id.md
  - https://developers.dovetail.com/reference/get_v1-docs-user-user-id.md
  - https://developers.dovetail.com/reference/get_v1-docs.md
  - https://developers.dovetail.com/reference/get_v1-fields-field-id.md
  - https://developers.dovetail.com/reference/get_v1-fields.md
  - https://developers.dovetail.com/reference/get_v1-files-file-id-download.md
  - https://developers.dovetail.com/reference/get_v1-files-file-id.md
  - https://developers.dovetail.com/reference/get_v1-folders-folder-id-contents.md
  - https://developers.dovetail.com/reference/get_v1-folders-folder-id.md
  - https://developers.dovetail.com/reference/get_v1-folders.md
  - https://developers.dovetail.com/reference/get_v1-highlights-highlight-id.md
  - https://developers.dovetail.com/reference/get_v1-highlights.md
  - https://developers.dovetail.com/reference/get_v1-insights-insight-id-comments-comment-id.md


# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dovetail/refs/heads/main/openapi/dovetail-files-api-openapi.yml