Folder

View as Markdown

Folder

The Folder class creates, fetches, and deletes the asset folders of a stack. Asset folders group the assets of a stack, and a folder can sit inside another folder.

When to Use This Class: Use this class when your code sets up a folder structure for uploads, or removes a folder and the assets in it.

Conceptual Role: Acts as the Content Management API (CMA) client for the /assets/folders endpoint. Call stack.Asset().Folder() to get an instance.

Returns: Folder. A handle for asset folder operations.

Instance State

The UID you pass to Folder() decides which methods you can call on the instance:

  • Call stack.Asset().Folder() without a UID to create a folder with Create or CreateAsync.
  • Call stack.Asset().Folder("<FOLDER_UID>") to work with one folder, for example Fetch or Delete.

If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. The Method Index below lists every method in each group.

Folder() itself throws InvalidOperationException when the Asset instance has a UID. Call it on stack.Asset() with no argument.

Warning The SDK treats an empty string as no UID in its checks, so Folder("") allows Create, and Fetch and Delete throw InvalidOperationException. Pass null, or call Folder() with no argument, when you mean a new folder.

Warning Set the folder UID only through Folder("<FOLDER_UID>"). The SDK builds the request path when you call Folder(). Setting the Uid property later changes which methods the SDK allows without changing which folder the request targets.

Class-Level Notes

Authentication.

  • stack.Asset() throws InvalidOperationException when the client has no authtoken and the Stack has no management token, and when the Stack has no API key.
  • Every method except Create and Update repeats the login check when you call it.
  • The CMA accepts an authtoken, an Open Authorization (OAuth) token, or a management token for every folder request.

Renaming and moving folders.

  • Known issue: Update and UpdateAsync create a new folder with the name you pass. They do not rename or move the folder whose UID you passed, which stays unchanged. To rename or move a folder, send the CMA Update or move folder request directly.

Branch scoping.

  • The branchUid argument of client.Stack() adds a branch header to every request from that Stack. The CMA then reads and writes folders in that branch.

Errors.

  • The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.
  • A method that returns without throwing returns a ContentstackResponse with a success status. Read its body with OpenJsonObjectResponse() or OpenTResponse<T>().

Rate Limiting & Retry.

  • This SDK automatically retries a request that returns 429, 500, 502, 503, or 504, with configurable delay and attempt limits.

Additional Resource For more information on retry limits and delay, refer to the ContentstackClientOptions documentation.

Async methods.

  • The async methods run the same client-side checks as soon as you call them, before they return a task.

Capability Matrix

CapabilitySupportedNotes / Alternative
Rename a folder or move it under another folderNoUpdate creates a new folder instead. See the Known issue in the Class-Level Notes above.
List the folders of a stackThrough AssetCall Find on the Query method of Asset with include_folders set to true.
Find a folder by nameThrough AssetPass a query of {"is_dir": true, "name": "<FOLDER_NAME>"} to Find on the Query method of Asset.
Upload an asset into a folderThrough AssetModelSet ParentUID on the AssetModel you pass to Asset.Create.

Properties

PropertyTypeAccessDefaultDescription
Uidstring?get, setThe UID passed to Folder()UID of the folder. null on an instance that creates a folder.

Method Index

Create a folder. Available on stack.Asset().Folder() when you pass no UID.

Method NameReturnsDescription
CreateThe API response with the created folder.Creates an asset folder.
CreateAsyncThe API response with the created folder.Creates an asset folder asynchronously.

Work with one folder. Available on stack.Asset().Folder("<FOLDER_UID>").

Method NameReturnsDescription
FetchThe API response with the requested folder.Retrieves one folder.
FetchAsyncThe API response with the requested folder.Retrieves one folder asynchronously.
UpdateThe API response with a newly created folder.Sends a create request with a new name.
UpdateAsyncThe API response with a newly created folder.Sends a create request with a new name asynchronously.
DeleteThe API response with the deletion notice.Deletes a folder and its assets.
DeleteAsyncThe API response with the deletion notice.Deletes a folder and its assets asynchronously.

Class-Level Snippet

The snippet below creates a folder, creates a subfolder inside it, and fetches the subfolder with the path of its parent folders.

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");

