Get file information

get
https://api.box.com/2.0
/files/:file_id

Retrieves the details about a file.

Request

application/json

Path Parameters

stringin pathrequired
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.

Query Parameters

string arrayin queryoptional
id,type,name

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.

Request Headers

stringin header
optional
1

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

stringin header
required
[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 94x94 pixel dimensions provide the following hints.

X-Rep-Hints: [jpg?dimensions=32x32][jpg?dimensions=94x94]

Additionally, a text representation is available for all document file types in Box using the [extracted_text] representation.

X-Rep-Hints: [extracted_text]

Response

application/jsonFile

Returns a file object.

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

none

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.

application/jsonClient error

Returned when the access token provided in the Authorization header is not recognized or not provided.

application/jsonClient error

Returned if the file is not found, or the user does not have access to the file.

application/jsonClient error

Returned if the file_id is not in a recognized format.

application/jsonClient error

Returns an error if an action is performed on a file with an incorrect media type.

  • unsupported_media_type when requesting an expiring_embed_link for a file that is not supported by Box Embed.
application/jsonClient error

An unexpected client error.

get
Get file information
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -X GET https://api.box.com/2.0/files/12345 \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
.NET
BoxFile file = await client.FilesManager.GetInformationAsync(id: "11111");
Java
BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.getInfo();
Python
file_id = '11111'
file_info = client.file(file_id).get()
print('File "{0}" has a size of {1} bytes'.format(file_info.name, file_info.size))
Node
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' }

		*/
	});
iOS
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)")
}