Dotfile Files API

openapi: 3.2.0
info:
  title: ⚙️ API specifications Files API
  description: Dotfile public API documentation
  version: v1
  contact: {}
servers:
- url: https://api.dotfile.com
  description: Production environment
security:
- DotfileAPIKey: []
tags:
- name: Files
paths:
  /v1/files/upload:
    post:
      operationId: file-upload-file
      summary: Upload a file
      description: 'Upload a file and get an `upload_ref` to be used for Identity Document Check or Documents checks.


        ---


        Maximum file size is at most **20MB** but may vary depending on the usage afterward.


        The `upload_ref` is valid for about **1 day**.


        The accepted file formats are:

        - Image files:

        - `.avif`: AVIF image (`image/avif`)

        - `.bmp`: Windows OS/2 Bitmap Graphics (`image/bmp`)

        - `.gif`: Graphics Interchange Format (GIF, `image/gif`)

        - `.ico`: Icon format (`image/vnd.microsoft.icon`)

        - `.ico`: Icon format (`image/x-icon`)

        - `.jpeg, .jpg`: JPEG images (`image/jpeg`)

        - `.png`: Portable Network Graphics (`image/png`)

        - `.svg`: Scalable Vector Graphics (SVG, `image/svg+xml`)

        - `.tif, .tiff`: Tagged Image File Format (TIFF, `image/tiff`)

        - `.webp`: WEBP image (`image/webp`)

        - Office files:

        - `.doc`: Microsoft Word (`application/msword`)

        - `.docx`: Microsoft Word (OpenXML, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`)

        - `.odp`: OpenDocument presentation document (`application/vnd.oasis.opendocument.presentation`)

        - `.ods`: OpenDocument spreadsheet document (`application/vnd.oasis.opendocument.spreadsheet`)

        - `.odt`: OpenDocument text document (`application/vnd.oasis.opendocument.text`)

        - `.pdf`: Adobe Portable Document Format (PDF, `application/pdf`)

        - `.ppt`: Microsoft PowerPoint (`application/vnd.ms-powerpoint`)

        - `.pptx`: Microsoft PowerPoint (OpenXML, `application/vnd.openxmlformats-officedocument.presentationml.presentation`)

        - `.vsd`: Microsoft Visio (`application/vnd.visio`)

        - `.xls`: Microsoft Excel (`application/vnd.ms-excel`)

        - `.xlsx`: Microsoft Excel (OpenXML, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)

        - Text files:

        - `.csv`: Comma-separated values (CSV, `text/csv`)

        - `.json`: JSON format (`application/json`)

        - `.jsonld`: JSON-LD format (`application/ld+json`)

        - `.rtf`: Rich Text Format (RTF, `application/rtf`)

        - `.txt`: Text, (generally ASCII or ISO 8859-n, `text/plain`)

        - Archive files:

        - `.arc`: Archive document (multiple files embedded, `application/x-freearc`)

        - `.bz`: BZip archive (`application/x-bzip`)

        - `.bz2`: BZip2 archive (`application/x-bzip2`)

        - `.gz`: GZip Compressed Archive (`application/gzip`)

        - `.rar`: RAR archive (`application/vnd.rar`)

        - `.tar`: Tape Archive (TAR, `application/x-tar`)

        - `.zip`: ZIP archive (`application/zip`)

        - `.7z`: 7-zip archive (`application/x-7z-compressed`)

        - `.7z`: 7-zip archive on windows (`application/x-compressed`)

        - `.zip`: ZIP archive on windows (`application/x-zip-compressed`)


        ---


        #### See also

        Learn more about Files'
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: 'File uploaded and reference ready to be used.


            **ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFile'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - When the file is missing\n  - When the file is empty\n  "
        '413':
          description: File too large, maximum file size is **20MB**.
        '415':
          description: File type not supported.
      tags:
      - Files
  /v1/files/{id}:
    get:
      operationId: file-get-file
      summary: Download a file
      description: 'Download a file. Get file content as standard `binary/octet-stream` File.


        ---


        #### See also

        Learn more about Files'
      parameters:
      - name: id
        required: true
        in: path
        description: Id of the file
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: 'Get File content


            **ℹ️ Click to see full payload**'
          content:
            '*/*':
              schema:
                type: string
                format: binary
              example: File
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the identifier specified in the URL is a valid UUID\n  "
        '404':
          description: No file can be found.
      tags:
      - Files
components:
  schemas:
    UploadedFile:
      type: object
      properties:
        upload_ref:
          type: string
        expired_at:
          type: string
          format: date-time
          description: "Upload ref will expire after this date  \nDate time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)"
      required:
      - upload_ref
      - expired_at
  securitySchemes:
    DotfileAPIKey:
      type: apiKey
      in: header
      name: X-DOTFILE-API-KEY
      description: Configure your api key in the Workspace settings
x-uploaded-at: '2026-08-14T14:05:07.336Z'
x-commit-sha: f460fa65a5cc33cf4211bbcee7818f93d5b9e8de