BObox
Files

Update file

Changed on

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

put/files/{file_id}

Request

  • Base URL
    https://api.box.com/2.0
  • URL
    https://api.box.com/2.0/files/{file_id}
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Path parameters

file_idstring required

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

fieldsstring[]

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.

Headers

if-matchstring

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.

Request body

namestring

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.

descriptionstring

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.

disposition_atstring date-time

The retention expiration timestamp for the given file. This date cannot be shortened once set on a file.

tagsstring[]

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.

Example request

{
  "name": "NewFile.txt",
  "description": "The latest reports. Automatically updated",
  "parent": {
    "id": "123",
    "user_id": "12346930"
  },
  "shared_link": {
    "access": "open",
    "password": "do-n8t-use-this-Password",
    "vanity_name": "my-shared-link",
    "unshared_at": "2012-12-12T10:53:43-08:00",
    "permissions": {
      "can_download": true
    },
    "one_time_passcode": {
      "mode": "none"
    }
  },
  "lock": {
    "access": "lock",
    "expires_at": "2012-12-12T10:53:43-08:00",
    "is_download_prevented": true
  },
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "permissions": {
    "can_download": "open"
  },
  "collections": [
    {
      "id": "11446498",
      "type": "file"
    }
  ],
  "tags": [
    "approved"
  ]
}

Response

Returns a file object.

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

idstring required

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.

etagstring nullable

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.

type'file' required

The value will always be file.

sequence_idstring

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

namestring

The name of the file.

sha1string digest

The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.

descriptionstring

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.

sizeinteger

The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.

created_atstring date-time

The date and time when the file was created on Box.

modified_atstring date-time

The date and time when the file was last updated on Box.

trashed_atstring date-time nullable

The time at which this file was put in the trash.

purged_atstring date-time nullable

The time at which this file is expected to be purged from the trash.

content_created_atstring date-time nullable

The date and time at which this file was originally created, which might be before it was uploaded to Box.

content_modified_atstring date-time nullable

The date and time at which this file was last updated, which might be before it was uploaded to Box.

item_status'active' | 'trashed' | 'deleted'

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.
version_numberstring

The version number of this file.

comment_countinteger

The number of comments on this file.

tagsstring[]

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.

extensionstring

Indicates the (optional) file extension for this file. By default, this is set to an empty string.

is_packageboolean

Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.

is_accessible_via_shared_linkboolean

Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.

allowed_invitee_rolesstring[]

A list of the types of roles that user can be invited at when sharing this file.

is_externally_ownedboolean

Specifies if this file is owned by a user outside of the authenticated enterprise.

has_collaborationsboolean

Specifies if this file has any other collaborators.

metadataobject

An object containing the metadata instances that have been attached to this file.

Each metadata instance is uniquely identified by its scope and templateKey. There can only be one instance of any metadata template attached to each file. Each metadata instance is nested within an object with the templateKey as the key, which again itself is nested in an object with the scope as the key.

expires_atstring date-time nullable

When the file will automatically be deleted.

uploader_display_namestring

The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload.

If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of File Request.

In all other anonymous cases where no email was provided this field will default to a value of Someone.

disposition_atstring date-time nullable

The retention expiration timestamp for the given file.

shared_link_permission_optionsstring[] nullable

A list of the types of roles that user can be invited at when sharing this file.

is_associated_with_app_itemboolean

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.

is_download_availableboolean

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_urlstring url

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_urlstring url

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_levelsstring[]

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.

Example response

{
  "id": "12345",
  "etag": "1",
  "type": "file",
  "sequence_id": "3",
  "name": "Contract.pdf",
  "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
  "file_version": {
    "id": "12345",
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  },
  "description": "Contract for Q1 renewal",
  "size": 629644,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      }
    ]
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "purged_at": "2012-12-12T10:53:43-08:00",
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "shared_link": {
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "vanity_url": "https://acme.app.box.com/v/my_url/",
    "vanity_name": "my_url",
    "access": "open",
    "effective_access": "company",
    "effective_permission": "can_download",
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_preview": true
    },
    "download_count": 3,
    "preview_count": 3,
    "one_time_passcode": {
      "mode": "allowlist",
      "allowlist": [
        {
          "type": "email",
          "value": "alice@example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        },
        {
          "type": "domain",
          "value": "example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        }
      ]
    }
  },
  "parent": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "item_status": "active",
  "version_number": "1",
  "comment_count": 10,
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_annotate": true,
    "can_comment": true,
    "can_preview": true,
    "can_upload": true,
    "can_view_annotations_all": true,
    "can_view_annotations_self": true,
    "can_apply_watermark": true
  },
  "tags": [
    "approved"
  ],
  "lock": {
    "id": "11446498",
    "type": "lock",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "expired_at": "2012-12-12T10:53:43-08:00",
    "is_download_prevented": true,
    "app_type": "office_wopiplus"
  },
  "extension": "pdf",
  "is_package": true,
  "expiring_embed_link": {
    "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "restricted_to": [
      {
        "scope": "item_download",
        "object": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      }
    ],
    "url": "https://cloud.app.box.com/preview/expiring_embed/..."
  },
  "watermark_info": {
    "is_watermarked": true
  },
  "is_accessible_via_shared_link": true,
  "allowed_invitee_roles": [
    "editor"
  ],
  "is_externally_owned": true,
  "has_collaborations": 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
      }
    }
  },
  "expires_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"
        }
      }
    ]
  },
  "classification": {
    "name": "Top Secret",
    "definition": "Content that should not be shared outside the company.",
    "color": "#FF0000"
  },
  "uploader_display_name": "Ellis Wiggins",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "shared_link_permission_options": [
    "can_preview"
  ],
  "is_associated_with_app_item": true,
  "collections": [
    {
      "id": "11446498",
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites"
    }
  ],
  "is_download_available": true,
  "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
  "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
  "allowed_shared_link_access_levels": [
    "open"
  ]
}

Changes

  • c4d5303fa5c3Revision changes
    • breaking

      added subschema #1 subschema #2 to the request property allOf list

    • breaking

      the response property // became nullable for the status

    • breaking

      the response property / became nullable for the status

    • warning

      removed subschema #1 subschema #2 from the request property allOf list

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added subschema #1 to the / response property allOf list for the response status

    • info

      added subschema #1 subschema #2 to the // response property allOf list for the response status

    • info

      added subschema #1 subschema #2 to the / response property allOf list for the response status

    • info

      added subschema #2 to the // response property allOf list for the response status

    • info

      added subschema #2 subschema #3 to the //// response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the // response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the / response property allOf list for the response status

    • info

      removed subschema #1 subschema #3 from the / response property allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the // response property allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the //// response property allOf list for the response status

    • info

      added the required property //// to the response with the status