Skip to main content
Files, together with Folders, are at the core of the Box API. Files can be uploaded and downloaded, as well as hold important metadata information about the content.

File

A standard representation of a file, as returned from any file API endpoints by default.
PropertyTypeRequiredDescription
idstringYesThe 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.
etagstringNoThe 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. Can be null.
typeenum<string>YesThe value will always be file. Available options: file.
sequence_idstringNoA 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. Can be null.
namestringNoThe name of the file.
sha1stringNoThe SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionFile version (Mini)NoThe information about the current version of the file.
descriptionstringNoThe 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.
sizeintegerNoThe file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
path_collectionobjectNoA list of parent folders for an item.
created_atstringNoThe date and time when the file was created on Box.
modified_atstringNoThe date and time when the file was last updated on Box.
trashed_atstringNoThe time at which this file was put in the trash. Can be null.
purged_atstringNoThe time at which this file is expected to be purged from the trash. Can be null.
content_created_atstringNoThe date and time at which this file was originally created, which might be before it was uploaded to Box. Can be null.
content_modified_atstringNoThe date and time at which this file was last updated, which might be before it was uploaded to Box. Can be null.
created_byUser (Mini)NoThe user who created this file.
modified_byUser (Mini)NoThe user who last modified this file.
owned_byUser (Mini)NoThe user who owns this file.
shared_linkobjectNoShared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be null.
parentFolder (Mini)NoThe folder that this file is located within. This value may be null for some folders such as the root folder or the trash folder. Can be null.
item_statusenum<string>NoDefines 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. Available options: active, trashed, deleted.
Example
{
  "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,
      "can_edit": false
    },
    "download_count": 3,
    "preview_count": 3
  },
  "parent": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "item_status": "active"
}

File (Base)

The bare basic representation of a file, the minimal amount of fields returned when using the fields query parameter.
PropertyTypeRequiredDescription
idstringYesThe 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.
etagstringNoThe 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. Can be null.
typeenum<string>YesThe value will always be file. Available options: file.
Example
{
  "id": "12345",
  "etag": "1",
  "type": "file"
}

File (Full)

A full representation of a file, as can be returned from any file API endpoints by default.
PropertyTypeRequiredDescription
idstringYesThe 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.
etagstringNoThe 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. Can be null.
typeenum<string>YesThe value will always be file. Available options: file.
sequence_idstringNoA 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. Can be null.
namestringNoThe name of the file.
sha1stringNoThe SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionFile version (Mini)NoThe information about the current version of the file.
descriptionstringNoThe 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.
sizeintegerNoThe file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.
path_collectionobjectNoA list of parent folders for an item.
created_atstringNoThe date and time when the file was created on Box.
modified_atstringNoThe date and time when the file was last updated on Box.
trashed_atstringNoThe time at which this file was put in the trash. Can be null.
purged_atstringNoThe time at which this file is expected to be purged from the trash. Can be null.
content_created_atstringNoThe date and time at which this file was originally created, which might be before it was uploaded to Box. Can be null.
content_modified_atstringNoThe date and time at which this file was last updated, which might be before it was uploaded to Box. Can be null.
created_byUser (Mini)NoThe user who created this file.
modified_byUser (Mini)NoThe user who last modified this file.
owned_byUser (Mini)NoThe user who owns this file.
shared_linkobjectNoShared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be null.
parentFolder (Mini)NoThe folder that this file is located within. This value may be null for some folders such as the root folder or the trash folder. Can be null.
item_statusenum<string>NoDefines 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. Available options: active, trashed, deleted.
version_numberstringNoThe version number of this file.
comment_countintegerNoThe number of comments on this file.
permissionsobjectNoThe permissions that the authenticated user has for a file.
tagsarray of stringNoThe 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.
lockobjectNoThe lock held on a file. A lock prevents a file from being moved, renamed, or otherwise changed by anyone else than the user who created the lock. Can be null.
extensionstringNoIndicates the (optional) file extension for this file. By default, this is set to an empty string.
is_packagebooleanNoIndicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.
expiring_embed_linkobjectNoAn expiring Box Embed Link.
watermark_infoobjectNoDetails about the watermark applied to this item.
is_accessible_via_shared_linkbooleanNoSpecifies if the file can be accessed via the direct shared link or a shared link to a parent folder.
allowed_invitee_rolesarray of enum<string>NoA list of the types of roles that user can be invited at when sharing this file.
is_externally_ownedbooleanNoSpecifies if this file is owned by a user outside of the authenticated enterprise.
has_collaborationsbooleanNoSpecifies if this file has any other collaborators.
metadataobjectNoA list of metadata instances, nested within key-value pairs of their scope and templateKey. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the GET /files/:id or GET /folder/:id endpoint with the fields query parameter to get the metadata by ID. To request a metadata instance for a particular scope and templateKey use the following format for the fields parameter: metadata.<scope>.<templateKey> For example, ?fields=metadata.enterprise_27335.marketingCollateral.
expires_atstringNoWhen the file will automatically be deleted. Can be null.
representationsobjectNoA list of file representations.
classificationobjectNoThe classification applied to an item. Can be null.
uploader_display_namestringNoThe 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_atstringNoThe retention expiration timestamp for the given file. Can be null.
shared_link_permission_optionsarray of enum<string>NoA list of the types of roles that user can be invited at when sharing this file. Can be null.
is_associated_with_app_itembooleanNoThis 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
{
  "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,
      "can_edit": false
    },
    "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_watermark_inherited": false,
    "is_watermarked_by_access_policy": false
  },
  "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
}

File (Mini)

A mini representation of a file, used when nested under another resource.
PropertyTypeRequiredDescription
idstringYesThe 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.
etagstringNoThe 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. Can be null.
typeenum<string>YesThe value will always be file. Available options: file.
sequence_idstringNoA 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. Can be null.
namestringNoThe name of the file.
sha1stringNoThe SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.
file_versionFile version (Mini)NoThe information about the current version of the file.
Example
{
  "id": "12345",
  "etag": "1",
  "type": "file",
  "sequence_id": "3",
  "name": "Contract.pdf",
  "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
  "file_version": {
    "id": "12345",
    "type": "file_version",
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  }
}

Files

A list of files.
PropertyTypeRequiredDescription
total_countintegerNoThe number of files.
entriesarray of File (Full)NoA list of files.
Example
{
  "total_count": 1,
  "entries": [
    {
      "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,
          "can_edit": false
        },
        "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_watermark_inherited": false,
        "is_watermarked_by_access_policy": false
      },
      "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
    }
  ]
}
Last modified on July 9, 2026