Box Developer Documentation
Log in
Latest version

Create folder

post
https://api.box.com/2.0
/folders

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Creates a new empty folder within the specified parent folder.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Query Parameters

string arrayin queryoptional
id,type,name

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Request Body

objectin body

Setting this object enables the upload email address.

This email address can be used by users to directly upload files directly to the folder via email.

stringin bodyoptional
"open"

When this parameter has been set, users can email files to the email address that has been automatically created for this folder.

To create an email address, set this property either when creating or updating the folder.

When set to collaborators, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered.

When set to open it will accept emails from any email address.

Value is one of open,collaborators

stringin bodyrequired
"New Folder"
255

The name for the new folder.

There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (/, \), as well as names with trailing spaces are prohibited.

Additionally, the names . and .. are not allowed either.

objectin body

The parent folder to create the new folder within.

stringin bodyrequired
"0"

The ID of parent folder

stringin bodyoptional
"synced"

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Value is one of synced,not_synced,partially_synced

Response

application/jsonFolder (Full)

Returns a folder object.

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.

application/jsonClient error

Returns an error if some of the parameters are missing or not valid.

  • bad_request when a parameter is missing or incorrect.
  • item_name_too_long when the folder name is too long.
  • item_name_invalid when the folder name contains non-valid characters.
application/jsonClient error

Returns an error if the user does not have the required access to perform the action. This might be because they don't have access to the folder or parent folder, or because the application does not have permission to write files and folders.

application/jsonClient error

Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder.

  • not_found when the authenticated user does not have access to the parent folder
application/jsonClient error

  • operation_blocked_temporary: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process.

    The operation can be retried at a later point.

  • item_name_in_use: Returned if a folder with the name already exists in the parent folder.

application/jsonClient error

An unexpected client error.

post
Create folder
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X POST "https://api.box.com/2.0/folders" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "name": "New Folder",
       "parent": {
         "id": "0"
       }
     }'
TypeScript Gen
await client.folders.createFolder({
  name: newFolderName,
  parent: { id: '0' } satisfies CreateFolderRequestBodyParentField,
} satisfies CreateFolderRequestBody);
Python Gen
client.folders.create_folder(new_folder_name, CreateFolderParent(id="0"))
.NET Gen
await client.Folders.CreateFolderAsync(requestBody: new CreateFolderRequestBody(name: newFolderName, parent: new CreateFolderRequestBodyParentField(id: "0")));
Swift Gen (Beta)
try await client.folders.createFolder(requestBody: CreateFolderRequestBody(name: newFolderName, parent: CreateFolderRequestBodyParentField(id: "0")))
Java
BoxFolder parentFolder = new BoxFolder(api, "id");
BoxFolder.Info childFolderInfo = parentFolder.createFolder("Child Folder Name");
Python
subfolder = client.folder('0').create_subfolder('My Stuff')
print(f'Created subfolder with ID {subfolder.id}')
.NET
// Create a new folder in the user's root folder
var folderParams = new BoxFolderRequest()
{
    Name = "New folder",
    Parent = new BoxRequestEntity()
    {
        Id = "0"
    }
};
BoxFolder folder = await client.FoldersManager.CreateAsync(folderParams);
Node
client.folders.create('0', 'New Folder')
    .then(folder => {
        /* folder -> {
            type: 'folder',
            id: '123456',
            sequence_id: '0',
            etag: '0',
            name: 'New Folder',
            created_at: '2012-12-12T10:53:43-08:00',
            modified_at: '2012-12-12T11:15:04-08:00',
            description: '',
            size: 0,
            path_collection: 
            { total_count: 1,
                entries: 
                [ { type: 'folder',
                    id: '0',
                    sequence_id: null,
                    etag: null,
                    name: 'All Files' } ] },
            created_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User'
                login: 'user@example.com' },
            modified_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            owned_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            shared_link: null,
            parent: 
            { type: 'folder',
                id: '0',
                sequence_id: null,
                etag: null,
                name: 'All Files' },
            item_status: 'active',
            item_collection: 
            { total_count: 0,
                entries: [],
                offset: 0,
                limit: 100 } }
        */
    });
