Create a storage folder

create_storage_folder

Creates an empty folder in a site's storage bucket, so files can be organized before they are uploaded.

POST /v1/create_storage_folderScopedata:writeMakes changes

Pass visibility to set what files uploaded into it later default to. When it is left out, a new folder follows its parent, or the site default at the top level. The response reports the default the folder ended up with.

Only the last path segment of the name is kept, so a name containing slashes silently loses everything before the final one, and a name of ., .. or nothing but slashes is refused. Put the parent in path instead. A folder is kept as a .modulify-keep file inside it, so that name is refused, and so is a folder whose path and name together are longer than 1001 bytes.

Creating a folder that already exists leaves its contents where they are. Without visibility it keeps the default it already has, and with visibility only the default for files uploaded later changes, so use set_storage_visibility to move the files already inside.

A folder inside the CMS folder at the top level, or the CMS folder itself, 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/create_storage_folder, sending the inputs below as a JSON object. The token needs the data:write scope.

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

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

Over MCP, the same method is the create_storage_folder tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id.
`path`	string	No	The parent folder to create it in. Leave it out or pass an empty string for the top level of the bucket.
`name`	string	Yes	The name of the new folder, without any slashes.
`visibility`	string	No	The default for files uploaded into the folder later, `public` or `private`. Leave it out to keep the default of a folder that already exists, or to inherit from the parent folder for a new one.

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.