Box Developer Documentation
Log in
Latest version

Update file

put
https://api.box.com/2.0
/files/:file_id

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Updates a file. This can be used to rename or move a file, create a shared link, or lock a file.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Request Headers

stringin headeroptional
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.

Path Parameters

stringin pathrequired
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.

Query Parameters

string arrayin queryoptional
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.

Request Body

object arrayin bodyoptional

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.

stringin bodyoptional
"11446498"

The unique identifier for this object

stringin bodyoptional
"file"

The type for this object

stringin bodyoptional
"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.

string (date-time)in bodyoptional
"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.

objectin body

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.

stringin bodyoptional
"lock"

The type of this object.

Value is always lock

string (date-time)in bodyoptional
"2012-12-12T10:53:43-08:00"

Defines the time at which the lock expires.

booleanin bodyoptional
true

Defines if the file can be downloaded while it is locked.

stringin bodyoptional
"NewFile.txt"

An optional different name for the file. This can be used to rename the file.

objectin body

An optional new parent folder for the file. This can be used to move the file to a new folder.

stringin bodyoptional
"123"

The ID of parent item

stringin bodyoptional
"12346930"

The input for user_id is optional. Moving to non-root folder is not allowed when user_id is present. Parent folder id should be zero when user_id is provided.

objectin body

Defines who can download a file.

stringin bodyoptional
"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

objectin body

Defines a shared link for a file. Set this to null to remove the shared link.

stringin bodyoptional
"open"

The level of access for the shared link. This can be restricted to anyone with the link (open), only people within the company (company) and only those who have been invited to the folder (collaborators).

If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the shared_link object with no access field, for example { "shared_link": {} }.

The company access level is only available to paid accounts.

Value is one of open,company,collaborators

stringin bodyoptional
"do-n8t-use-this-Password"

The password required to access the shared link. Set the password to null to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when access is set to open.

objectin body
booleanin bodyoptional
true

If the shared link allows for downloading of files. This can only be set when access is set to open or company.

string (date-time)in bodyoptional
"2012-12-12T10:53:43-08:00"

The timestamp at which this shared link will expire. This field can only be set by users with paid accounts.

stringin bodyoptional
"my-shared-link"

Defines a custom vanity name to use in the shared link URL, for example https://app.box.com/v/my-shared-link.

Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.

string arrayin bodyoptional
["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.

Response

application/jsonFile (Full)

Returns a file object.

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.

application/jsonClient error

Returned when the new retention time > maximum retention length.

application/jsonClient error

Returned when the access token provided in the Authorization header is not recognized or not provided.

application/jsonClient error

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.
  • Returned when retention time is shorter or equal to current retention timestamp.
  • Returned when a file_id that is not under retention is entered.
  • Returned when a file that is retained but the disposition action is set to remove_retention
  • forbidden_by_policy is returned if copying a folder is forbidden due to information barrier restrictions.
application/jsonClient error

Returned if the file is not found, or the user does not have access to the file.

application/jsonClient error

Returned if the file_id is not in a recognized format.

application/jsonClient error

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.

application/jsonClient error

An unexpected client error.

put
Update file
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
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"
     }'
TypeScript Gen
await client.files.updateFileById(fileToUpdate.id, {
  requestBody: {
    name: updatedName,
    description: 'Updated description',
  } satisfies UpdateFileByIdRequestBody,
} satisfies UpdateFileByIdOptionalsInput);
Python Gen
client.files.update_file_by_id(
    file_to_update.id, name=updated_name, description="Updated description"
)
.NET Gen
await client.Files.UpdateFileByIdAsync(fileId: fileToUpdate.Id, requestBody: new UpdateFileByIdRequestBody() { Name = updatedName, Description = "Updated description" });
Swift Gen (Beta)
try await client.files.updateFileById(fileId: fileToUpdate.id, requestBody: UpdateFileByIdRequestBody(name: updatedName, description: "Updated description"))
Java
BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.new Info();
info.setName("New Name");
file.updateInfo(info);
Python
file_id = '11111'
updated_file = client.file(file_id).update_info(data={'description': 'My file'})
.NET
// Rename file 11111
var requestParams = new BoxFileRequest()
{
    Id = "11111",
    Name = "New name.pdf"
};
BoxFile updatedFile = await client.FilesManager.UpdateInformationAsync(requestParams);
Node
client.files.update('75937', { name : 'New name.pdf', fields: 'name' })
	.then(updatedFile => {
		/* updatedFile => {
			type: 'file',
			id: '11111',
			name: 'New name.pdf'
		}
		*/
	});
iOS
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)")
}

Response Example

{
  "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": [
      {
        "object": {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        },
        "scope": "item_download"
      }
    ],
    "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": [
      {
        "etag": "1",
        "id": "12345",
        "type": "folder",
        "name": "Contracts",
        "sequence_id": "3"
      }
    ],
    "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
  }
}