Skip to main content
post/files/upload
Request example
Response
post/files/upload

Authorization

Authorizationstringheaderrequired#

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

multipart/form-data
filefilerequired#

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.

Responses

application/json
File uploaded successfully.
conversation_idstring#
ID of the associated conversation.
created_atinteger#
Upload timestamp (Unix epoch seconds).
created_bystring#
End-user ID of the uploader. Look up details with Get End User Info.
extensionstring#
File extension.
file_keystring#
Unused; always null.
idstring#
Unique file ID.
mime_typestring#
MIME type of the file.
namestring#
File name.
original_urlstring#
Original URL of the file.
preview_urlstring#
Preview URL for the file.
referencestring#
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#
ID of the associated tenant.
user_idstring#
Unused; always null.