Updates a file. This can be used to rename or move a file, create a shared link, or lock a file.
12345
The unique identifier that represents 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
.
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.
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 endpoint.
Passing an empty array []
or null
will remove
the file from all collections.
"11446498"
The unique identifier for this object
"file"
The type for this object
"The latest reports. Automatically updated"
256
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.
"2012-12-12T10:53:43-08:00"
The retention expiration timestamp for the given file. This date cannot be shortened once set on a file.
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.
"lock"
The type of this object.
Value is always lock
"2012-12-12T10:53:43-08:00"
Defines the time at which the lock expires.
true
Defines if the file can be downloaded while it is locked.
"NewFile.txt"
An optional different name for the file. This can be used to rename the file.
An optional new parent folder for the file. This can be used to move the file to a new folder.
"123"
The ID of parent item
Defines who can download a file.
"open"
Defines who is allowed to download this file. The possible
values are either open
for everyone or company
for
the other members of the user's enterprise.
This setting overrides the download permissions that are
normally part of the role
of a collaboration. When set to
company
, this essentially removes the download option for
external users with viewer
or editor
a roles.
Value is one of open
,company
["approved"]
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.
1
Ensures this item hasn't recently changed before making changes.
Pass in the item's last observed etag
value
into this header and the endpoint will fail
with a 412 Precondition Failed
if it
has changed since.
Returns a file object.
Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.
Returned when the new retention time > maximum retention length.
Returned when the access token provided in the Authorization
header
is not recognized or not provided.
Returned if the user does not have all the permissions to complete the update.
access_denied_insufficient_permissions
returned
when the authenticated user does not have access
to the destination folder to move the file to.file_id
that is not under retention is entered.remove_retention
forbidden_by_policy
is returned if copying a folder is
forbidden due to information barrier restrictions.Returned if the file is not found, or the user does not have access to the file.
Returned if the file_id
is not in a recognized format.
Returns an error when the If-Match
header does not match
the current etag
value of the file. This indicates that the file
has changed since it was last requested.
An unexpected client error.
curl -i -X PUT "https://api.box.com/2.0/files/12345" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"name": "New name"
}'
await downscopedClient.files.updateFileById(file.id, {
requestBody: { name: getUuid() } satisfies UpdateFileByIdRequestBody,
} satisfies UpdateFileByIdOptionalsInput);
downscoped_client.files.update_file_by_id(file.id, name=get_uuid())
await downscopedClient.Files.UpdateFileByIdAsync(fileId: file.Id, requestBody: new UpdateFileByIdRequestBody() { Name = Utils.GetUUID() });
try await downscopedClient.files.updateFileById(fileId: file.id, requestBody: UpdateFileByIdRequestBody(name: Utils.getUUID()))
BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.new Info();
info.setName("New Name");
file.updateInfo(info);
file_id = '11111'
updated_file = client.file(file_id).update_info(data={'description': 'My file'})
// Rename file 11111
var requestParams = new BoxFileRequest()
{
Id = "11111",
Name = "New name.pdf"
};
BoxFile updatedFile = await client.FilesManager.UpdateInformationAsync(requestParams);
client.files.update('75937', { name : 'New name.pdf', fields: 'name' })
.then(updatedFile => {
/* updatedFile => {
type: 'file',
id: '11111',
name: 'New name.pdf'
}
*/
});
client.files.update(fileId: "11111", name: "New file name.docx") { (result: Result<File, BoxSDKError>) in
guard case let .success(file) = result else {
print("Error updating file information")
return
}
print("File \(file.name) was updated at \(file.modifiedAt)")
}
{
"id": "12345",
"type": "file",
"allowed_invitee_roles": [
"editor"
],
"classification": {
"color": "#FF0000",
"definition": "Content that should not be shared outside the company.",
"name": "Top Secret"
},
"comment_count": 10,
"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",
"disposition_at": "2012-12-12T10:53:43-08:00",
"etag": "1",
"expires_at": "2012-12-12T10:53:43-08:00",
"expiring_embed_link": {
"access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
"expires_in": 3600,
"restricted_to": [
{
"scope": "item_download",
"object": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
}
],
"token_type": "bearer",
"url": "https://cloud.app.box.com/preview/expiring_embed/..."
},
"extension": "pdf",
"file_version": {
"id": "12345",
"type": "file_version",
"sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
},
"has_collaborations": true,
"is_accessible_via_shared_link": true,
"is_associated_with_app_item": true,
"is_externally_owned": true,
"is_package": true,
"item_status": "active",
"lock": {
"id": "11446498",
"type": "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",
"is_download_prevented": true
},
"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": "Contract.pdf",
"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": [
{
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
],
"total_count": 1
},
"permissions": {
"can_annotate": true,
"can_comment": true,
"can_delete": true,
"can_download": true,
"can_invite_collaborator": true,
"can_preview": true,
"can_rename": true,
"can_set_share_access": true,
"can_share": true,
"can_upload": true,
"can_view_annotations_all": true,
"can_view_annotations_self": true
},
"purged_at": "2012-12-12T10:53:43-08:00",
"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"
}
}
]
},
"sequence_id": "3",
"sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
"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/"
},
"shared_link_permission_options": [
"can_preview"
],
"size": 629644,
"tags": [
"approved"
],
"trashed_at": "2012-12-12T10:53:43-08:00",
"uploader_display_name": "Ellis Wiggins",
"version_number": "1",
"watermark_info": {
"is_watermarked": true
}
}