Folder

View as Markdown

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

CapabilitySupportedNotes / Alternative
List folders or find a folder by nameNoCall stack.asset().query({ query: { is_dir: true, name: '<name>' } }) and then find()
List the assets in a folderNoCall 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 NameReturnsDescription
createThe 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 NameReturnsDescription
fetchThe requested folder.Retrieves one folder.
updateThe updated folder.Renames a folder or moves it to another parent.
deleteThe 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 NameReturnsDescription
addHeaderThe same folder, for chaining.Adds one request header.
addHeaderDictThe same folder, for chaining.Adds several request headers.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Name of the request header.

Default: Not applicable
value (required)string

Value of the request header.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
data (required){ asset: FolderData }

Request body with the folder under an asset key.

Default: Not applicable
data.asset.name (required)string

Name of the new folder.

Default: Not applicable
data.asset.parent_uidstring

UID of the parent folder.

Default: undefined (not sent)
paramAnyProperty

Query parameters for the request.

Default: undefined (sends no query parameters)
param.include_branchboolean

Adds the _branch key to the folder.

Default: API default

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_pathboolean

Adds the names and UIDs of the parent folders.

Default: API default
param.include_branchboolean

Adds the _branch key to the folder.

Default: API default

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_branchboolean

Adds the _branch key to the folder.

Default: API default

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) }