Box · Schema
File (Full)
A full representation of a file, as can be returned from any file API endpoints by default
Cloud StorageCollaborationContent ManagementDocumentsEnterpriseFile Sharing
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/File--Full",
"title": "File (Full)",
"type": "object",
"x-box-resource-id": "file--full",
"x-box-variant": "full",
"description": "A full representation of a file, as can be returned from any\nfile API endpoints by default",
"allOf": [
{
"$ref": "#/components/schemas/File"
},
{
"properties": {
"version_number": {
"type": "string",
"example": "1",
"description": "The version number of this file"
},
"comment_count": {
"type": "integer",
"example": 10,
"description": "The number of comments on this file"
},
"permissions": {
"allOf": [
{
"type": "object",
"description": "The permissions that the authenticated user has for a file.",
"required": [
"can_annotate",
"can_comment",
"can_preview",
"can_upload",
"can_view_annotations_all",
"can_view_annotations_self"
],
"allOf": [
{
"type": "object",
"description": "The permissions that the authenticated user has for an item.",
"required": [
"can_delete",
"can_download",
"can_invite_collaborator",
"can_rename",
"can_set_share_access",
"can_share"
],
"properties": {
"can_delete": {
"type": "boolean",
"description": "Specifies if the current user can delete this item.",
"example": true,
"nullable": false
},
"can_download": {
"type": "boolean",
"description": "Specifies if the current user can download this item.",
"example": true,
"nullable": false
},
"can_invite_collaborator": {
"type": "boolean",
"description": "Specifies if the current user can invite new\nusers to collaborate on this item, and if the user can\nupdate the role of a user already collaborated on this\nitem.",
"example": true,
"nullable": false
},
"can_rename": {
"type": "boolean",
"description": "Specifies if the user can rename this item.",
"example": true,
"nullable": false
},
"can_set_share_access": {
"type": "boolean",
"description": "Specifies if the user can change the access level of an\nexisting shared link on this item.",
"example": true,
"nullable": false
},
"can_share": {
"type": "boolean",
"description": "Specifies if the user can create a shared link for this item.",
"example": true,
"nullable": false
}
}
},
{
"properties": {
"can_annotate": {
"type": "boolean",
"description": "Specifies if the user can place annotations on this file.",
"example": true,
"nullable": false
},
"can_comment": {
"type": "boolean",
"description": "Specifies if the user can place comments on this file.",
"example": true,
"nullable": false
},
"can_preview": {
"type": "boolean",
"description": "Specifies if the user can preview this file.",
"example": true,
"nullable": false
},
"can_upload": {
"type": "boolean",
"description": "Specifies if the user can upload a new version of this file.",
"example": true,
"nullable": false
},
"can_view_annotations_all": {
"type": "boolean",
"description": "Specifies if the user view all annotations placed on this file",
"example": true,
"nullable": false
},
"can_view_annotations_self": {
"type": "boolean",
"description": "Specifies if the user view annotations placed by themselves\non this file",
"example": true,
"nullable": false
}
}
}
]
},
{
"description": "Describes the permissions that the current user has\nfor this file."
},
{
"nullable": false
}
]
},
"tags": {
"allOf": [
{
"type": "array",
"example": [
"approved"
],
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 100,
"description": "The tags for this item. These tags are shown in\nthe Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags,\nmodify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000\nunique tags per enterprise."
},
{
"nullable": false
}
]
},
"lock": {
"allOf": [
{
"title": "Lock",
"type": "object",
"description": "The lock held on a file. A lock prevents a file from being moved,\nrenamed, or otherwise changed by anyone else than the user who created the\nlock.",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for this lock",
"example": "11446498"
},
"type": {
"type": "string",
"description": "`lock`",
"example": "lock",
"enum": [
"lock"
]
},
"created_by": {
"allOf": [
{
"$ref": "#/components/schemas/User--Mini"
},
{
"description": "The user who created the lock."
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2012-12-12T10:53:43-08:00",
"description": "The time this lock was created at."
},
"expired_at": {
"type": "string",
"format": "date-time",
"example": "2012-12-12T10:53:43-08:00",
"description": "The time this lock is to expire at, which might be in the past."
},
"is_download_prevented": {
"type": "boolean",
"example": true,
"description": "Whether or not the file can be downloaded while locked."
},
"app_type": {
"type": "string",
"description": "If the lock is managed by an application rather than a user, this\nfield identifies the type of the application that holds the lock.\nThis is an open enum and may be extended with additional values in\nthe future.",
"enum": [
"gsuite",
"office_wopi",
"office_wopiplus",
"other"
],
"example": "office_wopiplus",
"nullable": true
}
}
},
{
"description": "The lock held on this file. If there is no lock, this can either\nbe `null` or have a timestamp in the past."
}
],
"nullable": true
},
"extension": {
"type": "string",
"example": "pdf",
"description": "Indicates the (optional) file extension for this file. By default,\nthis is set to an empty string."
},
"is_package": {
"type": "boolean",
"example": true,
"description": "Indicates if the file is a package. Packages are commonly used\nby Mac Applications and can include iWork files."
},
"expiring_embed_link": {
"allOf": [
{
"title": "Expiring embed link",
"type": "object",
"description": "An expiring Box Embed Link.",
"allOf": [
{
"type": "object",
"description": "The basics of an access token",
"properties": {
"access_token": {
"type": "string",
"format": "token",
"example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
"description": "The requested access token."
},
"expires_in": {
"type": "integer",
"format": "int64",
"example": 3600,
"description": "The time in seconds by which this token will expire."
},
"token_type": {
"type": "string",
"enum": [
"bearer"
],
"example": "bearer",
"description": "The type of access token returned."
},
"restricted_to": {
"type": "array",
"description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.",
"items": {
"$ref": "#/components/schemas/FileOrFolderScope"
}
}
}
},
{
"properties": {
"url": {
"type": "string",
"format": "url",
"example": "https://cloud.app.box.com/preview/expiring_embed/...",
"description": "The actual expiring embed URL for this file, constructed\nfrom the file ID and access tokens specified in this object."
}
}
}
]
},
{
"description": "Requesting this field creates an expiring Box Embed URL for an\nembedded preview session in an `iframe`.\n\nThis URL will expire after 60 seconds and the session will\nexpire after 60 minutes.\n\nNot all file types are supported for these embed URLs. Box Embed\nis not optimized for mobile browsers and should not be used in web\nexperiences designed for mobile devices. Many UI elements, like\nthe **download** and **print** options might not show in mobile\nbrowsers."
}
]
},
"watermark_info": {
"allOf": [
{
"type": "object",
"description": "Details about the watermark applied to this item",
"properties": {
"is_watermarked": {
"type": "boolean",
"description": "Specifies if this item has a watermark applied.",
"example": true,
"nullable": false
}
}
},
{
"description": "Details about the watermark applied to this file"
}
]
},
"is_accessible_via_shared_link": {
"type": "boolean",
"description": "Specifies if the file can be accessed\nvia the direct shared link or a shared link\nto a parent folder.",
"example": true,
"enum": [
true,
false
]
},
"allowed_invitee_roles": {
"type": "array",
"example": [
"editor"
],
"nullable": false,
"description": "A list of the types of roles that user can be invited at\nwhen sharing this file.",
"items": {
"type": "string",
"enum": [
"editor",
"viewer",
"previewer",
"uploader",
"previewer uploader",
"viewer uploader",
"co-owner"
]
}
},
"is_externally_owned": {
"type": "boolean",
"example": true,
"nullable": false,
"description": "Specifies if this file is owned by a user outside of the\nauthenticated enterprise."
},
"has_collaborations": {
"type": "boolean",
"example": true,
"nullable": false,
"description": "Specifies if this file has any other collaborators."
},
"metadata": {
"allOf": [
{
"title": "Item metadata instances",
"type": "object",
"description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.\n\nTo access the metadata for a file or folder, first use the\nmetadata endpoints to determine the metadata templates available to your\nenterprise.\n\nThen use the `GET /files/:id` or `GET /folder/:id`\nendpoint with the `fields` query parameter to get\nthe metadata by ID.\n\nTo request a metadata instance for a particular `scope` and `templateKey`\nuse the following format for the `fields` parameter:\n`metadata.<scope>.<templateKey>`\n\nFor example, `?fields=metadata.enterprise_27335.marketingCollateral`.",
"example": {
"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
}
}
},
"additionalProperties": {
"type": "object",
"description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.",
"example": {
"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
}
},
"additionalProperties": {
"$ref": "#/components/schemas/Metadata"
}
}
},
{
"description": "An object containing the metadata instances that have been\nattached to this file.\n\nEach metadata instance is uniquely identified by its `scope` and\n`templateKey`. There can only be one instance of any metadata\ntemplate attached to each file. Each metadata instance is nested\nwithin an object with the `templateKey` as the key, which again\nitself is nested in an object with the `scope` as the key."
}
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the file will automatically be deleted",
"example": "2012-12-12T10:53:43-08:00"
},
"representations": {
"allOf": [
{
"title": "Representations",
"description": "A list of file representations",
"type": "object",
"properties": {
"entries": {
"type": "array",
"description": "A list of files",
"items": {
"type": "object",
"description": "A file representation",
"properties": {
"content": {
"type": "object",
"description": "An object containing the URL that can be used to actually fetch\nthe representation.",
"properties": {
"url_template": {
"type": "string",
"example": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567",
"description": "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation."
}
}
},
"info": {
"type": "object",
"description": "An object containing the URL that can be used to fetch more info\non this representation.",
"properties": {
"url": {
"type": "string",
"example": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048",
"description": "The API URL that can be used to get more info on this file\nrepresentation. Make sure to make an authenticated API call\nto this endpoint."
}
}
},
"properties": {
"type": "object",
"description": "An object containing the size and type of this presentation.",
"properties": {
"dimensions": {
"type": "string",
"format": "<width>x<height>",
"example": "2048x2048",
"description": "The width by height size of this representation in pixels."
},
"paged": {
"type": "boolean",
"example": true,
"description": "Indicates if the representation is build up out of multiple\npages."
},
"thumb": {
"type": "boolean",
"example": true,
"description": "Indicates if the representation can be used as a thumbnail of\nthe file."
}
}
},
"representation": {
"type": "string",
"example": "png",
"description": "Indicates the file type of the returned representation."
},
"status": {
"type": "object",
"description": "An object containing the status of this representation.",
"properties": {
"state": {
"type": "string",
"example": "success",
"enum": [
"success",
"viewable",
"pending",
"none"
],
"description": "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation."
}
}
}
}
}
}
}
},
{
"description": "A list of representations for a file that can be used to\ndisplay a placeholder of the file in your application. By default\nthis returns all representations and we recommend using the\n`x-rep-hints` header to further customize the desired\nrepresentations."
}
]
},
"classification": {
"allOf": [
{
"type": "object",
"description": "The classification applied to an item",
"properties": {
"name": {
"type": "string",
"example": "Top Secret",
"description": "The name of the classification"
},
"definition": {
"type": "string",
"example": "Content that should not be shared outside the company.",
"description": "An explanation of the meaning of this classification."
},
"color": {
"type": "string",
"example": "#FF0000",
"description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app."
}
}
},
{
"description": "Details about the classification applied to this file."
},
{
"nullable": true
}
]
},
"uploader_display_name": {
"allOf": [
{
"title": "Uploader display name",
"type": "string",
"example": "Ellis Wiggins",
"nullable": false,
"description": "The display name of the user that uploaded the file. In most cases this is the\nname of the user logged in at the time of the upload.\n\nIf the file was uploaded using a File Request form that requires the user to\nprovide an email address, this field is populated with that email address. If\nan email address was not required in the File Request form, this field is set\nto return a value of `File Request`.\n\nIn all other anonymous cases where no email was provided this field\nwill default to a value of `Someone`."
}
]
},
"disposition_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "The retention expiration timestamp for the given file",
"example": "2012-12-12T10:53:43-08:00"
},
"shared_link_permission_options": {
"type": "array",
"example": [
"can_preview"
],
"nullable": true,
"description": "A list of the types of roles that user can be invited at\nwhen sharing this file.",
"items": {
"type": "string",
"enum": [
"can_preview",
"can_download",
"can_edit"
]
}
}
}
}
]
}