Is AI recommending you? Ask Contentstack Canoe for free
Is AI recommending your brand? Find out with Contentstack Canoe for free
Contentstack.comAcademyLogin
CS-log-dark.svgCS-log-dark.svg
  • Changelog
  • APIs
  • SDKs

Platform

  • Solution Center
  • Marketplace
  • Changelog
  • Developers & IT
  • Business users
  • Digital leaders
  • Developer Fast Track
  • Plans & Pricing

Solutions

  • Retail
  • Travel and tourism
  • Financial services
  • Technology
  • Manufacturing
  • E-commerce
  • Localization
  • Personalization
  • Portals and knowledge bases

Resources

  • Academy
  • Docs
  • Contentstack for Developers
  • Product updates
  • Contentstack on Contentstack
  • Blog
  • Insights and analyst reports
  • The Forrester Wave™: Digital Experience Platforms, Q4 2025
  • Webinars
  • Podcasts
  • Glossary
  • Content generative library
  • Community
  • Headless CMS
  • Composable AXP
  • Personalization
  • CDP

Customers

  • Case Studies
  • Customer Care
  • Contentstack Experience Awards
  • Customer support

Partners

  • Overview
  • Find a partner
  • Login

Company

  • About us
  • News
  • Customer support portal
  • Contact

Social

  • Facebook
  • LinkedIn
  • Instagram
  • GitHub
  • YouTube
  • Discord
  • X
LegalTermsPrivacyTrust Center

Cookie settings

Copyright © 2026 Contentstack Inc. All rights reserved.
/
  1. Home
  2. APIs
  3. Assets API
  4. Folders

Folders

markdownView as Markdown

Organize assets into hierarchical folders.

Create a folder

POSThttps://am-api.contentstack.com/api/spaces/{space_uid}/folders

The Create a folder request creates a new folder in the specified space. To create a subfolder, pass the uid of the parent folder in the request body.

Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

Query Parameters

workspaceoptionalstring

The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.

Body Parameters

titlerequiredstring

The title of the folder.

descriptionoptionalstring

A description of the folder.

parent_uidoptionalstring

The uid of the parent folder. Omit to create a folder at the root level.

Sample Request
12345
{
  "title": "string",
  "description": "string",
  "parent_uid": "string"
}
Sample Response
Status|201 Created
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384
{
  "notice": "string",
  "folder": {
    "_id": "string",
    "uid": "string",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "parent_uid": "string",
    "path": [
      {
        "uid": "string",
        "title": "string"
      }
    ],
    "owner_uid": "string",
    "co_owners": [
      {
        "uid": "string",
        "name": "string"
      }
    ],
    "permanent_url": "string",
    "permanent_url_slug": "string",
    "content_type": "string",
    "asset_type_uid": "string",
    "file_size": 0,
    "tags": [
      "string"
    ],
    "is_dir": true,
    "asset_id": "string",
    "url": "string",
    "locale": "string",
    "dimensions": {
      "height": 0,
      "width": 0
    },
    "status": "IN_PROGRESS",
    "version": 0,
    "org_uid": "string",
    "space_uid": "string",
    "user_defined_fields": {},
    "visual_markups": [
      {
        "type": "Hotspot",
        "title": "string",
        "description": "string",
        "url": "http://example.com",
        "coordinates": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        }
      }
    ],
    "publish_details": [
      {
        "locale": "string",
        "environment": "string",
        "time": "2019-08-24T14:15:22Z",
        "user": "string",
        "version": 0,
        "action": "string",
        "job_id": "string",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "workspace_uid": "string",
        "origin": "string"
      }
    ],
    "_version_name": {
      "title": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string"
    },
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "is_deleted": true
  }
}

Get all folders

GEThttps://am-api.contentstack.com/api/spaces/{space_uid}/folders

Restore a deleted folder

POSThttps://am-api.contentstack.com/api/spaces/{space_uid}/folders/{folder_uid}/restore

Update a folder

PUThttps://am-api.contentstack.com/api/spaces/{space_uid}/folders/{folder_uid}

Get a folder

GEThttps://am-api.contentstack.com/api/spaces/{space_uid}/folders/{folder_uid}

Delete a folder

DELETEhttps://am-api.contentstack.com/api/spaces/{space_uid}/folders/{folder_uid}