iOS
client.folders.create(name: "New Folder", parentId: "22222") { (result: Result<Folder, BoxSDKError>) in
    guard case let .success(folder) = result else {
        print("Error creating folder")
        return
    }

    print("Created folder \"\(folder.name)\" inside of folder \"\(folder.parent?.name)\"")
}

Response Example

{
  "id": "12345",
  "type": "folder",
  "allowed_invitee_roles": [
    "editor"
  ],
  "allowed_shared_link_access_levels": [
    "open"
  ],
  "can_non_owners_invite": true,
  "can_non_owners_view_collaborators": true,
  "classification": {
    "color": "#FF0000",
    "definition": "Content that should not be shared outside the company.",
    "name": "Top Secret"
  },
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "description": "Legal contracts for the new ACME deal",
  "etag": "1",
  "folder_upload_email": {
    "access": "open",
    "email": "upload.Contracts.asd7asd@u.box.com"
  },
  "has_collaborations": true,
  "is_accessible_via_shared_link": true,
  "is_associated_with_app_item": true,
  "is_collaboration_restricted_to_enterprise": true,
  "is_externally_owned": true,
  "item_collection": {
    "entries": [
      {
        "etag": "1",
        "id": "12345",
        "type": "file",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "name": "Contract.pdf",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "description": "Contract for Q1 renewal",
        "item_status": "active",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "parent": {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        },
        "path_collection": {
          "entries": [
            {
              "etag": "1",
              "id": "12345",
              "type": "folder",
              "name": "Contracts",
              "sequence_id": "3"
            }
          ],
          "total_count": 1
        },
        "purged_at": "2012-12-12T10:53:43-08:00",
        "shared_link": {
          "access": "open",
          "download_count": 3,
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "effective_access": "company",
          "effective_permission": "can_download",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_edit": false,
            "can_preview": true
          },
          "preview_count": 3,
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "vanity_name": "my_url",
          "vanity_url": "https://acme.app.box.com/v/my_url/"
        },
        "size": 629644,
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "allowed_invitee_roles": [
          "editor"
        ],
        "classification": {
          "color": "#FF0000",
          "definition": "Content that should not be shared outside the company.",
          "name": "Top Secret"
        },
        "comment_count": 10,
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "expires_at": "2012-12-12T10:53:43-08:00",
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "restricted_to": [
            {
              "object": {
                "etag": "1",
                "id": "12345",
                "type": "folder",
                "name": "Contracts",
                "sequence_id": "3"
              },
              "scope": "item_download"
            }
          ],
          "token_type": "bearer",
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "extension": "pdf",
        "has_collaborations": true,
        "is_accessible_via_shared_link": true,
        "is_associated_with_app_item": true,
        "is_externally_owned": true,
        "is_package": true,
        "lock": {
          "app_type": "office_wopiplus",
          "created_at": "2012-12-12T10:53:43-08:00",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "login": "ceo@example.com",
            "name": "Aaron Levie"
          },
          "expired_at": "2012-12-12T10:53:43-08:00",
          "id": "11446498",
          "is_download_prevented": true,
          "type": "lock"
        },
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true
        },
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "shared_link_permission_options": [
          "can_preview"
        ],
        "tags": [
          "approved"
        ],
        "uploader_display_name": "Ellis Wiggins",
        "version_number": "1",
        "watermark_info": {
          "is_watermarked": true
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000
  },
  "item_status": "active",
  "metadata": {
    "enterprise_27335": {
      "marketingCollateral": {
        "$canEdit": true,
        "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
        "$parent": "folder_59449484661",
        "$scope": "enterprise_27335",
        "$template": "marketingCollateral",
        "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
        "$typeVersion": 2,
        "$version": 1
      }
    }
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "name": "Contracts",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "parent": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "path_collection": {
    "entries": [
      {
        "etag": "1",
        "id": "12345",
        "type": "folder",
        "name": "Contracts",
        "sequence_id": "3"
      }
    ],
    "total_count": 1
  },
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "sequence_id": "3",
  "shared_link": {
    "access": "open",
    "download_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_edit": false,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_name": "my_url",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "size": 629644,
  "sync_state": "synced",
  "tags": [
    "approved"
  ],
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "watermark_info": {
    "is_watermarked": true
  }
}