Box Developer Documentation
Log in

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

File (Full)

A full representation of a file, as can be returned from any file API endpoints by default

This resource has a few variations that can be encountered when using the API.

The fields that are part of the full variant can be returned by API endpoints that support the fields parameter. For example, by defining the fields request parameter as id,type when requesting a file by ID, only those fields will be returned in the API response.

string
12345

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.

string
file

file

Value is always file

string array
["editor"]

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

object

Details about the classification applied to this file.

string
#FF0000

The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app.

string
Content that should not be shared outside the company.

An explanation of the meaning of this classification.

string
Top Secret

The name of the classification

integer
10

The number of comments on this file

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

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

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

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

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

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

User (Mini) object

The user who created this file

string
Contract for Q1 renewal255

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.

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

The retention expiration timestamp for the given file

string
1

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.

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

When the file will automatically be deleted

object

Requesting this field creates an expiring Box Embed URL for an embedded preview session in an iframe.

This URL will expire after 60 seconds and the session will expire after 60 minutes.

Not all file types are supported for these embed URLs. Box Embed is not optimized for mobile browsers and should not be used in web experiences designed for mobile devices. Many UI elements, like the download and print options might not show in mobile browsers.

string (token)
c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ

The requested access token.

integer (int64)
3600

The time in seconds by which this token will expire.

object array

The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.

File (Mini) / Folder (Mini) object

The file or folder resource

string
item_download

The scopes for the resource access

Value is one of annotation_edit,annotation_view_all,annotation_view_self,base_explorer,base_picker,base_preview,base_upload,item_delete,item_download,item_preview,item_rename,item_share,item_upload

string
bearer

The type of access token returned.

Value is always bearer

string (url)
https://cloud.app.box.com/preview/expiring_embed/...

The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object.

string
pdf

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

File version (Mini) object

The information about the current version of the file.

boolean
true

Specifies if this file has any other collaborators.

boolean
true

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

Value is one of true,false

boolean
true

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.

boolean
true

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

boolean
true

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

string
active

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.

Value is one of active,trashed,deleted

object

The lock held on this file. If there is no lock, this can either be null or have a timestamp in the past.

string
11446498

The unique identifier for this lock

string
lock

lock

Value is always lock

string
office_wopiplus

If the lock is managed by an application rather than a user, this field identifies the type of the application that holds the lock. This is an open enum and may be extended with additional values in the future.

Value is one of gsuite,office_wopi,office_wopiplus,other

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

The time this lock was created at.

User (Mini) object

The user who created the lock.

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

The time this lock is to expire at, which might be in the past.

boolean
true

Whether or not the file can be downloaded while locked.

associative array

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.

associative array

A list of metadata instances, nested within key-value pairs of their scope and templateKey.

Metadata instance (Full)

An instance of a metadata template, which has been applied to a file or folder.

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

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

User (Mini) object

The user who last modified this file

string
Contract.pdf

The name of the file

User (Mini) object

The user who owns this file

Folder (Mini) object

The folder that this file is located within.

object

The tree of folders that this file is contained in, starting at the root.

Folder (Mini) array

The parent folders for this item

integer (int64)
1

The number of folders in this list.

object

Describes the permissions that the current user has for this file.

boolean
true

Specifies if the user can place annotations on this file.

boolean
true

Specifies if the user can place comments on this file.

boolean
true

Specifies if the current user can delete this item.

boolean
true

Specifies if the current user can download this item.

boolean
true

Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item.

boolean
true

Specifies if the user can preview this file.

boolean
true

Specifies if the user can rename this item.

boolean
true

Specifies if the user can change the access level of an existing shared link on this item.

boolean
true

Specifies if the user can create a shared link for this item.

boolean
true

Specifies if the user can upload a new version of this file.

boolean
true

Specifies if the user view all annotations placed on this file

boolean
true

Specifies if the user view annotations placed by themselves on this file

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

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

object

A list of representations for a file that can be used to display a placeholder of the file in your application. By default this returns all representations and we recommend using the x-rep-hints header to further customize the desired representations.

object array

A list of files

object

An object containing the URL that can be used to actually fetch the representation.

string
https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567

The download URL that can be used to fetch the representation. Make sure to make an authenticated API call to this endpoint.

