Delete stored files

delete_storage_files

Permanently deletes files from a site's storage bucket.

POST /v1/delete_storage_filesScopedata:writeDestructive

The files are gone for good, there is no recycle bin, and any page or CDN link pointing at them breaks straight away. The tool tells the client to confirm the exact list with you first, and never to delete files to tidy up on its own initiative.

Nothing deleted here is in any archive unless one was taken first. When the client has create_storage_backup, the tool tells it to take one and wait until list_storage_backups reports that backup ready before deleting, because a file removed before the archive is read is left out of the zip.

Pass the full keys from list_storage_files, and use delete_storage_folder for a whole folder. A key ending in a slash names a folder and is refused with a 400 and A key ending in a slash is a folder. Delete it as a folder instead! Without the Delete projects permission in the workspace, the call is refused with a 403 and You are not allowed to delete stored files for this site!

When some files could not be deleted the call fails with deleted, failed and failedKeys in its data. Only the keys in failedKeys are still there, so retry just those. A key that no longer existed is counted in missing rather than deleted, and the call still succeeds, reading The files were already gone. when nothing was left to delete.

A key inside the CMS folder at the top level is refused with a 403 and The CMS folder holds the files of your CMS items, so it cannot be changed from storage. Add files from a CMS field, and they are deleted with their item! The CMS manages that folder, and a CMS file is deleted with the item that uses it. See The CMS folder.

While a storage backup is being restored, the call is refused with a 409 and Your storage is being restored from a backup. Try again when the restore finishes! See While a restore runs.

Request

Call it with a POST to https://api.modulify.ai/v1/delete_storage_files, sending the inputs below as a JSON object. The token needs the data:write scope.

This method is marked destructive: it deletes or overwrites data. Check the inputs before you call it, and send an Idempotency-Key header whenever you might retry it.

curl -X POST https://api.modulify.ai/v1/delete_storage_files \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","keys":[]}'

Over MCP, the same method is the delete_storage_files tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id.
`keys`	array of strings	Yes	The full keys of the files to delete, from `list_storage_files`, at most 200. A key ending in a slash is refused, because it names a folder.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.