Sample - Box Platform API
PUT/files/{file_id}

Update file information

Updates a file's name, description, location, sharing settings, lock, retention, permissions, collections, or tags. Send only the properties you want to change, and use if-match when you need to prevent updates based on a stale file version.

3 parameters · 9 body fields
file_idstringrequired
The unique identifier of the file to update.
fieldsarray<string>optional
A comma-separated list of attributes to include in the updated file response.
if-matchstringoptional
The file's previously observed ETag for optimistic concurrency control; the update proceeds only when it matches the current ETag.

Optional file properties to update, including naming, location, sharing, retention, permissions, collections, and tags.

namestringoptional
An optional different name for the file. This can be used to rename the file. File names must be unique within their parent folder. The name check is case-insensitive, so a file named `New File` cannot be created in a parent folder that already contains a folder named `new file`.
descriptionstringoptional
The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description.
parentobjectoptional
The new parent folder for moving the file, identified by its `id` and optionally its `user_id`.
shared_linkobjectoptional
Shared-link settings for the file, or `null` to remove the shared link.
lockobjectoptional
Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to `null` to remove the lock.
disposition_atstringoptional
The retention expiration timestamp for the given file. This date cannot be shortened once set on a file.
permissionsobjectoptional
Defines who can download a file.
collectionsarray<Reference>optional
An array of collections to make this file a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the file from all collections. [1]: https://developer.box.com/reference/get-collections
tagsarray<string>optional
The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

8 status codes
200Returns the updated file object with the requested changes applied.
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.
400Returned when the new retention time exceeds the maximum retention length.
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.
401Returned when the access token in the `Authorization` header is missing or not recognized.
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 lacks permission to complete the update, including destination-folder, retention, or policy 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.
404Returned when the file is not found or the authenticated user does 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.
405Returned when `file_id` is not in a recognized format.
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.
412Returned when the `if-match` ETag does not match the file's current ETag, indicating that the file changed after it was retrieved.
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 the new retention time exceeds the maximum retention length, and a 401 is returned when the access token is missing or unrecognized. A 403 is returned when the authenticated user lacks permission, a 404 when the file is unavailable, a 405 when file_id has an unrecognized format, and a 412 when if-match does not match the current ETag. The description cannot exceed 256 characters, tags must contain 1 to 100 items, and permissions.can_download must be open or company.