Sample - Box Platform API
GET/files/{file_id}

Get file information

Retrieves the details of a specific file. Use fields to request additional attributes or metadata, and use conditional or shared-link headers when retrieving a file through a cached or shared-link context.

5 parameters
file_idstringrequired
The unique identifier of the file to retrieve.
fieldsarray<string>optional
A comma-separated list of attributes or metadata fields to include in the response.
if-none-matchstringoptional
The file's previously observed ETag; the response is withheld when the file has not changed since that ETag.
boxapistringoptional
The shared-link URL and optional password used to access the file or a nested item through a shared link.
x-rep-hintsstringoptional
Representation hints used with `fields` to request specific file representations, such as image dimensions or extracted text.

7 status codes
200Returns a file object containing the requested standard fields and any additional attributes specified through `fields`.
idstringrequired
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`.
etagstringoptional
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.
typestringrequired
The value will always be `file`.
Allowed:file
sequence_idobjectoptional
namestringoptional
The name of the file.
sha1stringoptional
The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionobjectoptional
descriptionstringoptional
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.
sizeintegeroptional
The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
path_collectionobjectoptional
created_atstringoptional
The date and time when the file was created on Box.
modified_atstringoptional
The date and time when the file was last updated on Box.
trashed_atstringoptional
The time at which this file was put in the trash.
purged_atstringoptional
The time at which this file is expected to be purged from the trash.
content_created_atstringoptional
The date and time at which this file was originally created, which might be before it was uploaded to Box.
content_modified_atstringoptional
The date and time at which this file was last updated, which might be before it was uploaded to Box.
created_byobjectoptional
modified_byobjectoptional
owned_byobjectoptional
shared_linkobjectoptional
parentobjectoptional
item_statusstringoptional
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.
Allowed:activetrasheddeleted
version_numberstringoptional
The version number of this file.
comment_countintegeroptional
The number of comments on this file.
permissionsobjectoptional
tagsobjectoptional
lockobjectoptional
extensionstringoptional
Indicates the (optional) file extension for this file. By default, this is set to an empty string.
is_packagebooleanoptional
Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.
expiring_embed_linkobjectoptional
watermark_infoobjectoptional
is_accessible_via_shared_linkbooleanoptional
Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.
allowed_invitee_rolesarray<string>optional
A list of the types of roles that user can be invited at when sharing this file.
is_externally_ownedbooleanoptional
Specifies if this file is owned by a user outside of the authenticated enterprise.
has_collaborationsbooleanoptional
Specifies if this file has any other collaborators.
metadataobjectoptional
expires_atstringoptional
When the file will automatically be deleted.
representationsobjectoptional
classificationobjectoptional
uploader_display_nameobjectoptional
disposition_atstringoptional
The retention expiration timestamp for the given file.
shared_link_permission_optionsarray<string>optional
A list of the types of roles that user can be invited at when sharing this file.
is_associated_with_app_itembooleanoptional
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.
collectionsarray<Collection>optional
The collections that this file belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).
is_download_availablebooleanoptional
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_urlstringoptional
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_urlstringoptional
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_levelsarray<SharedLinkAccessLevel>optional
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.
304Returns an empty response when `if-none-match` matches the file's current ETag, indicating that the file has not changed.
401Returned when the access token in the `Authorization` header is missing or not recognized.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the file is not found or the authenticated user does not have access to it.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
405Returned when `file_id` is not in a recognized format.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
415Returned when an operation requests an unsupported media type, such as an expiring embed link for an unsupported file.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultReturned when an unexpected client error occurs.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 401 is returned when the access token is missing or unrecognized, and a 404 is returned when the file_id does not identify an accessible file. A 405 is returned when file_id has an unrecognized format, while a 415 is returned when an unsupported media type is requested for an expiring embed link.