try
{
    ContentstackResponse parent = await stack.Asset().Folder().CreateAsync("Product Images");
    string parentUid = parent.OpenJsonObjectResponse()["asset"]?["uid"]?.ToString() ?? "";

    ContentstackResponse child = await stack.Asset().Folder().CreateAsync("Spring Range", parentUid);
    string childUid = child.OpenJsonObjectResponse()["asset"]?["uid"]?.ToString() ?? "";

    ParameterCollection collection = new ParameterCollection();
    collection.Add("include_path", true);
    ContentstackResponse fetched = await stack.Asset().Folder(childUid).FetchAsync(collection);
    Console.WriteLine(fetched.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the Folder class has its own section below, with its parameters, validation rules, behavior, and examples.

Create

Create creates an asset folder, at the root of the stack or inside a parent folder.

NameTypeDescription
name (required)string

Sets the name of the new folder.

Default: Not applicable
parentUidstring?

Places the folder inside this parent folder.

Default: null

Returns: ContentstackResponse. The API response with the created folder.

Validation

  • Throws InvalidOperationException if the instance has a UID, because Create adds a new folder. Call stack.Asset().Folder().
  • Throws ArgumentNullException if name is null, because the API needs a name for the folder.
  • An empty name passes the SDK check, and the SDK then leaves name out of the request body. The Content Management API (CMA) Create a folder request needs a name, so pass a non-empty value.
  • The SDK does not check parentUid. A UID that names no folder reaches the API and fails there.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one POST request to /assets/folders, the Create a folder request.
  • Sends the body {"asset": {"name": "<name>", "parent_uid": "<parentUid>"}}. The SDK leaves out parent_uid when parentUid is null or empty, and the API then creates the folder at the root.
  • Returns the raw API response. The new folder sits under the asset key, with its UID in asset.uid.

Example

Basic usage: create a folder at the root

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Asset().Folder().Create("Product Images");
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: create a subfolder inside a parent folder

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Asset()
        .Folder()
        .Create("Spring Range", "<FOLDER_UID>");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

CreateAsync

CreateAsync creates an asset folder, at the root of the stack or inside a parent folder, without blocking the calling thread.

NameTypeDescription
name (required)string

Sets the name of the new folder.

Default: Not applicable
parentUidstring?

Places the folder inside this parent folder.

Default: null

Returns: Task<ContentstackResponse>. The API response with the created folder.

Validation

  • Throws InvalidOperationException if the instance has a UID, because CreateAsync adds a new folder. Call stack.Asset().Folder().
  • Throws ArgumentNullException if name is null, because the API needs a name for the folder.
  • The SDK throws the exceptions above when you call CreateAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Runs the login check that Create skips.
  • Otherwise behaves like Create.

Example

Basic usage: create a folder at the root

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset().Folder().CreateAsync("Product Images");
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: create a subfolder inside a parent folder

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Asset()
        .Folder()
        .CreateAsync("Spring Range", "<FOLDER_UID>");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Delete

Delete deletes the folder whose UID you passed to Folder(), together with the assets in it.

This method takes no parameters.

Returns: ContentstackResponse. The API response with the deletion notice.

Validation

  • Throws InvalidOperationException if the instance has no UID, because Delete removes one folder. Call stack.Asset().Folder("<FOLDER_UID>").
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one DELETE request to /assets/folders/<FOLDER_UID>, the Delete a folder request.
  • The API deletes the folder together with every asset in it.
  • Returns the raw API response.

Example

Warning Delete removes the folder and every asset inside it. Move the assets you want to keep to another folder first.

Basic usage: delete a folder

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").Delete();
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Check the folder contents before you delete it

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();
Stack stack = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("folder", "<FOLDER_UID>");

try
{
    ContentstackResponse contents = stack.Asset().Query().Find(collection);
    Console.WriteLine(contents.OpenJsonObjectResponse().ToJsonString());

    // Review the assets above, then delete the folder.
    stack.Asset().Folder("<FOLDER_UID>").Delete();
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeleteAsync

DeleteAsync deletes the folder whose UID you passed to Folder(), together with the assets in it, without blocking the calling thread.

This method takes no parameters.

Returns: Task<ContentstackResponse>. The API response with the deletion notice.

Validation

  • Throws InvalidOperationException if the instance has no UID, because DeleteAsync removes one folder. Call stack.Asset().Folder("<FOLDER_UID>").
  • The SDK throws the exception above when you call DeleteAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

Example

Warning DeleteAsync removes the folder and every asset inside it. Move the assets you want to keep to another folder first.

Basic usage: delete a folder

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").DeleteAsync();
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Check the folder contents before you delete it

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();
Stack stack = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("folder", "<FOLDER_UID>");

try
{
    ContentstackResponse contents = await stack.Asset().Query().FindAsync(collection);
    Console.WriteLine(contents.OpenJsonObjectResponse().ToJsonString());

    // Review the assets above, then delete the folder.
    await stack.Asset().Folder("<FOLDER_UID>").DeleteAsync();
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Fetch

Fetch retrieves the details of the folder whose UID you passed to Folder().

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the requested folder.

Validation

  • Throws InvalidOperationException if the instance has no UID, because Fetch reads one folder. Call stack.Asset().Folder("<FOLDER_UID>").
  • The SDK does not check the UID format. A UID that names no folder reaches the API and fails there.
  • collection set to null or left empty sends no query parameters.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one GET request to /assets/folders/<FOLDER_UID>, the Get a single folder request.
  • Sends each entry of collection as a query parameter. include_path set to true adds the names and UIDs of the parent folders. The Content Management API (CMA) reference also lists include_branch.
  • Returns the raw API response. The folder sits under the asset key.

Example

Basic usage: fetch a folder by UID

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").Fetch();
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["name"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a folder with the path of its parent folders

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_path", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Asset().Folder("<FOLDER_UID>").Fetch(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FetchAsync

FetchAsync retrieves the details of the folder whose UID you passed to Folder(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the requested folder.

Validation

  • Throws InvalidOperationException if the instance has no UID, because FetchAsync reads one folder. Call stack.Asset().Folder("<FOLDER_UID>").
  • The SDK throws the exception above when you call FetchAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

Example

Basic usage: fetch a folder by UID

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").FetchAsync();
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["name"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a folder with the path of its parent folders

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_path", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Asset().Folder("<FOLDER_UID>").FetchAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Update

Update sends a create request with the name and parent folder you pass. It does not change the folder whose UID you passed to Folder().

Known issue: Update creates a new folder instead of renaming or moving this one, and the original folder stays unchanged. To rename or move a folder, send the Content Management API (CMA) Update or move folder request directly.

NameTypeDescription
name (required)string

Sets the name of the folder that the request creates.

Default: Not applicable
parentUidstring?

Places the created folder inside this parent folder.

Default: null

Returns: ContentstackResponse. The API response with a newly created folder.

Validation

  • Throws InvalidOperationException if the instance has no UID. Call stack.Asset().Folder("<FOLDER_UID>").
  • Throws ArgumentNullException if name is null.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one POST request to /assets/folders with the body {"asset": {"name": "<name>", "parent_uid": "<parentUid>"}}. This is the Create a folder request, not Update or move folder.
  • Does not send the folder UID of the instance. The UID only decides that the SDK allows the call.
  • Returns the raw API response. The new folder sits under the asset key, with its own UID in asset.uid.

Example

Basic usage: call Update and read the UID of the folder it creates

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").Update("Product Images 2026");

    // The UID below belongs to a new folder, not to <FOLDER_UID>.
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: pass a parent folder UID

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");

try
{
    ContentstackResponse response = stack.Asset().Folder("<FOLDER_UID>").Update("Spring Range", "<PARENT_FOLDER_UID>");
    string createdUid = response.OpenJsonObjectResponse()["asset"]?["uid"]?.ToString() ?? "";

    // Remove the extra folder if you did not want it.
    stack.Asset().Folder(createdUid).Delete();
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

UpdateAsync

UpdateAsync sends a create request with the name and parent folder you pass, without blocking the calling thread. It does not change the folder whose UID you passed to Folder().

Known issue: UpdateAsync creates a new folder instead of renaming or moving this one, and the original folder stays unchanged. To rename or move a folder, send the Content Management API (CMA) Update or move folder request directly.

NameTypeDescription
name (required)string

Sets the name of the folder that the request creates.

Default: Not applicable
parentUidstring?

Places the created folder inside this parent folder.

Default: null

Returns: Task<ContentstackResponse>. The API response with a newly created folder.

Validation

  • Throws InvalidOperationException if the instance has no UID. Call stack.Asset().Folder("<FOLDER_UID>").
  • Throws ArgumentNullException if name is null.
  • The SDK throws the exceptions above when you call UpdateAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Runs the login check that Update skips.
  • Otherwise behaves like Update, including the known issue.

Example

Basic usage: call UpdateAsync and read the UID of the folder it creates

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset().Folder("<FOLDER_UID>").UpdateAsync("Product Images 2026");

    // The UID below belongs to a new folder, not to <FOLDER_UID>.
    Console.WriteLine(response.OpenJsonObjectResponse()["asset"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: pass a parent folder UID

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");

try
{
    ContentstackResponse response = await stack.Asset().Folder("<FOLDER_UID>").UpdateAsync("Spring Range", "<PARENT_FOLDER_UID>");
    string createdUid = response.OpenJsonObjectResponse()["asset"]?["uid"]?.ToString() ?? "";

    // Remove the extra folder if you did not want it.
    await stack.Asset().Folder(createdUid).DeleteAsync();
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}