Trash API

The Trash API manages soft-deleted files, allowing users to restore or permanently delete items.

Concepts

When a file is deleted via DELETE /api/files/{fileId}, it is moved to the trash rather than being permanently deleted. This allows users to:

  • Recover accidentally deleted files
  • Review deleted items before permanent removal
  • Empty the trash to free up storage

Files remain in trash until explicitly restored or permanently deleted.

Endpoints

List Trashed Files

GET /api/files?parentId=__trash__

List all files currently in the trash.

Query Parameters:

  • parentId=__trash__ - Required to list trash
  • limit (optional) - Maximum files to return

Response:

{
  "data": [
    {
      "fileId": "file_abc123",
      "fileName": "document.pdf",
      "contentType": "application/pdf",
      "deletedAt": "2025-01-15T10:30:00Z",
      "originalParentId": "folder_xyz"
    }
  ],
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/files?parentId=__trash__&limit=50"

Restore File from Trash

POST /api/files/{fileId}/restore

Restore a file from the trash.

Path Parameters:

  • fileId - File ID to restore

Request Body:

{
  "parentId": "folder_xyz"
}

If parentId is omitted or null, the file is restored to the root folder.

Response:

{
  "data": {
    "fileId": "file_abc123",
    "parentId": "folder_xyz",
    "restoredAt": "2025-01-15T11:00:00Z"
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentId": "folder_xyz"}' \
  "https://cl-o.alice.cloudillo.net/api/files/file_abc123/restore"

Permanently Delete File

DELETE /api/files/{fileId}?permanent=true

Permanently delete a file from trash. The file must already be in trash.

Path Parameters:

  • fileId - File ID to permanently delete

Query Parameters:

  • permanent=true - Required for permanent deletion

Response:

{
  "data": {
    "fileId": "file_abc123",
    "permanent": true
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/files/file_abc123?permanent=true"

Empty Trash

DELETE /api/trash

Permanently delete all files in the trash.

Response:

{
  "data": {
    "deletedCount": 15
  },
  "time": 1705315800,
  "req_id": "req_xyz"
}

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/trash"

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'alice.cloudillo.net', authToken: token })

// Move file to trash (soft delete)
await api.files.delete(fileId)

// List trashed files
const trashed = await api.trash.list()

// Restore a file
await api.files.restore(fileId, 'folder_xyz')

// Restore to root
await api.files.restore(fileId)

// Permanently delete a single file
await api.files.permanentDelete(fileId)

// Empty entire trash
const result = await api.trash.empty()
console.log(`Deleted ${result.deletedCount} files`)

File Lifecycle

┌──────────────┐     DELETE      ┌──────────────┐
│    Active    │ ───────────────>│    Trash     │
│    File      │                 │    (soft)    │
└──────────────┘                 └──────────────┘
                                        │
                                        │ restore
                                        │
                ┌───────────────────────┘
                │
                v
        ┌──────────────┐
        │    Active    │
        │    File      │
        └──────────────┘


┌──────────────┐  DELETE?permanent  ┌──────────────┐
│    Trash     │ ──────────────────>│   Deleted    │
│    (soft)    │                    │  (permanent) │
└──────────────┘                    └──────────────┘

Automatic Trash Cleanup

Info

Automatic trash cleanup (retention period) is planned for future releases. Currently, files remain in trash indefinitely until manually restored or deleted.

See Also