Delete File or Folder

This action is irreversible, and it deletes folders recursively. Pointing this endpoint at a folder removes that folder, everything inside it at every depth, and all their cached variants, in one call and with no confirmation step. Check the path before you send it.

Deletes the file or folder at {path}, along with its cached transformation variants.

DELETE /storage/{path}

curl -X DELETE http://localhost:3000/storage/photos/portrait.jpg \
  -H "Authorization: Bearer <api_key>"

To clear cached variants and keep the original, use Invalidate Cache instead. Auth: API key required. A dashboard session cookie also works.

Path parameters

Param	Type	Required	Description
`path`	string	yes	Path to the file or folder relative to the storage root, e.g. `photos/2026`. Use the `path` of a file or folder returned by List Storage.

Response

{
  "success": true,
  "message": "Asset deleted successfully",
  "details": {
    "jobsDeleted": 0,
    "localCacheFilesDeleted": 3,
    "cloudCacheFilesDeleted": 0
  }
}

Field	Type	Description
`success`	boolean	`true` when the delete completed with no errors
`message`	string	Human-readable result summary
`details`	object	Counters, below

jobsDeleted, number: queued processing jobs cancelled and removed
localCacheFilesDeleted, number: cached transformation variants removed from local disk
cloudCacheFilesDeleted, number: cached transformation variants removed from cloud storage

Deleting a folder on cloud storage returns early once the folder is removed, so jobsDeleted and the cache counters stay at 0 even though the folder’s objects are gone.

Partial deletion

If the original was removed but some cleanup step failed, the response has a different shape: no success field, and an errors array inside details.

{
  "error": "Partial deletion",
  "message": "Asset deleted but some cleanup operations failed",
  "details": {
    "originalFileDeleted": true,
    "jobsDeleted": 0,
    "localCacheFilesDeleted": 2,
    "cloudCacheFilesDeleted": 0,
    "errors": ["Failed to delete cached variant w_200/photo.jpg"]
  }
}

The status is 200 when originalFileDeleted is true and 500 when it is false. Branch on the presence of error, not on success.

Code	Meaning
`200`	Deleted, or deleted with non-fatal cleanup errors
`400`	Path is missing
`404`	Nothing exists at that path
`500`	The original could not be deleted

Invalidate Cache

Clear cached variants while keeping the original.

List Storage

Browse folders and files before deleting.

Move File or Folder

Move instead of deleting.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

Path parameters

Response

Partial deletion

Invalidate Cache

List Storage

Move File or Folder

​Path parameters

​Response

​Partial deletion

​Related

Invalidate Cache

List Storage

Move File or Folder

Path parameters

Response

Partial deletion

Related