SFTPGo Octri Preview
POST/folders

Create a virtual folder

Creates a new virtual folder with its storage configuration and quota settings. Supply name and configure filesystem for the storage provider you want to use. Run a quota scan after creation to populate the folder's used file and size counters.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 11 body fields
confidential_dataintegeroptional
Set to `1` to include keys and additional data for secrets in the response; this parameter is ignored if the authenticated user does not have the required permission.

Virtual folder configuration, including its unique name, storage filesystem, and quota usage values. name is required.

descriptionstringoptional
Optional free-form description.
filesystemobjectoptional
Storage filesystem details. The `provider` field selects which sub-config is active — all other sub-configs are ignored / cleared on save. See `FsProviders` for the mapping. * `provider: -1` → no sub-config (None; users and groups) * `provider: 0` → `osconfig` (local; root is the user's `home_dir`) * `provider: 1` → `s3config` * `provider: 2` → `gcsconfig` * `provider: 3` → `azblobconfig` * `provider: 4` → `cryptconfig` (encrypted local; root is the user's `home_dir`) * `provider: 5` → `sftpconfig` * `provider: 6` → `httpconfig` * `provider: 7` → `ftpconfig`
groupsarray<string>optional
list of groups associated with this virtual folder
idintegeroptional
Server-generated folder identifier; this field is read-only.
last_quota_updateintegeroptional
Last quota update as unix timestamp in milliseconds
mapped_pathstringoptional
Absolute filesystem path used as the virtual folder's storage root. Only meaningful when `filesystem.provider` is 0 (local) or 4 (encrypted local); ignored for cloud providers, which reference a bucket/container via `filesystem.*config`.
namestringrequired
Unique name for this virtual folder (server-side identifier; not shown to end users).
rolestringoptional
Role name. A folder carrying a role with `resource_isolation` enabled is visible to the admins carrying the same role, it is reachable from the groups and the accounts of that role and its storage is measured against the allowlist of the role. An admin carrying a role receives that role on the folders it creates. On update the body replaces the stored role: omitting it clears the role, and the change is refused while accounts or groups of another role reference the folder
used_quota_filesintegeroptional
Current used quota as a number of files.
used_quota_sizeintegeroptional
Current used quota as a size in bytes.
usersarray<string>optional
list of usernames associated with this virtual folder

6 status codes
201Returns the created virtual folder, including its configuration, name, and quota usage values.
descriptionstringoptional
Optional free-form description.
filesystemobjectoptional
Storage filesystem details. The `provider` field selects which sub-config is active — all other sub-configs are ignored / cleared on save. See `FsProviders` for the mapping. * `provider: -1` → no sub-config (None; users and groups) * `provider: 0` → `osconfig` (local; root is the user's `home_dir`) * `provider: 1` → `s3config` * `provider: 2` → `gcsconfig` * `provider: 3` → `azblobconfig` * `provider: 4` → `cryptconfig` (encrypted local; root is the user's `home_dir`) * `provider: 5` → `sftpconfig` * `provider: 6` → `httpconfig` * `provider: 7` → `ftpconfig`
groupsarray<string>optional
list of groups associated with this virtual folder
idintegeroptional
last_quota_updateintegeroptional
Last quota update as unix timestamp in milliseconds
mapped_pathstringoptional
Absolute filesystem path used as the virtual folder's storage root. Only meaningful when `filesystem.provider` is 0 (local) or 4 (encrypted local); ignored for cloud providers, which reference a bucket/container via `filesystem.*config`.
namestringrequired
Unique name for this virtual folder (server-side identifier; not shown to end users).
rolestringoptional
Role name. A folder carrying a role with `resource_isolation` enabled is visible to the admins carrying the same role, it is reachable from the groups and the accounts of that role and its storage is measured against the allowlist of the role. An admin carrying a role receives that role on the folders it creates. On update the body replaces the stored role: omitting it clears the role, and the change is refused while accounts or groups of another role reference the folder
used_quota_filesintegeroptional
used_quota_sizeintegeroptional
usersarray<string>optional
list of usernames associated with this virtual folder
400Returned when `name` is missing or the request is invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when authentication is missing or invalid.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the authenticated user is not permitted to create a folder.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when the server encounters an internal error.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
defaultUnexpected Error
errorstringoptional
error description if any
messagestringoptional
message, can be empty

Error handling

A 400 is returned when name is missing or the request is invalid. A 401 is returned when authentication is missing or invalid, and a 403 when the authenticated user is not permitted to create a folder. A 500 is returned when the server encounters an internal error.