The Get all folders request fetches a paginated list of all folders in the specified space.

Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687
{
  "count": 0,
  "relation": "string",
  "folders": [
    {
      "_id": "string",
      "uid": "string",
      "object_type": "string",
      "title": "string",
      "description": "string",
      "file_name": "string",
      "parent_uid": "string",
      "path": [
        {
          "uid": "string",
          "title": "string"
        }
      ],
      "owner_uid": "string",
      "co_owners": [
        {
          "uid": "string",
          "name": "string"
        }
      ],
      "permanent_url": "string",
      "permanent_url_slug": "string",
      "content_type": "string",
      "asset_type_uid": "string",
      "file_size": 0,
      "tags": [
        "string"
      ],
      "is_dir": true,
      "asset_id": "string",
      "url": "string",
      "locale": "string",
      "dimensions": {
        "height": 0,
        "width": 0
      },
      "status": "IN_PROGRESS",
      "version": 0,
      "org_uid": "string",
      "space_uid": "string",
      "user_defined_fields": {},
      "visual_markups": [
        {
          "type": "Hotspot",
          "title": "string",
          "description": "string",
          "url": "http://example.com",
          "coordinates": {
            "x": 0,
            "y": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "publish_details": [
        {
          "locale": "string",
          "environment": "string",
          "time": "2019-08-24T14:15:22Z",
          "user": "string",
          "version": 0,
          "action": "string",
          "job_id": "string",
          "scheduled_at": "2019-08-24T14:15:22Z",
          "workspace_uid": "string",
          "origin": "string"
        }
      ],
      "_version_name": {
        "title": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "updated_by": "string"
      },
      "created_by": "string",
      "updated_by": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "is_deleted": true
    }
  ]
}

The Restore a deleted folder request restores a soft-deleted folder. Set restore_with_assets to true to also restore the assets that the folder contained.

Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384
{
  "notice": "string",
  "asset": {
    "_id": "string",
    "uid": "string",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "parent_uid": "string",
    "path": [
      {
        "uid": "string",
        "title": "string"
      }
    ],
    "owner_uid": "string",
    "co_owners": [
      {
        "uid": "string",
        "name": "string"
      }
    ],
    "permanent_url": "string",
    "permanent_url_slug": "string",
    "content_type": "string",
    "asset_type_uid": "string",
    "file_size": 0,
    "tags": [
      "string"
    ],
    "is_dir": true,
    "asset_id": "string",
    "url": "string",
    "locale": "string",
    "dimensions": {
      "height": 0,
      "width": 0
    },
    "status": "IN_PROGRESS",
    "version": 0,
    "org_uid": "string",
    "space_uid": "string",
    "user_defined_fields": {},
    "visual_markups": [
      {
        "type": "Hotspot",
        "title": "string",
        "description": "string",
        "url": "http://example.com",
        "coordinates": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        }
      }
    ],
    "publish_details": [
      {
        "locale": "string",
        "environment": "string",
        "time": "2019-08-24T14:15:22Z",
        "user": "string",
        "version": 0,
        "action": "string",
        "job_id": "string",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "workspace_uid": "string",
        "origin": "string"
      }
    ],
    "_version_name": {
      "title": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string"
    },
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "is_deleted": true
  }
}

The Update a folder request updates the details of a specific folder, such as its title or parent folder.

Sample Request
12345
{
  "title": "string",
  "description": "string",
  "parent_uid": "string"
}
Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384
{
  "notice": "string",
  "folder": {
    "_id": "string",
    "uid": "string",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "parent_uid": "string",
    "path": [
      {
        "uid": "string",
        "title": "string"
      }
    ],
    "owner_uid": "string",
    "co_owners": [
      {
        "uid": "string",
        "name": "string"
      }
    ],
    "permanent_url": "string",
    "permanent_url_slug": "string",
    "content_type": "string",
    "asset_type_uid": "string",
    "file_size": 0,
    "tags": [
      "string"
    ],
    "is_dir": true,
    "asset_id": "string",
    "url": "string",
    "locale": "string",
    "dimensions": {
      "height": 0,
      "width": 0
    },
    "status": "IN_PROGRESS",
    "version": 0,
    "org_uid": "string",
    "space_uid": "string",
    "user_defined_fields": {},
    "visual_markups": [
      {
        "type": "Hotspot",
        "title": "string",
        "description": "string",
        "url": "http://example.com",
        "coordinates": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        }
      }
    ],
    "publish_details": [
      {
        "locale": "string",
        "environment": "string",
        "time": "2019-08-24T14:15:22Z",
        "user": "string",
        "version": 0,
        "action": "string",
        "job_id": "string",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "workspace_uid": "string",
        "origin": "string"
      }
    ],
    "_version_name": {
      "title": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string"
    },
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "is_deleted": true
  }
}

The Get a folder request fetches the details of a specific folder using its uid.

Sample Response
Status|200 OK
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
{
  "folder": {
    "_id": "string",
    "uid": "string",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "parent_uid": "string",
    "path": [
      {
        "uid": "string",
        "title": "string"
      }
    ],
    "owner_uid": "string",
    "co_owners": [
      {
        "uid": "string",
        "name": "string"
      }
    ],
    "permanent_url": "string",
    "permanent_url_slug": "string",
    "content_type": "string",
    "asset_type_uid": "string",
    "file_size": 0,
    "tags": [
      "string"
    ],
    "is_dir": true,
    "asset_id": "string",
    "url": "string",
    "locale": "string",
    "dimensions": {
      "height": 0,
      "width": 0
    },
    "status": "IN_PROGRESS",
    "version": 0,
    "org_uid": "string",
    "space_uid": "string",
    "user_defined_fields": {},
    "visual_markups": [
      {
        "type": "Hotspot",
        "title": "string",
        "description": "string",
        "url": "http://example.com",
        "coordinates": {
          "x": 0,
          "y": 0,
          "width": 0,
          "height": 0
        }
      }
    ],
    "publish_details": [
      {
        "locale": "string",
        "environment": "string",
        "time": "2019-08-24T14:15:22Z",
        "user": "string",
        "version": 0,
        "action": "string",
        "job_id": "string",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "workspace_uid": "string",
        "origin": "string"
      }
    ],
    "_version_name": {
      "title": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "updated_by": "string"
    },
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "is_deleted": true
  }
}

The Delete a folder request deletes a specific folder using its uid. Deleting a folder also affects the assets and subfolders it contains.

Sample Response
Status|200 OK
123456
{
  "notice": "string",
  "uid": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_by": "string"
}
Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

Query Parameters

skipoptionalstring

The skip parameter skips a specific number of items in the output. For example, if there are 20 items and you want to skip the first 2 to get only the last 18 in the response body, specify 2 here.

limitoptionalstring

The limit parameter returns a specific number of items (between 0 and 100) in your response based on the value you provide.

sortoptionalstring

Enter the field name to sort the results by, such as created_at or title.

orderoptionalstring

Enter the sort order of the results. Accepted values are asc for ascending and desc for descending.

parent_uidoptionalstring

Enter the uid of the parent folder to fetch only the subfolders within that folder.

workspaceoptionalstring

Enter the uid of the workspace to scope the results to a single workspace.

include_acloptionalstring

Set to true to include the access control list (ACL) of each folder in the response. Default is false.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.

Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

folder_uidrequiredstring

Enter the uid of the folder that you want to retrieve.

Query Parameters

restore_with_assetsoptionalstring

Set to true to restore the folder along with the assets it contained. Default is false.

workspaceoptionalstring

The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.

Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

folder_uidrequiredstring

Enter the uid of the folder that you want to retrieve.

Query Parameters

workspaceoptionalstring

The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.

Body Parameters

titleoptionalstring

The updated title of the folder.

descriptionoptionalstring

The updated description of the folder.

parent_uidoptionalstring

The uid of the folder to move this folder to.

Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

folder_uidrequiredstring

Enter the uid of the folder that you want to retrieve.

Query Parameters

include_acloptionalstring

Set to true to include the access control list (ACL) of the folder in the response. Default is false.

workspaceoptionalstring

The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.

Hide Parameters

URL Parameters

space_uidrequiredstring

Enter the uid of the space that you want to retrieve.

folder_uidrequiredstring

Enter the uid of the folder that you want to retrieve.

Query Parameters

workspaceoptionalstring

The workspace to work in. Defaults to the space’s default workspace, so a request that omits this parameter cannot see an asset held in any other workspace and fails with 404. Pass the workspace uid whenever you work outside the default, for example when a workspace is linked to a branch other than main.

Headers

authorizationoptionalstring

OAuth access token authentication. Pass the token in the authorization header as Bearer <token>. This header takes an OAuth access token. It does not take a management token, and management tokens are not supported by this API.

Authentication is required. Every request must carry either this header or the authtoken header; a request with neither is rejected.

authtokenoptionalstring

Contentstack authtoken authentication. Pass your Contentstack authtoken in the authtoken header.

This is your authtoken, not your stack api_key and not a management token. OpenAPI classifies any credential sent in a header as an API key, which is why some documentation viewers label this scheme apiKey. That label refers to the transport, not to a Contentstack API key.

Authentication is required. Every request must carry either this header or the authorization header; a request with neither is rejected.

x-cs-api-versionrequiredstring

Enter the Assets API version. Default is 4.