---
title: "Folders"
description: "<p>Organize assets into hierarchical folders.</p>"
url: "https://www.contentstack.com/docs/developers/apis/assets-api/folders"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-08-21"
---

# Folders

Organize assets into hierarchical folders.

## Create a folder

### Create a folder

**POST** `/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.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.

#### Query Parameters

- **workspace** (optional)
  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

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "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

### Get all folders

**GET** `/api/spaces/{space_uid}/folders`

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

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.

#### Query Parameters

- **skip** (optional)
  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.
- **limit** (optional)
  The limit parameter returns a specific number of items (between 0 and 100) in your response based on the value you provide.
- **sort** (optional)
  Enter the field name to sort the results by, such as created\_at or title.
- **order** (optional)
  Enter the sort order of the results. Accepted values are asc for ascending and desc for descending.
- **parent_uid** (optional)
  Enter the uid of the parent folder to fetch only the subfolders within that folder.
- **workspace** (optional)
  Enter the uid of the workspace to scope the results to a single workspace.
- **include_acl** (optional)
  Set to true to include the access control list (ACL) of each folder in the response. Default is false.

#### Headers

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "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
    }
  ]
}
```

## Restore a deleted folder

### Restore a deleted folder

**POST** `/api/spaces/{space_uid}/folders/{folder_uid}/restore`

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.

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **folder_uid** (required)
  Enter the uid of the folder that you want to retrieve.

#### Query Parameters

- **restore_with_assets** (optional)
  Set to true to restore the folder along with the assets it contained. Default is false.
- **workspace** (optional)
  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

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "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
  }
}
```

## Update a folder

### Update a folder

**PUT** `/api/spaces/{space_uid}/folders/{folder_uid}`

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

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **folder_uid** (required)
  Enter the uid of the folder that you want to retrieve.

#### Query Parameters

- **workspace** (optional)
  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

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "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 a folder

### Get a folder

**GET** `/api/spaces/{space_uid}/folders/{folder_uid}`

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

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **folder_uid** (required)
  Enter the uid of the folder that you want to retrieve.

#### Query Parameters

- **include_acl** (optional)
  Set to true to include the access control list (ACL) of the folder in the response. Default is false.
- **workspace** (optional)
  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

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "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
  }
}
```

## Delete a folder

### Delete a folder

**DELETE** `/api/spaces/{space_uid}/folders/{folder_uid}`

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

#### URL Parameters

- **space_uid** (required)
  Enter the uid of the space that you want to retrieve.
- **folder_uid** (required)
  Enter the uid of the folder that you want to retrieve.

#### Query Parameters

- **workspace** (optional)
  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

- **authorization** (optional)
  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.
- **authtoken** (optional)
  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-version** (required)
  Enter the Assets API version. Default is 4.

#### Sample Response

```json
{
  "notice": "string",
  "uid": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "updated_by": "string"
}
```