--- title: "Creates or updates the folder specified by the `folderPath`. If the folder's ancestors do not exist, they will be created automatically (with empty FolderSettings). Note: you don't need to create folders before uploading files to them. Requires a `secret_*` API key. Alternatively, you can use a `public_*` API key and JWT-based auth." method: PUT path: "/v2/accounts/{accountId}/folders" tags: ["Folder"] --- # Creates or updates the folder specified by the \`folderPath\`. If the folder's ancestors do not exist, they will be created automatically (with empty FolderSettings). Note: you don't need to create folders before uploading files to them. Requires a \`secret_\*\` API key. Alternatively, you can use a \`public_\*\` API key and JWT-based auth. `PUT /v2/accounts/{accountId}/folders` ## Request - Base URL: `https://api.bytescale.com` - URL: `https://api.bytescale.com/v2/accounts/{accountId}/folders` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates or updates the folder specified by the `folderPath`. If the folder's ancestors do not exist, they will be created automatically (with empty FolderSettings). Note: you don't need to create folders before uploading files to them. Requires a `secret_*` API key. Alternatively, you can use a `public_*` API key and JWT-based auth. ## Path parameters - `accountId` string, required: Your account ID. This is visible on the settings page: https://www.bytescale.com/dashboard/settings ## Request body - PutFolderRequest: Request body for PutFolder. - `allowUnnamedFolder` boolean: You must specify `true` if the `folderPath` ends with a `/`. This prevents the accidental creation of folders that produce file paths with double forward-slashes in them. Default: false - `folderPath` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `folderSettings` PatchFolderSettings: Specifies the folder settings to use when creating or updating a folder. - `description` union - UnspecifiedFieldValue: This data type specifies no update is to be performed. - `set` false, required: This field is always `false`. Indicates the property *will not* be updated as part of the request. - SpecifiedFieldValueEmptiableFolderDescription: This data type specifies the field must be updated. - `set` true, required: This field is always `true`. Indicates the property *will* be updated as part of the request, and the property's new value will be ```value```. - `value` string: Folder description. - `publicPermissions` union - UnspecifiedFieldValue: This data type specifies no update is to be performed. - `set` false, required: This field is always `false`. Indicates the property *will not* be updated as part of the request. - SpecifiedFieldValueEmptiablePublicPermissionsArray: This data type specifies the field must be updated. - `set` true, required: This field is always `true`. Indicates the property *will* be updated as part of the request, and the property's new value will be ```value```. - `value` PublicPermissions[]: The value to set into the field. - `permissions` PublicPermissionsGrants, required: Permissions applied to anonymous users who attempt to download files from a folder. Each folder can declare these permissions via its FolderSettings object. - `file` PublicPermissionsGrantsFiles, required: Permissions relating to the downloading of files at this path. - … - `scope` 'Children' | 'Grandchildren+' | 'This', required: Specifies the level in the file tree, relative to the path, that these permissions apply. - `"This"`: Permissions apply to the current path only. - `"Children"`: Permissions apply to the children (files and folders) of this path only. - `"Grandchildren+"`: Permissions apply to the grandchildren (files and folders) of this path and their descendants only. - `storageLayer` union - UnspecifiedFieldValue: This data type specifies no update is to be performed. - `set` false, required: This field is always `false`. Indicates the property *will not* be updated as part of the request. - SpecifiedFieldValueEmptiableStorageLayerUpdate: This data type specifies the field must be updated. - `set` true, required: This field is always `true`. Indicates the property *will* be updated as part of the request, and the property's new value will be ```value```. - `value` union: Data type used to update or create a folder's storage layer. This data type may contain credentials. - InternalStorageV2: Default storage layer used for files uploaded via the Bytescale API V2 (latest version). This is a read/write storage layer. - `mount` string: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `type` 'InternalStorageV2', required: The type of this storage layer. - WebStorage: Storage layer used for serving files from external HTTP origins. This is a read-only storage layer. - `appendQueryString` string: Query string without the leading "?" character. - `baseUrl` string: URL for an http(s) resource. - `queryStringForwarding` WebStorageQueryStringForwarding: This object is used for the value of the `queryStringForwarding` field on the `WebStorage` object, and defines how user-provided query strings are forwarded to the HTTP origin. If left unset, no user-provided query strings will be forwarded to the HTTP origin. *Instructions:* - To *block all* query string parameters: use `"Whitelist"` with an empty `parameters` array (default if unset). - To *allow all* query string parameters: use `"Blacklist"` with an empty `parameters` array. - To *allow some* query string parameters: use either `"Blacklist"` or `"Whitelist"` with one or more `parameters`. - … - `type` 'Web', required: The type of this storage layer. - AzureReadOnlyStorage - `azureStorage` object, required - … - `credentials` object, required - … - `type` 'AzureReadOnly', required - `useAbsolutePaths` boolean, required - S3Storage: Storage layer used for storing files in custom S3 buckets, as opposed to Bytescale's built-in storage. This is a read/write storage layer. - `bucket` object, required - … - `credentials` object, required - … - `type` 'S3', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `useTransferAcceleration` boolean, required: Enables S3 transfer acceleration, providing improved file upload speeds for larger files. Note: this setting must also be enabled on the S3 bucket. - GenericS3Storage - `bucket` object, required - … - `credentials` object, required - … - `type` 'GenericS3', required - `useAbsolutePaths` boolean, required - DigitalOceanStorage: Storage layer used for storing files in a DigitalOcean Space, as opposed to Bytescale's built-in storage. This is a read/write storage layer. - `bucket` object, required - … - `credentials` object, required - … - `type` 'DigitalOceanSpace', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - R2Storage: Storage layer used for storing files in Cloudflare R2, as opposed to Bytescale's built-in storage. This is a read/write storage layer. - `bucket` object, required - … - `cloudflareAccountId` string, required: Cloudflare Account ID. - `credentials` object, required - … - `type` 'R2', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - GoogleStorage: Storage layer used for storing files in Google Storage, as opposed to Bytescale's built-in storage. This is a read/write storage layer. - `bucket` object, required - … - `credentials` object, required - … - `type` 'GoogleStorage', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. ## Response `200` Success. - FolderDetails: Full details of a given folder. - `folderPath` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `settings` FolderSettings, required - `description` string: Folder description. - `publicPermissions` PublicPermissions[] - `permissions` PublicPermissionsGrants, required: Permissions applied to anonymous users who attempt to download files from a folder. Each folder can declare these permissions via its FolderSettings object. - `file` PublicPermissionsGrantsFiles, required: Permissions relating to the downloading of files at this path. - `downloadFile` TransformationUrlSlugPattern[], required: An array of transformation URL slug patterns. This array specifies which transformation slugs can be used when downloading files from this location. - Use `"*"` to allow all file downloads. - Use `"raw"` to allow raw/original file downloads. - Use a `*` suffix to allow transformation prefixes. For example: `"thumbnail-*"` will allow `thumbnail-sm` and `thumbnail-lg`. - Use any other value to allow specific transformations. For example: `"thumbnail"` will allow `thumbnail` downloads only. - Use an empty array to indicate no file downloads are allowed. - `scope` 'Children' | 'Grandchildren+' | 'This', required: Specifies the level in the file tree, relative to the path, that these permissions apply. - `"This"`: Permissions apply to the current path only. - `"Children"`: Permissions apply to the children (files and folders) of this path only. - `"Grandchildren+"`: Permissions apply to the grandchildren (files and folders) of this path and their descendants only. - `storageLayer` union: Storage layer summary information, describing an existing folder's storage layer. This data type does not contain credentials. - InternalStorageV1: Storage layer used for all files uploaded via the Bytescale API V1 (legacy version). This is a read/write storage layer. - `type` 'InternalStorageV1', required: The type of this storage layer. - InternalStorageV2: Default storage layer used for files uploaded via the Bytescale API V2 (latest version). This is a read/write storage layer. - `mount` string: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `type` 'InternalStorageV2', required: The type of this storage layer. - WebStorage: Storage layer used for serving files from external HTTP origins. This is a read-only storage layer. - `appendQueryString` string: Query string without the leading "?" character. - `baseUrl` string: URL for an http(s) resource. - `queryStringForwarding` WebStorageQueryStringForwarding: This object is used for the value of the `queryStringForwarding` field on the `WebStorage` object, and defines how user-provided query strings are forwarded to the HTTP origin. If left unset, no user-provided query strings will be forwarded to the HTTP origin. *Instructions:* - To *block all* query string parameters: use `"Whitelist"` with an empty `parameters` array (default if unset). - To *allow all* query string parameters: use `"Blacklist"` with an empty `parameters` array. - To *allow some* query string parameters: use either `"Blacklist"` or `"Whitelist"` with one or more `parameters`. - `parameters` WebStorageQueryStringParam[], required: Determines which parameters to forward based on the `type` field: If `"Whitelist"` is set in the `type` field: - Only parameters in this array will be forwarded. - An empty array prevents all parameters from being forwarded. If `"Blacklist"` is set in the `type` field: - Only parameters in this array will be blocked. - An empty array allows all parameters to be forwarded. - `name` string, required: Query string parameter name. Must be URL-encoded. - `type` 'Whitelist' | 'Blacklist', required: Determines whether the `parameters` array is interpreted as a blacklist or a whitelist. - `type` 'Web', required: The type of this storage layer. - AzureReadOnlyStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'AzureReadOnly', required - `azureStorage` object, required - `containerName` string, required: Azure Storage container name. - `blobNamePrefix` string, required: Azure Storage BLOB name prefix. - `accountName` string, required: Azure Storage account name. - `useAbsolutePaths` boolean, required - S3StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'S3', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketRegion` 'us-east-2' | 'us-east-1' | 'us-west-1' | 'us-west-2' | 'af-south-1' | 'ap-east-1' | 'ap-south-2' | 'ap-southeast-3' | 'ap-southeast-4' | 'ap-south-1' | 'ap-northeast-3' | 'ap-northeast-2' | 'ap-southeast-1' | 'ap-southeast-2' | 'ap-northeast-1' | 'ca-central-1' | 'ca-west-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'eu-south-1' | 'eu-west-3' | 'eu-south-2' | 'eu-north-1' | 'eu-central-2' | 'il-central-1' | 'me-south-1' | 'me-central-1' | 'sa-east-1', required: AWS Region. - `bucketName` string, required: S3-compatible bucket name. - `useTransferAcceleration` boolean, required: Enables S3 transfer acceleration, providing improved file upload speeds for larger files. Note: this setting must also be enabled on the S3 bucket. - GenericS3StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'GenericS3', required - `useAbsolutePaths` boolean, required - `bucket` object, required - `unsupportedOperations` S3OperationName[], required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `forcePathStyle` boolean, required: Controls how URLs are constructed when making HTTP requests to the S3-compatible API hosted at `bucketEndpoint`. - If `true` then `bucketName` will be added to the URL path. - If `false` then `bucketName` will be added as a subdomain of `bucketEndpoint`, assuming `bucketName` does not contain '.' and is DNS-compatible, else it will be added to the URL path. - `bucketRegion` string, required: Generic S3 Region. - `bucketName` string, required: S3-compatible bucket name. - `bucketEndpoint` string, required: URL for an http(s) resource. - DigitalOceanStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'DigitalOceanSpace', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketRegion` string, required: DigitalOcean Region. - `bucketName` string, required: S3-compatible bucket name. - R2StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'R2', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketName` string, required: S3-compatible bucket name. - `cloudflareAccountId` string, required: Cloudflare Account ID. - GoogleStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'GoogleStorage', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketName` string, required: Google Storage Bucket Name. - `type` 'Folder', required: Indicates this item is a folder (as opposed to a file). - `virtual` boolean, required: If `true` then the folder was created using the PutFolder operation. If `false` then the folder was created automatically as the result of a file upload operation, and will disappear if/when the folder later becomes empty. - `settingsInherited` FolderSettingsInherited, required: The FolderSettings inherited by the current path. If the folder defines its own `settings`, then those will take effect instead of these inherited settings. Each inherited setting contains a `folderPath` field to indicate which folder the setting was inherited from. Note: if the requester has insufficient privileges to read a setting, that setting's value will be undefined. - `publicPermissions` PublicPermissionsInherited - `folderPath` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `value` PublicPermissions[], required - `permissions` PublicPermissionsGrants, required: Permissions applied to anonymous users who attempt to download files from a folder. Each folder can declare these permissions via its FolderSettings object. - `file` PublicPermissionsGrantsFiles, required: Permissions relating to the downloading of files at this path. - `downloadFile` TransformationUrlSlugPattern[], required: An array of transformation URL slug patterns. This array specifies which transformation slugs can be used when downloading files from this location. - Use `"*"` to allow all file downloads. - Use `"raw"` to allow raw/original file downloads. - Use a `*` suffix to allow transformation prefixes. For example: `"thumbnail-*"` will allow `thumbnail-sm` and `thumbnail-lg`. - Use any other value to allow specific transformations. For example: `"thumbnail"` will allow `thumbnail` downloads only. - Use an empty array to indicate no file downloads are allowed. - `scope` 'Children' | 'Grandchildren+' | 'This', required: Specifies the level in the file tree, relative to the path, that these permissions apply. - `"This"`: Permissions apply to the current path only. - `"Children"`: Permissions apply to the children (files and folders) of this path only. - `"Grandchildren+"`: Permissions apply to the grandchildren (files and folders) of this path and their descendants only. - `storageLayer` StorageLayerInherited - `folderPath` string, required: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `value` union, required: Storage layer summary information, describing an existing folder's storage layer. This data type does not contain credentials. - InternalStorageV1: Storage layer used for all files uploaded via the Bytescale API V1 (legacy version). This is a read/write storage layer. - `type` 'InternalStorageV1', required: The type of this storage layer. - InternalStorageV2: Default storage layer used for files uploaded via the Bytescale API V2 (latest version). This is a read/write storage layer. - `mount` string: Absolute path to a folder. Begins with a `/`. Should not end with a `/`. - `type` 'InternalStorageV2', required: The type of this storage layer. - WebStorage: Storage layer used for serving files from external HTTP origins. This is a read-only storage layer. - `appendQueryString` string: Query string without the leading "?" character. - `baseUrl` string: URL for an http(s) resource. - `queryStringForwarding` WebStorageQueryStringForwarding: This object is used for the value of the `queryStringForwarding` field on the `WebStorage` object, and defines how user-provided query strings are forwarded to the HTTP origin. If left unset, no user-provided query strings will be forwarded to the HTTP origin. *Instructions:* - To *block all* query string parameters: use `"Whitelist"` with an empty `parameters` array (default if unset). - To *allow all* query string parameters: use `"Blacklist"` with an empty `parameters` array. - To *allow some* query string parameters: use either `"Blacklist"` or `"Whitelist"` with one or more `parameters`. - `parameters` WebStorageQueryStringParam[], required: Determines which parameters to forward based on the `type` field: If `"Whitelist"` is set in the `type` field: - Only parameters in this array will be forwarded. - An empty array prevents all parameters from being forwarded. If `"Blacklist"` is set in the `type` field: - Only parameters in this array will be blocked. - An empty array allows all parameters to be forwarded. - … - `type` 'Whitelist' | 'Blacklist', required: Determines whether the `parameters` array is interpreted as a blacklist or a whitelist. - `type` 'Web', required: The type of this storage layer. - AzureReadOnlyStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'AzureReadOnly', required - `azureStorage` object, required - `containerName` string, required: Azure Storage container name. - `blobNamePrefix` string, required: Azure Storage BLOB name prefix. - `accountName` string, required: Azure Storage account name. - `useAbsolutePaths` boolean, required - S3StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'S3', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketRegion` 'us-east-2' | 'us-east-1' | 'us-west-1' | 'us-west-2' | 'af-south-1' | 'ap-east-1' | 'ap-south-2' | 'ap-southeast-3' | 'ap-southeast-4' | 'ap-south-1' | 'ap-northeast-3' | 'ap-northeast-2' | 'ap-southeast-1' | 'ap-southeast-2' | 'ap-northeast-1' | 'ca-central-1' | 'ca-west-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'eu-south-1' | 'eu-west-3' | 'eu-south-2' | 'eu-north-1' | 'eu-central-2' | 'il-central-1' | 'me-south-1' | 'me-central-1' | 'sa-east-1', required: AWS Region. - `bucketName` string, required: S3-compatible bucket name. - `useTransferAcceleration` boolean, required: Enables S3 transfer acceleration, providing improved file upload speeds for larger files. Note: this setting must also be enabled on the S3 bucket. - GenericS3StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'GenericS3', required - `useAbsolutePaths` boolean, required - `bucket` object, required - `unsupportedOperations` S3OperationName[], required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `forcePathStyle` boolean, required: Controls how URLs are constructed when making HTTP requests to the S3-compatible API hosted at `bucketEndpoint`. - If `true` then `bucketName` will be added to the URL path. - If `false` then `bucketName` will be added as a subdomain of `bucketEndpoint`, assuming `bucketName` does not contain '.' and is DNS-compatible, else it will be added to the URL path. - `bucketRegion` string, required: Generic S3 Region. - `bucketName` string, required: S3-compatible bucket name. - `bucketEndpoint` string, required: URL for an http(s) resource. - DigitalOceanStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'DigitalOceanSpace', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes S3 objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes S3 objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketRegion` string, required: DigitalOcean Region. - `bucketName` string, required: S3-compatible bucket name. - R2StorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'R2', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketName` string, required: S3-compatible bucket name. - `cloudflareAccountId` string, required: Cloudflare Account ID. - GoogleStorageWithoutCredentials: From T, pick a set of properties whose keys are in the union K - `type` 'GoogleStorage', required: The type of this storage layer. - `useAbsolutePaths` boolean, required: If `true` then writes Google Storage objects with full `filePath` as key, prefixed with the `objectKeyPrefix`. If `false` then writes Google Storage objects using a relative `filePath` in relation to folder's path, prefixed with the `objectKeyPrefix`. - `bucket` object, required - `objectKeyPrefix` string, required: AWS S3 Object Key. - `bucketName` string, required: Google Storage Bucket Name. ## Other responses - `401`: Unauthenticated. ## Changes - **2026-09-01** `d63ecdd9ae9c`: 2 breaking, 5 info - the response property `settingsInherited/publicPermissions` became optional for the status `200` - the response property `settingsInherited/storageLayer` became optional for the status `200` - the request property `folderSettings/description` became optional - the request property `folderSettings/publicPermissions` became optional - …3 more [Operation history](https://skmtc.dev/bytescale/apis/bytescale-api/changes/v2/accounts/:accountId/folders/put.md) --- [API](https://skmtc.dev/bytescale/apis/bytescale-api.md) - [All operations](https://skmtc.dev/bytescale/apis/bytescale-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bytescale/apis/bytescale-api/revisions/d63ecdd9ae9c?raw)