Files resources

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.

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

{
  "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,
    "one_time_passcode": {
      "mode": "allowlist",
      "allowlist": [
        {
          "type": "email",
          "value": "alice@example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        },
        {
          "type": "domain",
          "value": "example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        }
      ]
    }
  },
  "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.

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

{
  "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.

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.
`collections`	array of Collection	No	The collections that this file belongs to. For more information, see the collections guide.
`is_download_available`	`boolean`	No	Whether the file’s binary content is eligible to be downloaded. This is a content-level flag and does not reflect whether the current user is authorized to download the file. Use `permissions.can_download`, when available, for that.
`download_url`	`string`	No	A pre-authorized, expiring URL for directly downloading the file’s content. Requires authentication and is valid only for the current session. This field is only returned for files, not folders or web links.
`authenticated_download_url`	`string`	No	A stable API URL for the file content endpoint, `/2.0/files/{id}/content`. Unlike `download_url`, authorization is evaluated when the URL is requested with a valid access token. This field is only returned for files, not folders or web links.
`allowed_shared_link_access_levels`	array of `enum<string>`	No	The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this file. The list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user.

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,
    "one_time_passcode": {
      "mode": "allowlist",
      "allowlist": [
        {
          "type": "email",
          "value": "alice@example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        },
        {
          "type": "domain",
          "value": "example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        }
      ]
    }
  },
  "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,
  "collections": [
    {
      "id": "11446498",
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites"
    }
  ],
  "is_download_available": true,
  "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
  "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
  "allowed_shared_link_access_levels": [
    "open"
  ]
}

File (Mini)

A mini representation of a file, used when nested under another resource.

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

{
  "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.

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

{
  "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,
        "one_time_passcode": {
          "mode": "allowlist",
          "allowlist": [
            {
              "type": "email",
              "value": "alice@example.com",
              "created_at": "2026-05-19T12:00:00Z",
              "created_by": {
                "id": "11446498",
                "type": "user"
              }
            },
            {
              "type": "domain",
              "value": "example.com",
              "created_at": "2026-05-19T12:00:00Z",
              "created_by": {
                "id": "11446498",
                "type": "user"
              }
            }
          ]
        }
      },
      "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,
      "collections": [
        {
          "id": "11446498",
          "type": "collection",
          "name": "Favorites",
          "collection_type": "favorites"
        }
      ],
      "is_download_available": true,
      "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
      "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
      "allowed_shared_link_access_levels": [
        "open"
      ]
    }
  ]
}

API reference

v2025.0

v2026.0

File

File (Base)

File (Full)

File (Mini)

Files

​File

​File (Base)

​File (Full)

​File (Mini)

​Files

File

File (Base)

File (Full)

File (Mini)

Files