Manage Applications

    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 headeroptional
    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 headerrequired
    X-Rep-Hints: [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.
    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' }
    
    		*/
    	});

    Response Example

    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "description": "Contract for Q1 renewal",
      "size": 629644,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "id": 12345,
            "etag": 1,
            "type": "folder",
            "sequence_id": 3,
            "name": "Contracts"
          }
        ]
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "trashed_at": "2012-12-12T10:53:43-08:00",
      "purged_at": "2012-12-12T10:53:43-08:00",
      "content_created_at": "2012-12-12T10:53:43-08:00",
      "content_modified_at": "2012-12-12T10:53:43-08:00",
      "created_by": {
        "id": 11446498,
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "modified_by": {
        "id": 11446498,
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "owned_by": {
        "id": 11446498,
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": "https://acme.app.box.com/v/my_url/",
        "access": "open",
        "effective_access": "company",
        "effective_permission": "can_download",
        "unshared_at": "2018-04-13T13:53:23-07:00",
        "is_password_enabled": true,
        "permissions": {
          "can_download": true,
          "can_preview": true
        },
        "download_count": 3,
        "preview_count": 3
      },
      "parent": {
        "id": 12345,
        "etag": 1,
        "type": "folder",
        "sequence_id": 3,
        "name": "Contracts"
      },
      "item_status": "active",
      "version_number": 1,
      "comment_count": 10,
      "permissions": {
        "can_delete": true,
        "can_download": true,
        "can_invite_collaborator": true,
        "can_rename": true,
        "can_set_share_access": true,
        "can_share": true,
        "can_annotate": true,
        "can_comment": true,
        "can_preview": true,
        "can_upload": true,
        "can_view_annotations_all": true,
        "can_view_annotations_self": true
      },
      "tags": [
        "approved"
      ],
      "lock": {
        "id": 11446498,
        "type": "lock",
        "created_by": {
          "id": 11446498,
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "expired_at": "2012-12-12T10:53:43-08:00",
        "is_download_prevented": true
      },
      "extension": "pdf",
      "is_package": true,
      "expiring_embed_link": {
        "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "restricted_to": [
          {
            "scope": "item_download",
            "object": {
              "id": 12345,
              "etag": 1,
              "type": "file",
              "sequence_id": 3,
              "name": "Contract.pdf"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true
      },
      "allowed_invitee_roles": [
        "open"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "global": {
          "marketingCollateral": {
            "$canEdit": true,
            "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
            "$parent": "folder_59449484661",
            "$scope": "enterprise_27335",
            "$template": "blueprintTemplate",
            "$type": "blueprintTemplate-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
            "$typeVersion": 2,
            "$version": 1
          }
        }
      },
      "expires_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"
            }
          }
        ]
      }
    }