Folder
Folder
An asset folder groups the assets of a stack, and a folder can sit inside another folder. Use the Folder class to create a folder, read its details, rename it, move it under another parent folder, or delete it.
The folder method on stack.asset() returns a new Folder and sends no request. To list the assets and subfolders of a folder, use the query method of Asset.
Additional Resource The Asset Folder Collection requests of the Content Management API (CMA) reference describe every folder request and its response.
Instance State
The form you call decides which methods the object has:
- Call stack.asset().folder() without a UID to create a folder (create).
- Call stack.asset().folder('<FOLDER_UID>') to work on one folder (fetch, update, delete).
- The three header methods exist on both forms.
A method of the other form is undefined on the object, and calling it throws TypeError. The folder method exists only on stack.asset(), so stack.asset('<ASSET_UID>').folder is undefined.
Warning folder('') and folder(null) return the create form, because the SDK treats an empty UID as no UID. Nothing fails at that point. The fetch call that follows throws TypeError. Check that the UID variable is non-empty before you call folder.
Class-Level Notes
Requests and responses.
- Every request method is async and sends one request when you call it.
- create, fetch and update resolve to a new Folder that the SDK builds from the asset key of the response. The API returns a folder under the asset key.
- Folder request bodies also use the asset key, for example { asset: { name: 'docs-test-folder' } }.
Headers and branches.
- A Folder starts with the headers of the Asset object that created it, such as api_key and branch. addHeader changes only this object.
Rate limiting and retry.
- This SDK retries 429 automatically, with configurable delay and attempt limits.
Additional Resource The Contentstack class covers the retry options of contentstack.client() and their defaults.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| List folders or find a folder by name | No | Call stack.asset().query({ query: { is_dir: true, name: '<name>' } }) and then find() |
| List the assets in a folder | No | Call stack.asset().query({ folder: '<FOLDER_UID>' }) and then find() |
Method Index
Create a folder. The method in the table below is available on stack.asset().folder().
| Method Name | Returns | Description |
|---|---|---|
| create | The new folder. | Creates an asset folder. |
Work with one folder. The methods in the table below are available on stack.asset().folder('<FOLDER_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested folder. | Retrieves one folder. |
| update | The updated folder. | Renames a folder or moves it to another parent. |
| delete | The API response with a notice. | Deletes a folder and the assets in it. |
Set request headers. The methods in the table below are available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same folder, for chaining. | Adds one request header. |
| addHeaderDict | The same folder, for chaining. | Adds several request headers. |
| removeHeader | The same folder, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below creates a folder inside a parent folder and then uploads an image into the new folder.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder().create({
asset: { name: 'docs-test-campaign-images', parent_uid: '<FOLDER_UID>' }
})
const asset = await stack.asset().create({ upload: '<FILE_PATH>', title: 'docs-test-hero-image', parent_uid: folder.uid })
console.log(folder.uid, asset.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the Folder class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this folder object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the request header. |
| value (required) | string | Value of the request header. |
Returns: Folder. The same folder, for chaining.
Validation
- There is no client-side validation of the name or the value.
- A null or undefined key leaves the headers unchanged, and addHeader returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader stores the header on this folder object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this folder object only. The stack and other objects keep their headers.
- Every later request from this object sends the header. A key that already exists, such as branch, takes the new value.
Example
Basic usage: send this object's requests to another branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const folder = stack.asset().folder('<FOLDER_UID>').addHeader('branch', '<BRANCH>')
console.log(folder.stackHeaders)addHeaderDict
addHeaderDict adds several headers to every request that this folder object sends afterwards.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Folder. The same folder, for chaining.
Validation
- There is no client-side validation of the names or the values.
- A headerDict that is null, undefined or not an object leaves the headers unchanged, and addHeaderDict returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict copies each key and value of headerDict into the headers of this folder object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this folder object only. The stack and other objects keep their headers.
- A key that already exists, such as branch, takes the new value.
Example
Basic usage: add a branch and a request ID in one call
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const folder = stack.asset().folder('<FOLDER_UID>').addHeaderDict({
branch: '<BRANCH>',
'x-request-id': 'docs-123'
})
console.log(folder.stackHeaders)create
create creates an asset folder, at the root or inside a parent folder.
| Name | Type | Description |
|---|---|---|
| data (required) | { asset: FolderData } | Request body with the folder under an asset key. |
| data.asset.name (required) | string | Name of the new folder. |
| data.asset.parent_uid | string | UID of the parent folder. |
| param | AnyProperty | Query parameters for the request. |
| param.include_branch | boolean | Adds the _branch key to the folder. |
Returns: Promise<Folder>. The new folder.
Validation
- There is no client-side validation. The SDK sends data as you pass it.
- create exists only on stack.asset().folder(). On stack.asset().folder('<FOLDER_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Create a folder request (POST /v3/assets/folders) with data as the JSON body and param as query parameters.
- Without parent_uid, the API creates the folder at the root of the asset library.
- create resolves to a new Folder that the SDK builds from the asset key of the response. The new object has fetch, update and delete.
Example
Basic usage: create a folder at the root
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder().create({ asset: { name: 'docs-test-folder' } })
console.log(folder.uid, folder.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: create a subfolder and include the branch key
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder().create(
{ asset: { name: 'docs-test-subfolder', parent_uid: '<FOLDER_UID>' } },
{ include_branch: true }
)
console.log(folder.uid, folder.parent_uid, folder._branch)
} catch (error) { console.error(error.errorMessage) }delete
delete deletes an asset folder together with all the assets in it.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
Returns: Promise<Response>. The API response with a notice.
Warning The API deletes the folder and every asset inside it, and the SDK has no method that restores them. Move the assets you want to keep to another folder first.
Validation
- There is no client-side validation.
- delete exists only on stack.asset().folder('<FOLDER_UID>'). On stack.asset().folder() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Delete a folder request (DELETE /v3/assets/folders/{folder_uid}) with param as query parameters. The API reference lists no query parameters for this request.
- delete resolves to the response body, which holds notice. When the response has no body, it resolves to { status, statusText }.
Example
Basic usage: delete a folder
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.asset().folder('<FOLDER_UID>').delete()
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: delete a folder and pass query parameters
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.asset().folder('<FOLDER_UID>').delete({ include_branch: true })
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }fetch
fetch retrieves the details of one asset folder.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_path | boolean | Adds the names and UIDs of the parent folders. |
| param.include_branch | boolean | Adds the _branch key to the folder. |
Returns: Promise<Folder>. The requested folder.
Validation
- There is no client-side validation.
- fetch exists only on stack.asset().folder('<FOLDER_UID>'). On stack.asset().folder() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Get a single folder request (GET /v3/assets/folders/{folder_uid}) with param as query parameters.
- With include_path, the API returns the parent folders as an array of objects with their names and UIDs.
- fetch resolves to a new Folder that the SDK builds from the asset key of the response.
Example
Basic usage: retrieve a folder by UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder('<FOLDER_UID>').fetch()
console.log(folder.name, folder.parent_uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: retrieve a folder with its path
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder('<FOLDER_UID>').fetch({ include_path: true, include_branch: true })
console.log(folder.name, folder.path)
} catch (error) { console.error(error.errorMessage) }removeHeader
removeHeader removes one header from the requests that this folder object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Folder. The same folder, for chaining.
Validation
- There is no client-side validation.
- A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the object without an error.
- Removing api_key makes the next request fail with an API error, because every stack request needs the API key.
Behavior
- Client-side only. removeHeader deletes the header from this folder object and sends no request.
- When the header came from the stack, the SDK first copies the headers, so the stack and other objects keep it.
- The management token and the authtoken live on the client, not on this object. removeHeader('authorization') does not remove them.
Example
Basic usage: stop sending the branch header from one object
import contentstack from '@contentstack/management'
const client = contentstack.client()
// This stack sends a branch header on every request
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
const folder = stack.asset().folder('<FOLDER_UID>').removeHeader('branch')
console.log(folder.stackHeaders)update
update saves a new name or a new parent folder that you set on a folder object.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_branch | boolean | Adds the _branch key to the folder. |
Returns: Promise<Folder>. The updated folder.
Validation
- There is no client-side validation. update sends whatever properties the object holds.
- update exists only on stack.asset().folder('<FOLDER_UID>'). On stack.asset().folder() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Update or move folder request (PUT /v3/assets/folders/{folder_uid}) with param as query parameters.
- update takes no body argument. The SDK builds the body as { "asset": { ... } } from the properties of the object. It leaves out uid, urlPath, stackHeaders, api_key and the created, updated and deleted metadata.
- Set name to rename the folder. Set parent_uid to move it under another folder.
- On a folder from fetch, the body also carries the other fetched fields. On stack.asset().folder('<FOLDER_UID>') with no fetch, the body holds only the properties you set.
- update resolves to a new Folder that the SDK builds from the response.
Example
Basic usage: rename a fetched folder
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder('<FOLDER_UID>').fetch()
folder.name = 'Campaign images'
const updated = await folder.update()
console.log(updated.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: move a folder under another parent
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const parent = await stack.asset().folder().create({ asset: { name: 'docs-test-parent-folder' } })
// No fetch, so the request body holds only the name and the new parent
const folder = stack.asset().folder('<FOLDER_UID>')
folder.name = 'Campaign images'
folder.parent_uid = parent.uid
const updated = await folder.update({ include_branch: true })
console.log(updated.parent_uid)
} catch (error) { console.error(error.errorMessage) }