Sign in

v1

latestOpenAPI 3.0.2Apache-2.02026-07-142963051.0 MB
Files

Get file information

Retrieves the details about a file.

get/files/{file_id}

Path parameters

file_idstring required

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

fieldsstring[]

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

Headers

if-none-matchstring

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.

boxapistring

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.

x-rep-hintsstring nullable

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

Returns a file object.

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

idstring required

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.

etagstring nullable

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.

type'file' required

The value will always be file.

sequence_idstring

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

namestring

The name of the file.

sha1string digest

The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.

descriptionstring

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.

sizeinteger

The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.

created_atstring date-time

The date and time when the file was created on Box.

modified_atstring date-time

The date and time when the file was last updated on Box.

trashed_atstring date-time nullable

The time at which this file was put in the trash.

purged_atstring date-time nullable

The time at which this file is expected to be purged from the trash.

content_created_atstring date-time nullable

The date and time at which this file was originally created, which might be before it was uploaded to Box.

content_modified_atstring date-time nullable

The date and time at which this file was last updated, which might be before it was uploaded to Box.

item_status'active' | 'trashed' | 'deleted'

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

The version number of this file.

comment_countinteger

The number of comments on this file.

tagsstring[]

The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.

To add or remove a tag, retrieve the item's current tags, modify them, and then update this field.

There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

extensionstring

Indicates the (optional) file extension for this file. By default, this is set to an empty string.

is_packageboolean

Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.

is_accessible_via_shared_linkboolean

Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.

allowed_invitee_rolesstring[]

A list of the types of roles that user can be invited at when sharing this file.

is_externally_ownedboolean

Specifies if this file is owned by a user outside of the authenticated enterprise.

has_collaborationsboolean

Specifies if this file has any other collaborators.

metadataobject

An object containing the metadata instances that have been attached to this file.

Each metadata instance is uniquely identified by its scope and templateKey. There can only be one instance of any metadata template attached to each file. Each metadata instance is nested within an object with the templateKey as the key, which again itself is nested in an object with the scope as the key.

expires_atstring date-time nullable

When the file will automatically be deleted.

uploader_display_namestring

The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload.

If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of File Request.

In all other anonymous cases where no email was provided this field will default to a value of Someone.

disposition_atstring date-time nullable

The retention expiration timestamp for the given file.

shared_link_permission_optionsstring[] nullable

A list of the types of roles that user can be invited at when sharing this file.

is_associated_with_app_itemboolean

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.

Example response

{
  "id": "12345",
  "etag": "1",
  "type": "file",
  "sequence_id": "3",
  "name": "Contract.pdf",
  "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
  "file_version": {
    "id": "12345",
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  },
  "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/",
    "vanity_name": "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,
    "can_apply_watermark": 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,
    "app_type": "office_wopiplus"
  },
  "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": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      }
    ],
    "url": "https://cloud.app.box.com/preview/expiring_embed/..."
  },
  "watermark_info": {
    "is_watermarked": true
  },
  "is_accessible_via_shared_link": true,
  "allowed_invitee_roles": [
    "editor"
  ],
  "is_externally_owned": true,
  "has_collaborations": 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
      }
    }
  },
  "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"
        }
      }
    ]
  },
  "classification": {
    "name": "Top Secret",
    "definition": "Content that should not be shared outside the company.",
    "color": "#FF0000"
  },
  "uploader_display_name": "Ellis Wiggins",
  "disposition_at": "2012-12-12T10:53:43-08:00",
  "shared_link_permission_options": [
    "can_preview"
  ],
  "is_associated_with_app_item": true
}