> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload file version
> Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs.
The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code.
This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.
Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
## OpenAPI
````yaml box-openapi.json post /files/{file_id}/content
openapi: 3.0.2
info:
title: Box Platform API
description: >-
[Box Platform](https://developer.box.com) provides functionality to provide
access to content stored within [Box](https://box.com). It provides
endpoints for basic manipulation of files and folders, management of users
within an enterprise, as well as more complex topics such as legal holds and
retention policies.
termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
contact:
name: Box, Inc
url: https://developer.box.com
email: devrel@box.com
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: '2024.0'
x-box-commit-hash: 3d705a6550
servers:
- url: https://api.box.com/2.0
description: Box Platform API server.
security:
- OAuth2Security: []
tags:
- name: AI
description: A set of endpoints used to interact with supported LLMs.
x-box-tag: ai
- name: AI Studio
description: A set of endpoints used to interact with AI Studio.
x-box-tag: ai_studio
- name: App item associations
x-box-tag: app_item_associations
- name: Authorization
description: A set of endpoints used to manage user authorization process.
x-box-tag: authorization
x-box-priority: true
- name: Box Sign requests
description: Box Sign requests are used to submit a file for signature.
x-box-tag: sign_requests
- name: Classifications
description: >-
Classification labels are used for content that is sensitive or under
security restrictions.
x-box-tag: classifications
- name: Classifications on files
description: >-
Classification labels are used for files that are sensitive or under
security restrictions.
x-box-tag: file_classifications
- name: Classifications on folders
description: >-
Classification labels are used for folders that are sensitive or under
security restrictions.
x-box-tag: folder_classifications
- name: Collaborations
description: >-
Collaborations define access permissions for users and groups to files and
folders, similar to access control lists.
x-box-tag: user_collaborations
- name: Collaborations (List)
description: >-
A set of endpoints used to retrieve file, folder, pending, and group
collaborations.
x-box-tag: list_collaborations
- name: Collections
description: >-
Collections are a way to group files, folders, and web links without
putting them all into a folder.
x-box-tag: collections
- name: Comments
description: >-
Comments are messages generated users on files, allowing users to
collaborate on a file, discussing any feedback they might have on the
content.
x-box-tag: comments
- name: Device pinners
description: >-
Device pinners allow enterprises to control what devices can use native
Box applications.
x-box-tag: device_pinners
- name: Domain restrictions (User exemptions)
description: >-
A set of endpoints that allow exempting users from restrictions imposed by
the list of allowed collaboration domains for a specific enterprise.
x-box-tag: collaboration_allowlist_exempt_targets
- name: Domain restrictions for collaborations
description: >-
A set of endpoints that manage domains for which users can collaborate
with files and folders in an enterprise.
x-box-tag: collaboration_allowlist_entries
- name: Downloads
description: >-
Downloads allow saving files to the application's server, or directly by
the end user in a browser.
x-box-tag: downloads
- name: Email aliases
description: >-
Email aliases provide a list of emails additional to the user's primary
login email.
x-box-tag: email_aliases
- name: Events
description: >-
Events provide a way for an application to subscribe to any actions
performed by any user, users, or service in an enterprise.
x-box-tag: events
- name: File requests
description: >-
File Requests provide a fast and secure way to request files and
associated metadata from anyone. Users can create new file requests based
on an existing file request, update file request settings, activate,
deactivate, and delete file requests programmatically.
x-box-tag: file_requests
- name: File version legal holds
description: >-
A legal hold is a process that an enterprise can use to preserve all forms
of potentially relevant information when litigation is pending or
reasonably anticipated. A File Version Legal Hold represents all the
policies that are assigned to a specific file version.
x-box-tag: file_version_legal_holds
- name: File version retentions
description: >-
A retention policy blocks permanent deletion of content for a specified
amount of time. A file version retention is a record for a retained file.
x-box-tag: file_version_retentions
- name: File versions
description: A set of endpoints used to manage specific versions of a file.
x-box-tag: file_versions
- name: Files
description: >-
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.
x-box-tag: files
- name: Folder Locks
description: >-
Folder locks define access restrictions placed by folder owners to prevent
specific folders from being moved or deleted.
x-box-tag: folder_locks
- name: Folders
description: >-
Folders, together with Files, are at the core of the Box API. Folders can
be uploaded and downloaded, as well as hold important metadata information
about the content.
x-box-tag: folders
- name: Integration mappings
description: >-
Integration Mappings allow the users to manage where content from partner
apps is stored in Box.
x-box-tag: integration_mappings
- name: Group memberships
description: Group memberships signify that a user is a part of the group.
x-box-tag: memberships
- name: Groups
description: Groups created in an enterprise.
x-box-tag: groups
- name: Invites
description: Invites are used to invite the user to an enterprise.
x-box-tag: invites
- name: Legal hold policies
description: >-
A legal hold is a process that an enterprise can use to preserve all forms
of potentially relevant information when litigation is pending or
reasonably anticipated.
x-box-tag: legal_hold_policies
- name: Legal hold policy assignments
description: >-
A Legal Hold Policy Assignment is a relation between a policy and
custodian. In this case, as custodian can be a user, folder, file, or file
version.
x-box-tag: legal_hold_policy_assignments
- name: Metadata cascade policies
description: >-
A metadata cascade policy describes how metadata instances applied to a
folder should be applied to any item within that folder.
x-box-tag: metadata_cascade_policies
- name: Metadata instances (Files)
description: >-
A metadata instance describes the relation between a template and a file,
including the values that are assigned for every field.
x-box-tag: file_metadata
- name: Metadata instances (Folders)
description: >-
A metadata instance describes the relation between a template and a
folder, including the values that are assigned for every field.
x-box-tag: folder_metadata
- name: Metadata taxonomies
description: >-
A metadata taxonomy is a hierarchical classification system that helps
organize and manage metadata within an enterprise.
x-box-tag: metadata_taxonomies
- name: Metadata templates
description: >-
A metadata template describes a reusable set of key/value pairs that can
be assigned to a file.
x-box-tag: metadata_templates
- name: Recent items
description: >-
Recent items represent items such as files or folders that the user
accessed recently.
x-box-tag: recent_items
- name: Retention policies
description: >-
A retention policy blocks permanent deletion of content for a specified
amount of time. Admins can create retention policies and then assign them
to specific folders or their entire enterprise.
x-box-tag: retention_policies
- name: Retention policy assignments
description: >-
A Retention Policy Assignment is a relation between a policy and folder or
enterprise. Creating an assignment puts a retention on all the file
versions that belong to that folder or enterprise.
x-box-tag: retention_policy_assignments
- name: Search
description: >-
The Box API provides a way to find content in Box using full-text search
queries.
x-box-tag: search
- name: Session termination
description: >-
Session termination API is used to validate the roles and permissions of
the group, and creates asynchronous jobs to terminate the group's
sessions.
x-box-tag: session_termination
- name: Shared links (Files)
description: >-
Files shared links are URLs that are generated for files stored in Box,
which provide direct, read-only access to the resource.
x-box-tag: shared_links_files
- name: Shared links (Folders)
description: >-
Folders shared links are URLs that are generated for folders stored in
Box, which provide direct, read-only access to the resource.
x-box-tag: shared_links_folders
- name: Shared links (Web Links)
description: >-
Web links for files are URLs that are generated for web links in Box,
which provide direct, read-only access to the resource.
x-box-tag: shared_links_web_links
- name: Shared links (App Items)
description: >-
URLs generated for app items stored in Box, which provide direct,
read-only access to the resource.
x-box-tag: shared_links_app_items
- name: Shield information barriers
description: >-
Shield information barrier in Box defines an ethical wall. An ethical wall
is a mechanism that prevents exchanges or communication that could lead to
conflicts of interest and therefore result in business activities
ethically or legally questionable.
x-box-tag: shield_information_barriers
- name: Shield information barrier segments
description: >-
Shield information barrier segment represents a defined group of users. A
user can be a member of only one segment, which makes segments different
from groups.
x-box-tag: shield_information_barrier_segments
- name: Shield information barrier segment members
description: >-
Shield information barrier segment member represents a user that is
assigned to a specific segment.
x-box-tag: shield_information_barrier_segment_members
- name: Shield information barrier reports
description: >-
Shield information barrier reports contain information on what existing
collaborations will be removed permanently when the information barrier is
enabled.
x-box-tag: shield_information_barrier_reports
- name: Shield information barrier segment restrictions
description: >-
Shield information barrier segment restriction is an access restriction
based on the content (file or folder) owner.
x-box-tag: shield_information_barrier_segment_restrictions
- name: Box Sign templates
description: >-
Sign templates allow you to use a predefined Box Sign template when
creating a signature request. The template includes placeholders that are
automatically populated with data when creating the request.
x-box-tag: sign_templates
- name: Skills
description: >-
Box Skills are designed to allow custom processing of files uploaded to
Box, with the intent of enhancing the underlying metadata of the file.
x-box-tag: skills
- name: Standard and Zones Storage Policies
description: >-
Storage policy assignment represents the storage zone for items in a given
enterprise.
x-box-tag: storage_policies
- name: Standard and Zones Storage Policy Assignments
description: >-
Storage policy assignment represents the relation between storage zone and
the assigned item (for example a file stored in a specific zone).
x-box-tag: storage_policy_assignments
- name: Task assignments
description: >-
A task assignment defines which task is assigned to which user to
complete.
x-box-tag: task_assignments
- name: Tasks
description: >-
Tasks allow users to request collaborators on a file to review a file or
complete a piece of work. Tasks can be used by developers to create
file-centric workflows.
x-box-tag: tasks
- name: Terms of service
description: A set of endpoints used to manage terms of service agreements.
x-box-tag: terms_of_services
- name: Terms of service user statuses
description: >-
A set of endpoints used to manage the status of terms of service for a
particular user.
x-box-tag: terms_of_service_user_statuses
- name: Transfer folders
description: >-
API designed to move all of the items (files, folders and workflows) owned
by a user into another user's account.
x-box-tag: transfer
- name: Trashed files
description: Files that were deleted and are in trash.
x-box-tag: trashed_files
- name: Trashed folders
description: Folders that were deleted and are in trash.
x-box-tag: trashed_folders
- name: Trashed items
description: Items that were deleted and are in trash.
x-box-tag: trashed_items
- name: Trashed web links
description: Web links that were deleted and are in trash.
x-box-tag: trashed_web_links
- name: Uploads
description: >-
The direct file upload API supports files up to 50MB in size and sends all
the binary data to the Box API in 1 API request.
x-box-tag: uploads
- name: Uploads (Chunked)
description: >-
The chunked upload endpoints support files from 20MB in size and allow an
application to upload the file in parts, allowing for more control to
catch any errors and retry parts individually.
x-box-tag: chunked_uploads
- name: User avatars
description: >-
User avatars are JPG or PNG files uploaded to Box to represent the user
image. They are then displayed in the user account.
x-box-tag: avatars
- name: Users
description: >-
Box API supports a variety of users, ranging from real employees logging
in with their Managed User account, to applications using App Users to
drive powerful automation workflows.
x-box-tag: users
- name: Watermarks (Files)
description: >-
A watermark is a semi-transparent overlay on an embedded file preview that
displays a viewer's email address or user ID and the time of access over
the file.
x-box-tag: file_watermarks
- name: Watermarks (Folders)
description: >-
A watermark is a semi-transparent overlay on an embedded folder preview
that displays a viewer's email address or user ID and the time of access
over the folder content.
x-box-tag: folder_watermarks
- name: Web links
description: >-
Web links are objects that point to URLs. These objects are also known as
bookmarks within the Box web application.
x-box-tag: web_links
- name: Webhooks
description: >-
Webhooks allow you to monitor Box content for events, and receive
notifications to a URL of your choice when they occur. For example, a
workflow may include waiting for a file to be downloaded to delete a
shared link.
x-box-tag: webhooks
- name: Workflows
description: >-
Box Relay Workflows are objects that represent a named collection of
flows.
x-box-tag: workflows
- name: Zip Downloads
description: >-
Zip downloads represent a successful request to create a ZIP archive with
files and folders.
x-box-tag: zip_downloads
externalDocs:
description: Box Developer Documentation.
url: https://developer.box.com
paths:
/files/{file_id}/content:
post:
tags:
- Uploads
summary: Upload file version
description: >-
Update a file's content. For file sizes over 50MB we recommend using the
Chunk Upload APIs.
The `attributes` part of the body must come **before** the `file` part.
Requests that do not follow this format when uploading the file will
receive a HTTP `400` error with a `metadata_after_file_contents` error
code.
operationId: post_files_id_content
parameters:
- name: file_id
in: path
description: >-
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`.
required: true
schema:
type: string
example: '12345'
- name: if-match
in: header
description: >-
Ensures this item hasn't recently changed before making changes.
Pass in the item's last observed `etag` value into this header and
the endpoint will fail with a `412 Precondition Failed` if it has
changed since.
required: false
schema:
type: string
example: '1'
- name: fields
in: query
description: >-
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.
required: false
schema:
type: array
items:
type: string
example:
- id
- type
- name
explode: false
- name: content-md5
in: header
description: >-
An optional header containing the SHA1 hash of the file to ensure
that the file was not corrupted in transit.
required: false
schema:
type: string
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
attributes:
description: >-
The additional attributes of the file being uploaded. Mainly
the name and the parent folder. These attributes are part of
the multi part request body and are in JSON format.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
type: object
properties:
name:
description: >-
An optional new name for the file. If specified, the
file will be renamed when the new version is uploaded.
type: string
example: Photo 2.0.png
content_modified_at:
description: |-
Defines the time the file was last modified at.
If not set, the upload time will be used.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
required:
- name
file:
description: >-
The content of the file to upload to Box.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
type: string
format: binary
required:
- attributes
- file
responses:
'200':
description: Returns the new file object in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/Files'
'412':
description: >-
Returns an error when the `If-Match` header does not match the
current `etag` value of the file. This indicates that the file has
changed since it was last requested.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads.
x-codeSamples:
- lang: curl
label: Upload file version
source: >-
curl -i -X POST "https://upload.box.com/api/2.0/files/12345/content"
\
-H "authorization: Bearer " \
-H "content-type: multipart/form-data" \
-F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \
-F file=@
- lang: dotnet
label: Upload file version
source: >-
await client.Uploads.UploadFileVersionAsync(fileId: uploadedFile.Id,
requestBody: new UploadFileVersionRequestBody(attributes: new
UploadFileVersionRequestBodyAttributesField(name:
newFileVersionName), file: newFileContentStream));
- lang: java
label: Upload file version
source: >-
client.getUploads().uploadFileVersion(uploadedFile.getId(), new
UploadFileVersionRequestBody(new
UploadFileVersionRequestBodyAttributesField(newFileVersionName),
newFileContentStream))
- lang: node
label: Upload file version
source: |-
await client.uploads.uploadFileVersion(file.id, {
attributes: {
name: file.name!,
} satisfies UploadFileVersionRequestBodyAttributesField,
file: generateByteStream(20),
} satisfies UploadFileVersionRequestBody);
- lang: python
label: Upload file version
source: |-
client.uploads.upload_file_version(
uploaded_file.id,
UploadFileVersionAttributes(name=new_file_version_name),
new_file_content_stream,
)
components:
schemas:
Files:
description: A list of files.
type: object
properties:
total_count:
description: The number of files.
type: integer
format: int64
example: 1
entries:
description: A list of files.
type: array
items:
$ref: '#/components/schemas/File--Full'
title: Files
x-box-resource-id: files
x-box-tag: files
ClientError:
description: A generic error.
type: object
properties:
type:
description: The value will always be `error`.
type: string
example: error
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
type: integer
format: int32
example: 400
nullable: false
code:
description: A Box-specific error code.
type: string
example: item_name_invalid
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
type: string
example: Method Not Allowed
nullable: false
context_info:
description: >-
A free-form object that contains additional context about the error.
The possible fields are defined on a per-endpoint basis. `message`
is only one example.
type: object
example:
message: Something went wrong
additionalProperties: {}
nullable: true
help_url:
description: A URL that links to more information about why this error occurred.
type: string
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
nullable: false
request_id:
description: >-
A unique identifier for this response, which can be used when
contacting Box support.
type: string
example: abcdef123456
nullable: false
title: Client error
x-box-resource-id: client_error
File--Full:
description: >-
A full representation of a file, as can be returned from any file API
endpoints by default.
type: object
allOf:
- $ref: '#/components/schemas/File'
- properties:
version_number:
description: The version number of this file.
type: string
example: '1'
comment_count:
description: The number of comments on this file.
type: integer
example: 10
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:
description: Specifies if the current user can delete this item.
type: boolean
example: true
nullable: false
can_download:
description: >-
Specifies if the current user can download this
item.
type: boolean
example: true
nullable: false
can_invite_collaborator:
description: >-
Specifies if the current user can invite new users
to collaborate on this item, and if the user can
update the role of a user already collaborated on
this item.
type: boolean
example: true
nullable: false
can_rename:
description: Specifies if the user can rename this item.
type: boolean
example: true
nullable: false
can_set_share_access:
description: >-
Specifies if the user can change the access level of
an existing shared link on this item.
type: boolean
example: true
nullable: false
can_share:
description: >-
Specifies if the user can create a shared link for
this item.
type: boolean
example: true
nullable: false
- properties:
can_annotate:
description: >-
Specifies if the user can place annotations on this
file.
type: boolean
example: true
nullable: false
can_comment:
description: >-
Specifies if the user can place comments on this
file.
type: boolean
example: true
nullable: false
can_preview:
description: Specifies if the user can preview this file.
type: boolean
example: true
nullable: false
can_upload:
description: >-
Specifies if the user can upload a new version of
this file.
type: boolean
example: true
nullable: false
can_view_annotations_all:
description: >-
Specifies if the user view all annotations placed on
this file.
type: boolean
example: true
nullable: false
can_view_annotations_self:
description: >-
Specifies if the user view annotations placed by
themselves on this file.
type: boolean
example: true
nullable: false
can_apply_watermark:
description: >-
Specifies if the user can apply a watermark to this
file.
type: boolean
example: true
nullable: false
- description: >-
Describes the permissions that the current user has for 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 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.
- nullable: false
lock:
allOf:
- title: Lock
type: object
description: >-
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.
properties:
id:
description: The unique identifier for this lock.
type: string
example: '11446498'
type:
description: The value will always be `lock`.
type: string
example: lock
enum:
- lock
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created the lock.
created_at:
description: The time this lock was created at.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
expired_at:
description: >-
The time this lock is to expire at, which might be in
the past.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
is_download_prevented:
description: Whether or not the file can be downloaded while locked.
type: boolean
example: true
app_type:
description: >-
If the lock is managed by an application rather than a
user, this field identifies the type of the application
that holds the lock. This is an open enum and may be
extended with additional values in the future.
type: string
example: office_wopiplus
enum:
- gsuite
- office_wopi
- office_wopiplus
- other
nullable: true
- description: >-
The lock held on this file. If there is no lock, this can
either be `null` or have a timestamp in the past.
nullable: true
extension:
description: >-
Indicates the (optional) file extension for this file. By
default, this is set to an empty string.
type: string
example: pdf
is_package:
description: >-
Indicates if the file is a package. Packages are commonly used
by Mac Applications and can include iWork files.
type: boolean
example: true
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:
description: The requested access token.
type: string
format: token
example: >-
c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
expires_in:
description: The time in seconds by which this token will expire.
type: integer
format: int64
example: 3600
token_type:
description: The type of access token returned.
type: string
example: bearer
enum:
- bearer
restricted_to:
description: >-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those
resources.
type: array
items:
$ref: '#/components/schemas/ResourceScope'
- properties:
url:
description: >-
The actual expiring embed URL for this file,
constructed from the file ID and access tokens
specified in this object.
type: string
format: url
example: https://cloud.app.box.com/preview/expiring_embed/...
- description: >-
Requesting this field creates an expiring Box Embed URL for
an embedded preview session in an `iframe`.
This URL will expire after 60 seconds and the session will
expire after 60 minutes.
Not all file types are supported for these embed URLs. Box
Embed is not optimized for mobile browsers and should not be
used in web experiences designed for mobile devices. Many UI
elements, like the **download** and **print** options might
not show in mobile browsers.
watermark_info:
allOf:
- type: object
description: Details about the watermark applied to this item.
properties:
is_watermarked:
description: Specifies if this item has a watermark applied.
type: boolean
example: true
nullable: false
is_watermark_inherited:
description: >-
Specifies if the watermark is inherited from any parent
folder in the hierarchy.
type: boolean
example: false
nullable: false
is_watermarked_by_access_policy:
description: >-
Specifies if the watermark is enforced by an access
policy.
type: boolean
example: false
nullable: false
- description: Details about the watermark applied to this file.
is_accessible_via_shared_link:
description: >-
Specifies if the file can be accessed via the direct shared link
or a shared link to a parent folder.
type: boolean
example: true
allowed_invitee_roles:
description: >-
A list of the types of roles that user can be invited at when
sharing this file.
type: array
items:
type: string
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
example:
- editor
nullable: false
is_externally_owned:
description: >-
Specifies if this file is owned by a user outside of the
authenticated enterprise.
type: boolean
example: true
nullable: false
has_collaborations:
description: Specifies if this file has any other collaborators.
type: boolean
example: true
nullable: false
metadata:
allOf:
- title: Item metadata instances
type: object
description: >-
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..`
For 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` and `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--Full'
- description: >-
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_at:
description: When the file will automatically be deleted.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
representations:
allOf:
- title: Representations
description: A list of file representations.
type: object
properties:
entries:
description: A list of files.
type: array
items:
type: object
description: A file representation.
properties:
content:
description: >-
An object containing the URL that can be used to
actually fetch the representation.
properties:
url_template:
description: >-
The download URL that can be used to fetch the
representation. Make sure to make an
authenticated API call to this endpoint.
This URL is a template and will require the
`{+asset_path}` to be replaced by a path. In
general, for unpaged representations it can be
replaced by an empty string.
For paged representations, replace the
`{+asset_path}` with the page to request plus
the extension for the file, for example
`1.pdf`.
When requesting the download URL the following
additional query params can be passed along.
- `set_content_disposition_type` - Sets the
`Content-Disposition` header in the API
response with the specified disposition type
of either `inline` or `attachment`. If not
supplied, the `Content-Disposition` header is
not included in the response.
- `set_content_disposition_filename` - Allows
the application to define the representation's
file name used in the `Content-Disposition`
header. If not defined, the filename is
derived from the source file name in Box
combined with the extension of the
representation.
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
type: object
info:
description: >-
An object containing the URL that can be used to
fetch more info on this representation.
type: object
properties:
url:
description: >-
The API URL that can be used to get more info
on this file representation. Make sure to make
an authenticated API call to this endpoint.
type: string
example: >-
https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
properties:
description: >-
An object containing the size and type of this
presentation.
type: object
properties:
dimensions:
type: string
format: x
example: 2048x2048
description: >-
The width by height size of this
representation in pixels.
paged:
type: string
example: 'true'
description: >-
Indicates if the representation is build up
out of multiple pages.
thumb:
type: string
example: 'true'
description: >-
Indicates if the representation can be used as
a thumbnail of the file.
representation:
description: >-
Indicates the file type of the returned
representation.
type: string
example: png
status:
description: >-
An object containing the status of this
representation.
type: object
properties:
state:
description: >-
The status of the representation.
- `success` defines the representation as
ready to be viewed.
- `viewable` defines a video to be ready for
viewing.
- `pending` defines the representation as to
be generated. Retry this endpoint to re-check
the status.
- `none` defines that the representation will
be created when requested. Request the URL
defined in the `info` object to trigger this
generation.
type: string
example: success
enum:
- success
- viewable
- pending
- none
- description: >-
A list of representations for a file that can be used to
display a placeholder of the file in your application. By
default this returns all representations and we recommend
using the `x-rep-hints` header to further customize the
desired representations.
classification:
allOf:
- type: object
description: The classification applied to an item.
properties:
name:
description: The name of the classification.
type: string
example: Top Secret
definition:
description: An explanation of the meaning of this classification.
type: string
example: Content that should not be shared outside the company.
color:
description: >-
The color that is used to display the classification
label in a user-interface. Colors are defined by the
admin or co-admin who created the classification in the
Box web app.
type: string
example: '#FF0000'
- 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 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:
description: The retention expiration timestamp for the given file.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
shared_link_permission_options:
description: >-
A list of the types of roles that user can be invited at when
sharing this file.
type: array
items:
type: string
enum:
- can_preview
- can_download
- can_edit
example:
- can_preview
nullable: true
is_associated_with_app_item:
description: >-
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.
type: boolean
example: true
nullable: false
title: File (Full)
x-box-resource-id: file--full
x-box-tag: files
x-box-variant: full
File:
description: >-
A standard representation of a file, as returned from any file API
endpoints by default.
type: object
allOf:
- $ref: '#/components/schemas/File--Mini'
- properties:
description:
description: >-
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.
type: string
example: Contract for Q1 renewal
maxLength: 255
nullable: false
size:
description: >-
The file size in bytes. Be careful parsing this integer as it
can get very large and cause an integer overflow.
type: integer
example: 629644
nullable: false
path_collection:
allOf:
- title: Path collection
description: A list of parent folders for an item.
type: object
required:
- total_count
- entries
properties:
total_count:
description: The number of folders in this list.
type: integer
format: int64
example: 1
nullable: false
entries:
description: The parent folders for this item.
type: array
items:
$ref: '#/components/schemas/Folder--Mini'
nullable: false
- description: >-
The tree of folders that this file is contained in, starting
at the root.
- nullable: false
created_at:
description: The date and time when the file was created on Box.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: false
modified_at:
description: The date and time when the file was last updated on Box.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: false
trashed_at:
description: The time at which this file was put in the trash.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
purged_at:
description: >-
The time at which this file is expected to be purged from the
trash.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
content_created_at:
description: >-
The date and time at which this file was originally created,
which might be before it was uploaded to Box.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
content_modified_at:
description: >-
The date and time at which this file was last updated, which
might be before it was uploaded to Box.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
nullable: true
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created this file.
modified_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who last modified this file.
- nullable: false
owned_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who owns this file.
- nullable: false
shared_link:
allOf:
- title: Shared link
description: >-
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.
type: object
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
properties:
url:
description: >-
The URL that can be used to access the item on Box.
This URL will display the item in Box's preview UI where
the file can be downloaded if allowed.
This URL will continue to work even when a custom
`vanity_url` has been set for this shared link.
type: string
format: url
example: https://www.box.com/s/vspke7y05sb214wjokpk
nullable: false
download_url:
description: >-
A URL that can be used to download the file. This URL
can be used in a browser to download the file. This URL
includes the file extension so that the file will be
saved with the right file type.
This property will be `null` for folders.
type: string
format: url
example: >-
https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
nullable: true
x-box-premium-feature: true
vanity_url:
description: >-
The "Custom URL" that can also be used to preview the
item on Box. Custom URLs can only be created or modified
in the Box Web application.
type: string
format: url
example: https://acme.app.box.com/v/my_url/
nullable: true
vanity_name:
description: >-
The custom name of a shared link, as used in the
`vanity_url` field.
type: string
example: my_url
nullable: true
access:
description: >-
The access level for this shared link.
- `open` - provides access to this item to anyone with
this link
- `company` - only provides access to this item to
people the same company
- `collaborators` - only provides access to this item to
people who are collaborators on this item
If this field is omitted when creating the shared link,
the access level will be set to the default access level
specified by the enterprise admin.
type: string
example: open
enum:
- open
- company
- collaborators
nullable: false
effective_access:
description: >-
The effective access level for the shared link. This can
be a more restrictive access level than the value in the
`access` field when the enterprise settings restrict the
allowed access levels.
type: string
example: company
enum:
- open
- company
- collaborators
nullable: false
effective_permission:
description: >-
The effective permissions for this shared link. These
result in the more restrictive combination of the share
link permissions and the item permissions set by the
administrator, the owner, and any ancestor item such as
a folder.
type: string
example: can_download
enum:
- can_edit
- can_download
- can_preview
- no_access
nullable: false
unshared_at:
description: >-
The date and time when this link will be unshared. This
field can only be set by users with paid accounts.
type: string
format: date-time
example: '2018-04-13T13:53:23-07:00'
nullable: true
is_password_enabled:
description: >-
Defines if the shared link requires a password to access
the item.
type: boolean
example: true
nullable: false
permissions:
description: >-
Defines if this link allows a user to preview, edit, and
download an item. These permissions refer to the shared
link only and do not supersede permissions applied to
the item itself.
type: object
properties:
can_download:
description: >-
Defines if the shared link allows for the item to be
downloaded. For shared links on folders, this also
applies to any items in the folder.
This value can be set to `true` when the effective
access level is set to `open` or `company`, not
`collaborators`.
type: boolean
example: true
nullable: false
can_preview:
description: >-
Defines if the shared link allows for the item to be
previewed.
This value is always `true`. For shared links on
folders this also applies to any items in the
folder.
type: boolean
example: true
nullable: false
can_edit:
description: >-
Defines if the shared link allows for the item to be
edited.
This value can only be `true` if `can_download` is
also `true` and if the item has a type of `file`.
type: boolean
example: false
nullable: false
required:
- can_download
- can_preview
- can_edit
download_count:
description: The number of times this item has been downloaded.
type: integer
example: 3
nullable: false
preview_count:
description: The number of times this item has been previewed.
type: integer
example: 3
nullable: false
- description: >-
The shared link for this file. This value will be `null` if
no shared link has been created for this file.
- nullable: true
parent:
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: >-
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.
nullable: true
item_status:
description: >-
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.
type: string
example: active
enum:
- active
- trashed
- deleted
nullable: false
title: File
x-box-resource-id: file
x-box-tag: files
x-box-variant: standard
User--Mini:
description: >-
A mini representation of a user, as can be returned when nested within
other resources.
type: object
allOf:
- $ref: '#/components/schemas/User--Base'
- properties:
name:
description: The display name of this user.
type: string
example: Aaron Levie
maxLength: 50
nullable: false
login:
description: The primary email address of this user.
type: string
format: email
example: ceo@example.com
nullable: false
title: User (Mini)
x-box-resource-id: user--mini
x-box-tag: users
x-box-variant: mini
ResourceScope:
description: >-
A relation between a resource (file or folder) and the scopes for which
the resource can be accessed.
type: object
properties:
scope:
description: The scopes for the resource access.
type: string
example: item_download
enum:
- annotation_edit
- annotation_view_all
- annotation_view_self
- base_explorer
- base_picker
- base_preview
- base_upload
- item_delete
- item_download
- item_preview
- item_rename
- item_share
- item_upload
- item_read
object:
$ref: '#/components/schemas/Resource'
title: Resource scope
Metadata--Full:
description: >-
An instance of a metadata template, which has been applied to a file or
folder.
type: object
allOf:
- $ref: '#/components/schemas/Metadata'
- properties:
$canEdit:
description: Whether the user can edit this metadata instance.
type: boolean
example: true
$id:
description: A UUID to identify the metadata instance.
type: string
format: uuid
example: 01234500-12f1-1234-aa12-b1d234cb567e
maxLength: 36
$type:
description: >-
A unique identifier for the "type" of this instance. This is an
internal system property and should not be used by a client
application.
type: string
example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion:
description: >-
The last-known version of the template of the object. This is an
internal system property and should not be used by a client
application.
type: integer
example: 2
- additionalProperties:
allOf:
- {}
- example: Aaron Levie
- description: >-
A value for each of the fields that are present on the
metadata template. For the `global.properties` template this
can be a list of zero or more fields, as this template allows
for any generic key-value pairs to be stored stored in the
template.
x-box-example-key: name
title: Metadata instance (Full)
x-box-resource-id: metadata--full
x-box-tag: file_metadata
x-box-variant: full
File--Mini:
description: >-
A mini representation of a file, used when nested under another
resource.
type: object
allOf:
- $ref: '#/components/schemas/File--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: >-
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.
- nullable: false
name:
description: The name of the file.
type: string
example: Contract.pdf
sha1:
description: >-
The SHA1 hash of the file. This can be used to compare the
contents of a file on Box with a local file.
type: string
format: digest
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
nullable: false
file_version:
allOf:
- $ref: '#/components/schemas/FileVersion--Mini'
- description: The information about the current version of the file.
nullable: true
title: File (Mini)
x-box-resource-id: file--mini
x-box-tag: files
x-box-variant: mini
Folder--Mini:
description: >-
A mini representation of a file version, used when nested under another
resource.
type: object
allOf:
- $ref: '#/components/schemas/Folder--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: >-
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.
- nullable: false
name:
description: The name of the folder.
type: string
example: Contracts
nullable: false
title: Folder (Mini)
x-box-resource-id: folder--mini
x-box-tag: folders
x-box-variant: mini
User--Base:
description: >-
A mini representation of a user, used when nested within another
resource.
type: object
properties:
id:
description: The unique identifier for this user.
type: string
example: '11446498'
type:
description: The value will always be `user`.
type: string
example: user
enum:
- user
nullable: false
required:
- type
- id
title: User (Base)
x-box-resource-id: user--base
x-box-tag: users
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
Resource:
description: The file or folder resource.
type: object
oneOf:
- $ref: '#/components/schemas/Folder--Mini'
- $ref: '#/components/schemas/File--Mini'
title: Resource
Metadata:
description: >-
An instance of a metadata template, which has been applied to a file or
folder.
type: object
allOf:
- $ref: '#/components/schemas/Metadata--Base'
title: Metadata instance
x-box-resource-id: metadata
x-box-tag: file_metadata
x-box-variant: standard
File--Base:
description: >-
The bare basic representation of a file, the minimal amount of fields
returned when using the `fields` query parameter.
type: object
properties:
id:
description: >-
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`.
type: string
example: '12345'
nullable: false
etag:
description: >-
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: string
example: '1'
nullable: true
type:
description: The value will always be `file`.
type: string
example: file
enum:
- file
nullable: false
nullable: true
required:
- id
- type
title: File (Base)
x-box-resource-id: file--base
x-box-tag: files
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
FileVersion--Mini:
description: >-
A mini representation of a file version, used when nested within another
resource.
type: object
allOf:
- $ref: '#/components/schemas/FileVersion--Base'
- properties:
sha1:
description: The SHA1 hash of this version of the file.
type: string
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
title: File version (Mini)
x-box-resource-id: file_version--mini
x-box-variant: mini
Folder--Base:
description: >-
The bare basic representation of a folder, the minimal amount of fields
returned when using the `fields` query parameter.
type: object
properties:
id:
description: >-
The unique identifier that represent a folder.
The ID for any folder can be determined by visiting a folder in the
web application and copying the ID from the URL. For example, for
the URL `https://*.app.box.com/folders/123` the `folder_id` is
`123`.
type: string
example: '12345'
nullable: false
etag:
description: >-
The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.
type: string
example: '1'
nullable: true
type:
description: The value will always be `folder`.
type: string
example: folder
enum:
- folder
nullable: false
required:
- id
- type
title: Folder (Base)
x-box-resource-id: folder--base
x-box-tag: folders
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
Metadata--Base:
description: The base representation of a metadata instance.
type: object
properties:
$parent:
description: >-
The identifier of the item that this metadata instance has been
attached to. This combines the `type` and the `id` of the parent in
the form `{type}_{id}`.
type: string
example: folder_59449484661,
$template:
description: The name of the template.
type: string
example: marketingCollateral
$scope:
description: >-
An ID for the scope in which this template has been applied. This
will be `enterprise_{enterprise_id}` for templates defined for use
in this enterprise, and `global` for general templates that are
available to all enterprises using Box.
type: string
example: enterprise_27335
$version:
description: >-
The version of the metadata instance. This version starts at 0 and
increases every time a user-defined property is modified.
type: integer
example: 1
title: Metadata instance (Base)
x-box-resource-id: metadata--base
x-box-tag: file_metadata
x-box-variant: base
x-box-variants:
- base
- standard
- full
FileVersion--Base:
description: >-
The bare basic representation of a file version, the minimal amount of
fields returned when using the `fields` query parameter.
type: object
properties:
id:
description: The unique identifier that represent a file version.
type: string
example: '12345'
nullable: false
type:
description: The value will always be `file_version`.
type: string
example: file_version
enum:
- file_version
nullable: false
required:
- id
- type
title: File version (Base)
x-box-resource-id: file_version--base
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
securitySchemes:
OAuth2Security:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://account.box.com/api/oauth2/authorize
tokenUrl: https://api.box.com/oauth2/token
scopes:
root_readonly: Read all files and folders stored in Box
root_readwrite: Read and write all files and folders stored in Box
manage_app_users: Provision and manage app users
manage_managed_users: Provision and manage managed users
manage_groups: Manage an enterprise's groups
manage_webhook: Create webhooks programmatically through the API
manage_enterprise_properties: Manage enterprise properties
manage_data_retention: Manage data retention polices
manage_legal_hold: Manage Legal Holds
````