Delete a storage folder

delete_storage_folder

Permanently deletes a folder from a site's storage bucket, along with everything inside it, nested subfolders included.

POST /v1/delete_storage_folderScopedata:writeDestructive

It cannot be undone and there is no recycle bin. The tool tells the client to read the folder with list_storage_files first and confirm the whole contents with you before calling it.

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.

One call removes at most 20,000 files from each side of the bucket, public and private. The response reports how many were removed in deleted, and complete is false when more remain, so call it again with the same input until complete is true.

The folder's visibility setting is deleted with it, so files written into that path later follow the parent folder or the top level default. The root of the bucket is refused, and without the Delete projects permission in the workspace the call is refused with a 403 and You are not allowed to delete storage folders for this site!

The CMS folder at the top level, or any folder inside it, 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_folder, 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_folder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","path":"PATH"}'

Over MCP, the same method is the delete_storage_folder tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id.
`path`	string	Yes	The folder to delete, from `list_storage_files`. The root of the bucket is refused.

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.