File (Full) - Box Dev Docs

API version 2024.0 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

example: 12345The 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.

type

string

example: fileThe value will always be file.Value is always file

allowed_invitee_roles

stringarray

example: ["editor"]A list of the types of roles that user can be invited at when sharing this file.

classification

object

Details about the classification applied to this file.

Show child attributes

color

string

example: #FF0000The 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.

definition

string

example: Content that should not be shared outside the company.An explanation of the meaning of this classification.

name

string

example: Top SecretThe name of the classification.

comment_count

integer

example: 10The number of comments on this file.

content_created_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The date and time at which this file was originally created, which might be before it was uploaded to Box.

content_modified_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The date and time at which this file was last updated, which might be before it was uploaded to Box.

created_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The date and time when the file was created on Box.

created_by

User (Mini)object

The user who created this file.

description

string

example: Contract for Q1 renewalThe 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.

disposition_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The retention expiration timestamp for the given file.

etag

string

example: 1The 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.

expires_at

string(date-time)

example: 2012-12-12T10:53:43-08:00When the file will automatically be deleted.

expiring_embed_link

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.

Show child attributes

access_token

string(token)

example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQThe requested access token.

expires_in

integer(int64)

example: 3600The time in seconds by which this token will expire.

restricted_to

object[]

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

Show child attributes

object

File (Mini)/Folder (Mini)object

The file or folder resource.

scope

string

example: item_downloadThe 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,item_read

token_type

string

example: bearerThe type of access token returned.Value is always bearer

url

string(url)

example: 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.

extension

string

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

file_version

File version (Mini)object

The information about the current version of the file.

has_collaborations

boolean

example: trueSpecifies if this file has any other collaborators.

is_accessible_via_shared_link

boolean

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

is_associated_with_app_item

boolean

example: trueThis 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_externally_owned

boolean

example: trueSpecifies if this file is owned by a user outside of the authenticated enterprise.

is_package

boolean

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

item_status

string

example: activeDefines 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

lock

object

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

Show child attributes

string

example: 11446498The unique identifier for this lock.

type

string

example: lockThe value will always be lock.Value is always lock

app_type

string

example: office_wopiplusIf 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

created_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The time this lock was created at.

created_by

User (Mini)object

The user who created the lock.

expired_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The time this lock is to expire at, which might be in the past.

is_download_prevented

boolean

example: trueWhether or not the file can be downloaded while locked.

metadata

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.

Show child attributes

<key>

associative array

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

Show child attributes

<key>

Metadata instance (Full)

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

modified_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The date and time when the file was last updated on Box.

modified_by

User (Mini)object

The user who last modified this file.

name

string

example: Contract.pdfThe name of the file.

owned_by

User (Mini)object

The user who owns this file.

parent

Folder (Mini)object

The folder that this file is located within. This value may be null for some folders such as the root folder or the trash folder.

path_collection

object

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

Show child attributes

entries

Folder (Mini)array

The parent folders for this item.

total_count

integer(int64)

example: 1The number of folders in this list.

permissions

object

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

Show child attributes

can_annotate

boolean

example: trueSpecifies if the user can place annotations on this file.

can_comment

boolean

example: trueSpecifies if the user can place comments on this file.

can_delete

boolean

example: trueSpecifies if the current user can delete this item.

can_download

boolean

example: trueSpecifies if the current user can download this item.

can_invite_collaborator

boolean

example: trueSpecifies 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.

can_preview

boolean

example: trueSpecifies if the user can preview this file.

can_rename

boolean

example: trueSpecifies if the user can rename this item.

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

example: trueSpecifies if the user can create a shared link for this item.

can_upload

boolean

example: trueSpecifies if the user can upload a new version of this file.

can_view_annotations_all

boolean

example: trueSpecifies if the user view all annotations placed on this file.

can_view_annotations_self

boolean

example: trueSpecifies if the user view annotations placed by themselves on this file.

purged_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The time at which this file is expected to be purged from the trash.

representations

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.

Show child attributes

entries

object[]

A list of files.

Show child attributes

content

object

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

Show child attributes

url_template

string

example:

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.

info

object

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

Show child attributes

url

string

example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048The 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.

properties

object

An object containing the size and type of this presentation.

Show child attributes

dimensions

string(<width>x<height>)

example: 2048x2048The width by height size of this representation in pixels.

paged

string

example: trueIndicates if the representation is build up out of multiple pages.

thumb

string

example: trueIndicates if the representation can be used as a thumbnail of the file.

representation

string

example: pngIndicates the file type of the returned representation.

status

object

An object containing the status of this representation.

Show child attributes

state

string

example: successThe 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

sequence_id

string

example: 3A 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.

sha1

string(digest)

example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.

shared_link

object

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

Show child attributes

access

string

example: openThe 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

download_count

integer

example: 3The number of times this item has been downloaded.

download_url

string(url)

example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpegA 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.

effective_access

string

example: companyThe 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

effective_permission

string

example: can_downloadThe 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

is_password_enabled

boolean

example: trueDefines if the shared link requires a password to access the item.

permissions

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.

Show child attributes

can_download

boolean

example: trueDefines 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.

can_edit

boolean

example: falseDefines 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.

can_preview

boolean

example: trueDefines 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.

preview_count

integer

example: 3The number of times this item has been previewed.

unshared_at

string(date-time)

example: 2018-04-13T13:53:23-07:00The date and time when this link will be unshared. This field can only be set by users with paid accounts.

url

string(url)

example: https://www.box.com/s/vspke7y05sb214wjokpkThe 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.

vanity_name

string

example: my_urlThe custom name of a shared link, as used in the vanity_url field.

vanity_url

string(url)

example: 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.

shared_link_permission_options

stringarray

example: ["can_preview"]A list of the types of roles that user can be invited at when sharing this file.

size

integer

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

tags

stringarray

example: ["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.

trashed_at

string(date-time)

example: 2012-12-12T10:53:43-08:00The time at which this file was put in the trash.

uploader_display_name

string

example: Ellis WigginsThe 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.

version_number

string

example: 1The version number of this file.

watermark_info

object

Details about the watermark applied to this file.

Show child attributes

is_watermarked

boolean

example: trueSpecifies if this item has a watermark applied.

{
  "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": "[email protected]",
    "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": "[email protected]",
      "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": "[email protected]",
    "name": "Aaron Levie"
  },
  "name": "Contract.pdf",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "login": "[email protected]",
    "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
  }
}