Add API and GUI cleanup mechanism to delete uploaded files and related DB entries by unique ID

[Himmelskomiker]

Self Checks

• I have read the Contributing Guide and Language Policy.
• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report, otherwise it will be closed.
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

Add API and GUI cleanup mechanism to delete uploaded files and related DB entries by unique ID

1. Description / Story

Hi, and thank you for your great work on Dify!

When uploading files or data — either via the API or through the GUI — each file receives a unique ID. However, after a run has completed, there is currently no way to delete these files and their related database entries.

All uploaded files (from API and GUI) are stored in the same directory as knowledge base data. This can become confusing and also leads to blocked storage and orphaned database entries that are no longer linked to any active run or knowledge source.

It would be very helpful to have an API call or cleanup mechanism (similar to the knowledge deletion endpoint) that allows developers to completely remove a file and its corresponding database entry — whether it was uploaded through the GUI or via the API.

---

2. Proposed Solution

This feature would:

• Prevent storage from being blocked by leftover files after execution
• Avoid orphaned database records
• Improve consistency between file management for GUI and API uploads
• Help developers keep their Dify environments clean and efficient

Example idea:

DELETE /v1/files/{file_id}

This endpoint could remove both the stored file and its related database entry.
Alternatively, a GUI cleanup option (e.g. “Delete after execution”) could achieve the same goal.

---

3. References and Related Issues

I checked the official Dify documentation and GitHub issues to confirm whether this already exists:

Documentation

• Maintain Knowledge and Documents — shows how to delete knowledge documents, not arbitrary uploaded files.
• File Upload Workflow — describes how files are uploaded and stored but not how to delete them later.

Related GitHub Issues

• #21688 — Confirms that there is no direct API to delete a file just by its upload_file_id.
• #16452 — Discusses the need for periodic cleanup of uploaded files.
• #23147 — Mentions cleanup of unused files tied to datasets but not generic uploads.
• #11218 — Requests retention/deletion control for workflow-uploaded files.

These references confirm that there’s no general API or GUI option to delete uploaded files and their DB entries after use.

---

4. Closing Note

Thank you for considering this improvement!
Adding a unified cleanup mechanism would greatly enhance Dify’s file management reliability and reduce confusion and storage issues for both API and GUI users.

2. Additional context or comments

References and Related Issues

I checked the official Dify documentation and GitHub issues to confirm whether this already exists:

Documentation

[Maintain Knowledge and Documents] (https://legacy-docs.dify.ai/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-knowledge-documents?utm_source=chatgpt.com)
— shows how to delete knowledge documents, not arbitrary uploaded files.

[File Upload Workflow] (https://legacy-docs.dify.ai/guides/workflow/file-upload?utm_source=chatgpt.com)
— describes how files are uploaded and stored but not how to delete them later.

Related GitHub Issues

[#21688] (https://github.com/langgenius/dify/issues/21688?utm_source=chatgpt.com)
— Confirms that there is no direct API to delete a file just by its upload_file_id.

[#16452] (https://github.com/langgenius/dify/issues/16452?utm_source=chatgpt.com)
— Discusses the need for periodic cleanup of uploaded files.

[#23147] (https://github.com/langgenius/dify/issues/23147?utm_source=chatgpt.com)
— Mentions cleanup of unused files tied to datasets but not generic uploads.

#11218
— Requests retention/deletion control for workflow-uploaded files.

These references confirm that there’s no general API or GUI option to delete uploaded files and their DB entries after use.

3. Can you help us with this feature?

• I am interested in contributing to this feature.