This URL is a template and will require the {+asset_path} to be replaced by a path. In general, for unpaged representations it can be replaced by an empty string.

For paged representations, replace the {+asset_path} with the page to request plus the extension for the file, for example 1.pdf.

When requesting the download URL the following additional query params can be passed along.

  • set_content_disposition_type - Sets the Content-Disposition header in the API response with the specified disposition type of either inline or attachment. If not supplied, the Content-Disposition header is not included in the response.

  • set_content_disposition_filename - Allows the application to define the representation's file name used in the Content-Disposition header. If not defined, the filename is derived from the source file name in Box combined with the extension of the representation.

object

An object containing the URL that can be used to fetch more info on this representation.

string
https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048

The API URL that can be used to get more info on this file representation. Make sure to make an authenticated API call to this endpoint.

object

An object containing the size and type of this presentation.

string (<width>x<height>)
2048x2048

The width by height size of this representation in pixels.

boolean
true

Indicates if the representation is build up out of multiple pages.

boolean
true

Indicates if the representation can be used as a thumbnail of the file.

string
png

Indicates the file type of the returned representation.

object

An object containing the status of this representation.

string
success

The status of the representation.

  • success defines the representation as ready to be viewed.
  • viewable defines a video to be ready for viewing.
  • pending defines the representation as to be generated. Retry this endpoint to re-check the status.
  • none defines that the representation will be created when requested. Request the URL defined in the info object to trigger this generation.

Value is one of success,viewable,pending,none

string
3

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.

string (digest)
85136C79CBF9FE36BB9D05D0639C70C265C18D37

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

object

The shared link for this file. This will be null if no shared link has been created for this file.

string
open

The access level for this shared link.

  • open - provides access to this item to anyone with this link
  • company - only provides access to this item to people the same company
  • collaborators - only provides access to this item to people who are collaborators on this item

If this field is omitted when creating the shared link, the access level will be set to the default access level specified by the enterprise admin.

Value is one of open,company,collaborators

integer
3

The number of times this item has been downloaded.

string (url)
https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg

A URL that can be used to download the file. This URL can be used in a browser to download the file. This URL includes the file extension so that the file will be saved with the right file type.

This property will be null for folders.

string
company

The effective access level for the shared link. This can be a more restrictive access level than the value in the access field when the enterprise settings restrict the allowed access levels.

Value is one of open,company,collaborators

string
can_download

The effective permissions for this shared link. These result in the more restrictive combination of the share link permissions and the item permissions set by the administrator, the owner, and any ancestor item such as a folder.

Value is one of can_edit,can_download,can_preview,no_access

boolean
true

Defines if the shared link requires a password to access the item.

object

Defines if this link allows a user to preview, edit, and download an item. These permissions refer to the shared link only and do not supersede permissions applied to the item itself.

boolean
true

Defines if the shared link allows for the item to be downloaded. For shared links on folders, this also applies to any items in the folder.

This value can be set to true when the effective access level is set to open or company, not collaborators.

boolean
false

Defines if the shared link allows for the item to be edited.

This value can only be true if can_download is also true and if the item has a type of file.

boolean
true

Defines if the shared link allows for the item to be previewed.

This value is always true. For shared links on folders this also applies to any items in the folder.

integer
3

The number of times this item has been previewed.

string (date-time)
2018-04-13T13:53:23-07:00

The date and time when this link will be unshared. This field can only be set by users with paid accounts.

string (url)
https://www.box.com/s/vspke7y05sb214wjokpk

The URL that can be used to access the item on Box.

This URL will display the item in Box's preview UI where the file can be downloaded if allowed.

This URL will continue to work even when a custom vanity_url has been set for this shared link.

string
my_url

The custom name of a shared link, as used in the vanity_url field.

string (url)
https://acme.app.box.com/v/my_url/

The "Custom URL" that can also be used to preview the item on Box. Custom URLs can only be created or modified in the Box Web application.

string array
["can_preview"]

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

integer
629644

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

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

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

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

string
Ellis Wiggins

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.

string
1

The version number of this file

object

Details about the watermark applied to this file

boolean
true

Specifies if this item has a watermark applied.

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": [
      {
        "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
  }
}