Get file information
Retrieves the details about a file.
Request
Request Headers
shared_link=[link]&shared_link_password=[password]The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been explicitly shared with a user.
Use the format shared_link=[link] or if a password is required then
use shared_link=[link]&shared_link_password=[password].
This header can be used on the file or folder shared, as well as on any files or folders nested within the item.
1Ensures an item is only returned if it has changed.
Pass in the item's last observed etag value
into this header and the endpoint will fail
with a 304 Not Modified if the item has not
changed since.
[pdf]A header required to request specific representations
of a file. Use this in combination with the fields query
parameter to request a specific file representation.
The general format for these representations is
X-Rep-Hints: [...] where [...] is one or many
hints in the format [fileType?query].
For example, to request a png representation in 32x32
as well as 64x64 pixel dimensions provide the following
hints.
x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]
Additionally, a text representation is available for all
document file types in Box using the [extracted_text]
representation.
x-rep-hints: [extracted_text]
Path Parameters
12345The 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
id,type,nameA 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.
Additionally this field can be used to query any metadata
applied to the file by specifying the metadata field as well
as the scope and key of the template to retrieve, for example
?fields=metadata.enterprise_12345.contractTemplate.
Response
Returns a file object.
Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.
Returns an empty response when the If-None-Match header matches
the current etag value of the folder. This indicates that the folder
has not changed since it was last requested.
Returned when the access token provided in the Authorization header
is not recognized or not provided.
Returned if the file is not found, or the user does not have access to the file.
Returned if the file_id is not in a recognized format.
Returns an error if an action is performed on a file with an incorrect media type.
unsupported_media_typewhen requesting anexpiring_embed_linkfor a file that is not supported by Box Embed.
An unexpected client error.
Request Example
curl -i -X GET "https://api.box.com/2.0/files/12345" \
-H "authorization: Bearer <ACCESS_TOKEN>"await client.files.getFileById(fileId, {
queryParams: {
fields: ['is_associated_with_app_item' as string],
} satisfies GetFileByIdQueryParams,
} satisfies GetFileByIdOptionalsInput);client.files.get_file_by_id(file_id, fields=["is_associated_with_app_item"])await client.Files.GetFileByIdAsync(fileId: fileId, queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"is_associated_with_app_item"}) });BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.getInfo();file_id = '11111'
file_info = client.file(file_id).get()
print(f'File "{file_info.name}" has a size of {file_info.size} bytes')BoxFile file = await client.FilesManager.GetInformationAsync(id: "11111");client.files.get('11111')
.then(file => {
/* file -> {
type: 'file',
id: '11111',
file_version:
{ type: 'file_version',
id: '22222',
sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93' },
sequence_id: '1',
etag: '1',
sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93',
name: 'Puppy.png',
description: '',
size: 106833,
path_collection:
{ total_count: 2,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
{ type: 'folder',
id: '33333',
sequence_id: '0',
etag: '0',
name: 'Collaborated Folder' } ] },
created_at: '2016-11-16T22:01:44-08:00',
modified_at: '2016-11-16T22:01:51-08:00',
trashed_at: null,
purged_at: null,
content_created_at: '2016-10-29T18:33:50-07:00',
content_modified_at: '2016-10-29T18:33:50-07:00',
created_by:
{ type: 'user',
id: '44444',
name: 'Owner',
login: 'owner@example.com' },
modified_by:
{ type: 'user',
id: '44444',
name: 'Owner',
login: 'owner@example.com' },
owned_by:
{ type: 'user',
id: '44444',
name: 'Owner',
login: 'owner@example.com' },
shared_link: null,
parent:
{ type: 'folder',
id: '33333',
sequence_id: '0',
etag: '0',
name: 'Collaborated Folder' },
item_status: 'active' }
*/
});client.files.get(fileId: "11111", fields: ["name", "created_at"]) { (result: Result<File, BoxSDKError>) in
guard case let .success(file) = result else {
print("Error retrieving file information")
return
}
print("File \(file.name) was created at \(file.createdAt)")
}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
}
}