Sample - Box Platform API
POST/folders/{folder_id}/copy

Copy folder

Creates a copy of a folder within a destination folder.

The original folder will not be changed.

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

2 parameters · 2 body fields
folder_idstringrequired
The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied.
fieldsarray<string>optional
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.
namestringoptional
An optional new name for the copied 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.
parentobjectrequired
The destination folder to copy the folder to.

8 status codes
201Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.
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).
304Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested.
400Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. * `item_name_too_long` when the new folder name is too long.
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.
403Returns an error when the user does not have the right permissions to copy a folder. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions.
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.
404Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders. * `not_found` when the authenticated user does not have access to 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.
409Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked. * `item_name_in_use` when a folder with the same name already exists.
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.
500Returns an error when trying to copy the root 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: Returns an error if some of the parameters are missing or not valid.

  • bad_request when a parameter is missing.

  • item_name_too_long when the new folder name is too long. A 403 is returned: Returns an error when the user does not have the right permissions to copy a folder.

  • forbidden_by_policy: Returned if copying a folder is forbidden due to information barrier restrictions. A 404 is returned: Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders.

  • not_found when the authenticated user does not have access to the parent folder. A 409 is returned: Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked.

  • item_name_in_use when a folder with the same name already exists. A 500 is returned: Returns an error when trying to copy the root folder. Any other status is an error: An unexpected client error.