File
A standard representation of a file, as returned from any file API endpoints by default.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 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. |
etag | string | No | 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. Can be null. |
type | enum<string> | Yes | The value will always be file. Available options: file. |
sequence_id | string | No | 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. Can be null. |
name | string | No | The name of the file. |
sha1 | string | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
file_version | File version (Mini) | No | The information about the current version of the file. |
description | string | No | 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. |
size | integer | No | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
path_collection | object | No | A list of parent folders for an item. |
created_at | string | No | The date and time when the file was created on Box. |
modified_at | string | No | The date and time when the file was last updated on Box. |
trashed_at | string | No | The time at which this file was put in the trash. Can be null. |
purged_at | string | No | The time at which this file is expected to be purged from the trash. Can be null. |
content_created_at | string | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be null. |
content_modified_at | string | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be null. |
created_by | User (Mini) | No | The user who created this file. |
modified_by | User (Mini) | No | The user who last modified this file. |
owned_by | User (Mini) | No | The user who owns this file. |
shared_link | object | No | Shared 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. |
parent | Folder (Mini) | No | The 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_status | enum<string> | No | 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. Available options: active, trashed, deleted. |
Example
File (Base)
The bare basic representation of a file, the minimal amount of fields returned when using thefields query parameter.
Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 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. |
etag | string | No | 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. Can be null. |
type | enum<string> | Yes | The value will always be file. Available options: file. |
Example
File (Full)
A full representation of a file, as can be returned from any file API endpoints by default.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 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. |
etag | string | No | 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. Can be null. |
type | enum<string> | Yes | The value will always be file. Available options: file. |
sequence_id | string | No | 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. Can be null. |
name | string | No | The name of the file. |
sha1 | string | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
file_version | File version (Mini) | No | The information about the current version of the file. |
description | string | No | 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. |
size | integer | No | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
path_collection | object | No | A list of parent folders for an item. |
created_at | string | No | The date and time when the file was created on Box. |
modified_at | string | No | The date and time when the file was last updated on Box. |
trashed_at | string | No | The time at which this file was put in the trash. Can be null. |
purged_at | string | No | The time at which this file is expected to be purged from the trash. Can be null. |
content_created_at | string | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be null. |
content_modified_at | string | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be null. |
created_by | User (Mini) | No | The user who created this file. |
modified_by | User (Mini) | No | The user who last modified this file. |
owned_by | User (Mini) | No | The user who owns this file. |
shared_link | object | No | Shared 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. |
parent | Folder (Mini) | No | The 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_status | enum<string> | No | 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. Available options: active, trashed, deleted. |
version_number | string | No | The version number of this file. |
comment_count | integer | No | The number of comments on this file. |
permissions | object | No | The permissions that the authenticated user has for a file. |
tags | array of string | No | 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. |
lock | object | No | The 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. |
extension | string | No | Indicates the (optional) file extension for this file. By default, this is set to an empty string. |
is_package | boolean | No | Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files. |
expiring_embed_link | object | No | An expiring Box Embed Link. |
watermark_info | object | No | Details about the watermark applied to this item. |
is_accessible_via_shared_link | boolean | No | Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder. |
allowed_invitee_roles | array of enum<string> | No | A list of the types of roles that user can be invited at when sharing this file. |
is_externally_owned | boolean | No | Specifies if this file is owned by a user outside of the authenticated enterprise. |
has_collaborations | boolean | No | Specifies if this file has any other collaborators. |
metadata | object | No | A 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_at | string | No | When the file will automatically be deleted. Can be null. |
representations | object | No | A list of file representations. |
classification | object | No | The classification applied to an item. Can be null. |
uploader_display_name | string | No | 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_at | string | No | The retention expiration timestamp for the given file. Can be null. |
shared_link_permission_options | array of enum<string> | No | A list of the types of roles that user can be invited at when sharing this file. Can be null. |
is_associated_with_app_item | boolean | No | 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
File (Mini)
A mini representation of a file, used when nested under another resource.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
id | string | Yes | 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. |
etag | string | No | 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. Can be null. |
type | enum<string> | Yes | The value will always be file. Available options: file. |
sequence_id | string | No | 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. Can be null. |
name | string | No | The name of the file. |
sha1 | string | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
file_version | File version (Mini) | No | The information about the current version of the file. |
Example
Files
A list of files.Attributes and example
Attributes and example
| Property | Type | Required | Description |
|---|---|---|---|
total_count | integer | No | The number of files. |
entries | array of File (Full) | No | A list of files. |
Example
