Get file information

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

Retrieves the details about a file.

Request

bearer [ACCESS_TOKEN]
application/json

Path Parameters

stringin pathrequired
12345

The 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

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.

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 ?field=metadata.enterprise_12345.contractTemplate.

Request Headers

stringin header
optional
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.

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
optional
[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]

Response

application/jsonFile (Full)

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 -i -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(f'File "{file_info.name}" has a size of {file_info.size} bytes')
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)")
}
TypeScript (Beta)
await client.files.getFileById(file.id);
Python (Beta)
client.files.get_file_by_id(file.id)
.NET (Beta)
await client.Files.GetFileByIdAsync(fileId: file.Id).ConfigureAwait(false)

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_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
  }
}