Folder
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Rename a folder or move it under another folder | No | Update creates a new folder instead. See the Known issue in the Class-Level Notes above. |
| List the folders of a stack | Through Asset | Call Find on the Query method of Asset with include_folders set to true. |
| Find a folder by name | Through Asset | Pass a query of {"is_dir": true, "name": "<FOLDER_NAME>"} to Find on the Query method of Asset. |
| Upload an asset into a folder | Through AssetModel | Set ParentUID on the AssetModel you pass to Asset.Create. |
Properties
| Property | Type | Access | Default | Description |
|---|---|---|---|---|
| Uid | string? | get, set | The 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 Name | Returns | Description |
|---|---|---|
| Create | The API response with the created folder. | Creates an asset folder. |
| CreateAsync | The API response with the created folder. | Creates an asset folder asynchronously. |
Work with one folder. Available on stack.Asset().Folder("<FOLDER_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested folder. | Retrieves one folder. |
| FetchAsync | The API response with the requested folder. | Retrieves one folder asynchronously. |
| Update | The API response with a newly created folder. | Sends a create request with a new name. |
| UpdateAsync | The API response with a newly created folder. | Sends a create request with a new name asynchronously. |
| Delete | The API response with the deletion notice. | Deletes a folder and its assets. |
| DeleteAsync | The 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.
| Name | Type | Description |
|---|---|---|
| name (required) | string | Sets the name of the new folder. |
| parentUid | string? | Places the folder inside this parent folder. |
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.
| Name | Type | Description |
|---|---|---|
| name (required) | string | Sets the name of the new folder. |
| parentUid | string? | Places the folder inside this parent folder. |
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
- Behaves like Delete.
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().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
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.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
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
- Behaves like Fetch.
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.
| Name | Type | Description |
|---|---|---|
| name (required) | string | Sets the name of the folder that the request creates. |
| parentUid | string? | Places the created folder inside this parent folder. |
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.
| Name | Type | Description |
|---|---|---|
| name (required) | string | Sets the name of the folder that the request creates. |
| parentUid | string? | Places the created folder inside this parent folder. |
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);
}