Sample - Box Platform API
POST/folders

Create a folder

Creates a new empty folder within a specified parent folder. Supply name and the parent folder's id, and optionally configure synchronization, folder upload email, or response fields. Folder names must be unique within the parent and comply with the documented naming restrictions.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 4 body fields
fieldsarray<string>optional
A comma-separated list of attributes to include in the response; when provided, standard fields are not returned unless you request them explicitly.

Folder creation details. name and parent are required.

namestringrequired
The name for the new folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`.
parentobjectrequired
The parent folder to create the new folder within.
folder_upload_emailobjectoptional
Settings that enable an email address for uploading files directly to the folder.
sync_statestringoptional
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.
Allowed:syncednot_syncedpartially_synced

6 status codes
201Returns the created folder object. Use `fields` to request attributes that are not included by default.
idstringrequired
The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.
etagstringoptional
The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.
typestringrequired
The value will always be `folder`.
Allowed:folder
sequence_idobjectoptional
namestringoptional
The name of the folder.
created_atstringoptional
The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder.
modified_atstringoptional
The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder.
descriptionobjectoptional
sizeintegeroptional
The folder size in bytes. Be careful parsing this integer as its value can get very large.
path_collectionobjectoptional
created_byobjectoptional
modified_byobjectoptional
trashed_atstringoptional
The time at which this folder was put in the trash.
purged_atstringoptional
The time at which this folder is expected to be purged from the trash.
content_created_atstringoptional
The date and time at which this folder was originally created.
content_modified_atstringoptional
The date and time at which this folder was last updated.
owned_byobjectoptional
shared_linkobjectoptional
folder_upload_emailobjectoptional
The `folder_upload_email` parameter is not `null` if one of the following options is **true**: * The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted. * The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked). If the conditions are not met, the parameter will have the following value: `folder_upload_email: null`.
parentobjectoptional
item_statusstringoptional
Defines if this item has been deleted or not. * `active` when the item has is not in the trash * `trashed` when the item has been moved to the trash but not deleted * `deleted` when the item has been permanently deleted.
Allowed:activetrasheddeleted
item_collectionobjectoptional
sync_stateobjectoptional
has_collaborationsbooleanoptional
Specifies if this folder has any other collaborators.
permissionsobjectoptional
tagsobjectoptional
can_non_owners_inviteobjectoptional
is_externally_ownedbooleanoptional
Specifies if this folder is owned by a user outside of the authenticated enterprise.
metadataobjectoptional
is_collaboration_restricted_to_enterpriseobjectoptional
allowed_shared_link_access_levelsarray<SharedLinkAccessLevel>optional
The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder. The list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level.
allowed_invitee_rolesarray<string>optional
A list of the types of roles that user can be invited at when sharing this folder.
watermark_infoobjectoptional
is_accessible_via_shared_linkbooleanoptional
Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.
can_non_owners_view_collaboratorsbooleanoptional
Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators.
classificationobjectoptional
is_associated_with_app_itembooleanoptional
This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.
collectionsarray<Collection>optional
The collections that this folder belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).
400Returned when required parameters are missing or invalid, the folder name is too long, or the folder name contains invalid characters.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returned when you do not have the required access or application permission to create a folder.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the parent folder cannot be found or you do not have access to it.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when the parent or source folder is locked, or a folder with the same name already exists in the parent folder.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when name or parent is missing, the name is invalid or exceeds 255 characters, or another parameter is invalid. A 403 is returned when you lack permission to create the folder, a 404 when the parent identified by parent.id cannot be found or accessed, and a 409 when the parent is locked or already contains a folder with the same name.