Files

Upload File

Changed on

Available for: Chatflow, Workflow, Agent, Chatbot, Legacy Agent, Text Generator apps.

Uploads a file and returns its id for later requests to reference. The file belongs to the uploading end user: only requests carrying the same user can reference it.

Which file types an app actually consumes depends on its file-upload settings; read them from Get App Parameters.

post/files/upload

Request

  • Base URL
    https://api.dify.ai/v1
  • URL
    https://api.dify.ai/v1/files/upload
  • Auth
    HTTP bearer

Request body multipart/form-data

filestring binary required

The file to upload, as one multipart/form-data part. The filename must not contain / or \.

Any extension is accepted unless it is on the deployment's security blacklist (UPLOAD_FILE_EXTENSION_BLACKLIST, empty by default).

Size limits per category: images 10 MB, audio 50 MB, video 100 MB, other files 15 MB by default (Dify Cloud uses the defaults). Self-hosted deployments adjust them with the UPLOAD_*_FILE_SIZE_LIMIT environment variables.

userstring

End-user identifier this upload belongs to, defined by your app and unique within it. Omit it to attribute the upload to the shared DEFAULT-USER. Only later requests with the same user can reference the file. See End User Identity.

Response

File uploaded successfully.

conversation_idstring uuid nullable

ID of the associated conversation.

created_atinteger

Upload timestamp (Unix epoch seconds).

created_bystring uuid nullable

End-user ID of the uploader. Look up details with Get End User Info.

extensionstring nullable

File extension.

file_keystring nullable

Unused; always null.

idstring uuid

Unique file ID.

mime_typestring nullable

MIME type of the file.

namestring

File name.

original_urlstring nullable

Original URL of the file.

preview_urlstring nullable

Preview URL for the file.

referencestring nullable

Opaque file reference used internally when attaching files in agent and tool contexts. Always null for files uploaded through this endpoint.

sizeinteger

File size in bytes.

source_urlstring

Signed URL for downloading the file.

tenant_idstring uuid nullable

ID of the associated tenant.

user_idstring uuid nullable

Unused; always null.

Changes