Dify Octri Demo
POST/files/upload

Upload File

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 body fields

File upload request. Requires multipart/form-data.

filestringrequired
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](/en/self-host/deploy/configuration/environments).
userstringoptional
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](/en/api-reference/guides/end-user-identity).

4 status codes
201File uploaded successfully.
conversation_idstringoptional
ID of the associated conversation.
created_atintegeroptional
Upload timestamp (Unix epoch seconds).
created_bystringoptional
End-user ID of the uploader. Look up details with [Get End User Info](/en/api-reference/end-users/get-end-user-info).
extensionstringoptional
File extension.
file_keystringoptional
Unused; always `null`.
idstringoptional
Unique file ID.
mime_typestringoptional
MIME type of the file.
namestringoptional
File name.
original_urlstringoptional
Original URL of the file.
preview_urlstringoptional
Preview URL for the file.
referencestringoptional
Opaque file reference used internally when attaching files in agent and tool contexts. Always `null` for files uploaded through this endpoint.
sizeintegeroptional
File size in bytes.
source_urlstringoptional
Signed URL for downloading the file.
tenant_idstringoptional
ID of the associated tenant.
user_idstringoptional
Unused; always `null`.
400- `no_file_uploaded` : No file was provided in the request. - `too_many_files` : Only one file is allowed per request. - `filename_not_exists_error` : The uploaded file has no filename. - `invalid_param` : The filename contains `/` or `\`. - `file_extension_blocked` : The file's extension is on the deployment's security blacklist (see the `file` field).

5 documented failures

  • file_extension_blocked

    The file extension is blocked for security reasons.

    file_extension_blocked

  • filename_not_exists_error

    The specified filename does not exist.

    filename_not_exists_error

  • invalid_param

    Filename contains invalid characters

    invalid_param

  • no_file_uploaded

    Please upload your file.

    no_file_uploaded

  • too_many_files

    Only one file is allowed.

    too_many_files

413`file_too_large` : The file exceeds its category's size limit (see the `file` field). The runtime `message` is currently returned as an empty string (a known backend quirk); rely on the `code` and status.

One documented failure

  • file_too_large

    file_too_large

415`unsupported_file_type` : The uploaded `file` part declares no MIME type.

One documented failure

  • unsupported_file_type

    File type not allowed.

    unsupported_file_type

Error handling

A 400 is returned: - no_file_uploaded : No file was provided in the request.

  • too_many_files : Only one file is allowed per request.
  • filename_not_exists_error : The uploaded file has no filename.
  • invalid_param : The filename contains / or \.
  • file_extension_blocked : The file's extension is on the deployment's security blacklist (see the file field). A 413 is returned: file_too_large : The file exceeds its category's size limit (see the file field). The runtime message is currently returned as an empty string (a known backend quirk); rely on the code and status. A 415 is returned: unsupported_file_type : The uploaded file part declares no MIME type.