Recycle Bin Tutorial

Feature Introduction

The Recycle Bin module covers the unified management and policy configuration of soft-deleted files in the "Media Library / Model Library" of FlightHub 2 On-Premises version. It also serves as the entry point for "directly hard delete bypassing the recycle bin" (media only). Coverage:

Media Recycle Bin: list, batch restore, batch permanent delete, disk statistics, retention days policy read/write.

Model Recycle Bin: disk statistics (other model recycle bin operations go through the corresponding interfaces of the Models / Model Reconstruction modules).

Bypass Recycle Bin: single media hard delete (does not enter the recycle bin).

Soft delete vs hard delete: The DELETE /... interfaces of the media library / model library / wayline library are soft delete into the recycle bin by default, and can be restored; the On-Premises version maintains a separate "auto-cleanup retention days" for recycle bin files for each project. After exceeding this number of days, the system automatically and permanently cleans up. POST /trash-config is a project-level configuration.

Batch restore / permanent delete are asynchronous: POST /trash-files/restore and POST /trash-files return 200 immediately after being received by the server, the actual operation is executed asynchronously in the background. The client cannot judge the final result from the response; it needs to refresh via the GET /trash-files list interface to confirm.

Protected directories do not allow hard delete: Live recording directory (FileTypeDirLive), 2D real-time mapping directory (FileTypeConstruction), organization data directory (FileTypeDirDataHub) — these three categories. Calling DELETE /files/{id}/direct will be rejected.

No "model recycle bin list / restore / permanent delete" interfaces: The model library does not have dedicated /model/.../trash-* interfaces; the "restore / permanent delete" of model files is implemented through the restore / destroy parameters of the model general file interface (see Models Tutorial). This module only exposes disk statistics.

Interface Usage Flow

Media Recycle Bin — Browse / Restore / Permanent Delete

Call steps:

Browse: Get Media Recycle Bin File List (GET /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/trash-files) — The list of files in the media recycle bin of the current project, supporting filtering by file name keyword, filtering by file type, paginated browsing, and browsing sub-items within deleted folders.

Batch restore: Restore Files from Recycle Bin (POST /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/trash-files/restore) — Batch restore the specified files / folders in the recycle bin to their original locations; if the original parent folder is also deleted, restore to the project root directory. Request body form { "ids": [<int64>...], "select_all": <bool> }, ids and select_all are mutually exclusive: when passing ids, restore according to the exact list; when select_all=true, restore all recycle bin files according to the current filter conditions.

Batch permanent delete: Permanently Delete Recycle Bin Files (POST /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/trash-files) — Batch permanent delete from storage, irrecoverable. The request body form is consistent with the restore interface: { "ids": [<int64>...], "select_all": <bool> }, the two are mutually exclusive.

The "restore from recycle bin" for a single file can also be completed via Update Media File Info (PUT /media/api/v1/workspaces/{workspace_id}/files/{id}) by passing restore=true. See Media Tutorial for details.

Media Recycle Bin — Retention Days Policy

Call steps:

Read policy: Get Media Recycle Bin Config (GET /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/trash-config) — The auto-cleanup policy of the media recycle bin of the current project. Projects that have not been set return the default value of 30 days.

Write policy: Modify Media Recycle Bin Config (POST /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/trash-config) — Update the retention days policy; files exceeding this number of days will be automatically permanently cleaned up.

Media Recycle Bin — Bypass Recycle Bin Direct Hard Delete

Hard Delete Single Media File (DELETE /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/files/{id}/direct) directly permanently deletes a single media file or folder from storage (does not enter the recycle bin, irrecoverable). Protected directory types (live recording directory, 2D real-time mapping directory, organization data directory) are not allowed to be deleted.

Paired with DELETE /files/direct (batch hard delete) in the Media Tutorial; the former operates by ID, the latter batches by list.

Disk Statistics

Purpose	Interface
Media recycle bin disk usage statistics (by file type)	`GET /openapi/v2.0/media/api/v1/workspaces/{workspace_id}/drive-statistics-trash`
Model library recycle bin disk usage statistics (by file type)	`GET /openapi/v2.0/model/api/v1/workspaces/{workspace_id}/drive-statistics-trash`

The return values both include: total count / used space / remaining space / breakdown grouped by type, used for the capacity bar and type distribution chart at the top of the "Recycle Bin" UI.

Feature Introduction#

Interface Usage Flow#

Media Recycle Bin — Browse / Restore / Permanent Delete#

Media Recycle Bin — Retention Days Policy#

Media Recycle Bin — Bypass Recycle Bin Direct Hard Delete#