Sample - Box Platform API
POST/files/{file_id}/copy

Copy a file

Creates a copy of a file in a destination folder. Supply parent.id to select the destination, and optionally use name or version to control the copied file. Use fields to request additional attributes in the returned file representation.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 3 body fields
file_idstringrequired
The unique identifier of the file to copy.
fieldsarray<string>optional
A comma-separated list of file attributes to include in the response. When supplied, request the standard fields you need explicitly.

Optional copy settings. The parent object identifies the destination folder, while name and version can customize the copied file.

namestringoptional
An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), and protected names like `.` and `..` are automatically sanitized by removing the non-allowed characters.
versionstringoptional
An optional ID of the specific file version to copy.
parentobjectrequired
The destination folder to copy the file to.

7 status codes
201Returns the new file object representing the copied file. The response includes the default file representation and any attributes requested through `fields`.
idstringrequired
The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.
etagstringoptional
The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.
typestringrequired
The value will always be `file`.
Allowed:file
sequence_idobjectoptional
namestringoptional
The name of the file.
sha1stringoptional
The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionobjectoptional
descriptionstringoptional
The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored.
sizeintegeroptional
The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
path_collectionobjectoptional
created_atstringoptional
The date and time when the file was created on Box.
modified_atstringoptional
The date and time when the file was last updated on Box.
trashed_atstringoptional
The time at which this file was put in the trash.
purged_atstringoptional
The time at which this file is expected to be purged from the trash.
content_created_atstringoptional
The date and time at which this file was originally created, which might be before it was uploaded to Box.
content_modified_atstringoptional
The date and time at which this file was last updated, which might be before it was uploaded to Box.
created_byobjectoptional
modified_byobjectoptional
owned_byobjectoptional
shared_linkobjectoptional
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
version_numberstringoptional
The version number of this file.
comment_countintegeroptional
The number of comments on this file.
permissionsobjectoptional
tagsobjectoptional
lockobjectoptional
extensionstringoptional
Indicates the (optional) file extension for this file. By default, this is set to an empty string.
is_packagebooleanoptional
Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.
expiring_embed_linkobjectoptional
watermark_infoobjectoptional
is_accessible_via_shared_linkbooleanoptional
Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.
allowed_invitee_rolesarray<string>optional
A list of the types of roles that user can be invited at when sharing this file.
is_externally_ownedbooleanoptional
Specifies if this file is owned by a user outside of the authenticated enterprise.
has_collaborationsbooleanoptional
Specifies if this file has any other collaborators.
metadataobjectoptional
expires_atstringoptional
When the file will automatically be deleted.
representationsobjectoptional
classificationobjectoptional
uploader_display_nameobjectoptional
disposition_atstringoptional
The retention expiration timestamp for the given file.
shared_link_permission_optionsarray<string>optional
A list of the types of roles that user can be invited at when sharing this file.
is_associated_with_app_itembooleanoptional
This field will return true if the file or any ancestor of the file 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 file.
collectionsarray<Collection>optional
The collections that this file belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).
is_download_availablebooleanoptional
Whether the file's binary content is eligible to be downloaded. This is a content-level flag and does not reflect whether the current user is authorized to download the file. Use `permissions.can_download`, when available, for that.
download_urlstringoptional
A pre-authorized, expiring URL for directly downloading the file's content. Requires authentication and is valid only for the current session. This field is only returned for files, not folders or web links.
authenticated_download_urlstringoptional
A stable API URL for the file content endpoint, `/2.0/files/{id}/content`. Unlike `download_url`, authorization is evaluated when the URL is requested with a valid access token. This field is only returned for files, not folders or web links.
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 file. The list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user.
304Returned when the `If-None-Match` header matches the file's current `etag`, indicating that the file has not changed since it was last requested.
400Returned when a parameter is missing or invalid.
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 the authenticated user does not have permission to copy the file, including when information barrier restrictions forbid the operation.
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 source file or destination folder cannot be found or the authenticated user cannot access either resource.
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 a source or destination folder is locked by another operation, or when a file 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.
defaultReturned when an unexpected client error occurs.
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 a parameter is missing or invalid. A 403 is returned when the authenticated user lacks permission to copy the file, and a 404 is returned when the source file or destination folder cannot be found or accessed. A 409 is returned when a source or destination folder is locked or a file with the requested name already exists; parent.id must identify the destination folder.