openapi: 3.1.0
info:
title: Box Files API
description: Needs a description.
paths:
/files/{file_id}:
get:
operationId: get_files_id
summary: Box Get file information
tags:
- Files
x-box-tag: files
x-box-enable-explorer: true
description: Retrieves the details about a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
Additionally this field can be used to query any metadata
applied to the file by specifying the `metadata` field as well
as the scope and key of the template to retrieve, for example
`?field=metadata.enterprise_12345.contractTemplate`.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: if-none-match
description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
in: header
required: false
example: '1'
schema:
type: string
- name: boxapi
description: >-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required
then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on
any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
required: false
schema:
type: string
- name: x-rep-hints
description: |-
A header required to request specific `representations`
of a file. Use this in combination with the `fields` query
parameter to request a specific file representation.
The general format for these representations is
`X-Rep-Hints: [...]` where `[...]` is one or many
hints in the format `[fileType?query]`.
For example, to request a `png` representation in `32x32`
as well as `64x64` pixel dimensions provide the following
hints.
`x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`
Additionally, a `text` representation is available for all
document file types in Box using the `[extracted_text]`
representation.
`x-rep-hints: [extracted_text]`
example: '[pdf]'
in: header
required: false
schema:
type: string
nullable: true
responses:
'200':
description: |-
Returns a file object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
'304':
description: >-
Returns an empty response when the `If-None-Match` header matches
the current `etag` value of the folder. This indicates that the
folder
has not changed since it was last requested.
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'415':
description: |-
Returns an error if an action is performed on a file with an
incorrect media type.
* `unsupported_media_type` when requesting an `expiring_embed_link`
for a file that is not supported by Box Embed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_id
summary: Box Restore file
tags:
- Files
x-box-tag: trashed_files
description: >-
Restores a file that has been moved to the trash.
An optional new parent ID can be provided to restore the file to in case
the
original folder has been deleted.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
description: An optional new name for the file.
example: Restored.docx
type: string
parent:
allOf:
- type: object
description: The parent for this item
properties:
id:
type: string
description: The ID of parent item
example: '123'
- description: >-
Specifies an optional ID of a folder to restore the file
to
when the original folder no longer exists.
Please be aware that this ID will only be used if the
original
folder no longer exists. Use this ID to provide a
fallback
location to restore the file to if the original location
has been deleted.
responses:
'201':
description: Returns a file object when the file has been restored.
content:
application/json:
schema:
$ref: '#/components/schemas/TrashFileRestored'
'403':
description: |-
Returns an error if the user does not have access to the folder
the file is being restored to, or the user does not have permission
to restore files from the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Returns an error if the file is not in the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: |-
Returns an error if there is an file with the same name
in the folder the file is being restored to.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id
summary: Box Update file
tags:
- Files
x-box-tag: files
x-box-enable-explorer: true
x-box-sanitized: true
description: |-
Updates a file. This can be used to rename or move a file,
create a shared link, or lock a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: if-match
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.
in: header
required: false
example: '1'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: |-
An optional different name for the file. This can be used to
rename the file.
example: NewFile.txt
description:
type: string
description: >-
The description for a file. This can be seen in the
right-hand sidebar panel
when viewing a file in the Box web app. Additionally, this
index is used in
the search index of the file, allowing users to find the
file by the content
in the description.
maxLength: 256
example: The latest reports. Automatically updated
parent:
allOf:
- type: object
description: The parent for this item
properties:
id:
type: string
description: The ID of parent item
example: '123'
- description: >-
An optional new parent folder for the file. This can be
used
to move the file to a new folder.
shared_link:
allOf:
- description: >-
Defines a shared link for an item. Set this to `null` to
remove
the shared link.
type: object
properties:
access:
type: string
description: >-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only
people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level
specified
by the enterprise admin. To create a shared link
with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {}
}`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
password:
type: string
description: >-
The password required to access the shared link. Set
the
password to `null` to remove it.
Passwords must now be at least eight characters
long and include a number, upper case letter, or
a non-numeric or non-alphabetic character.
A password can only be set when `access` is set to
`open`.
example: do-n8t-use-this-Password
vanity_name:
type: string
description: >-
Defines a custom vanity name to use in the shared
link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing
sensitive content
as vanity URLs are a lot easier to guess than
regular shared links.
example: my-shared-link
unshared_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts.
permissions:
type: object
properties:
can_download:
type: boolean
example: true
description: >-
If the shared link allows for downloading of
files.
This can only be set when `access` is set to
`open` or `company`.
- description: >-
Defines a shared link for a file. Set this to `null` to
remove
the shared link.
lock:
type: object
description: >-
Defines a lock on an item. This prevents the item from being
moved, renamed, or otherwise changed by anyone other than
the user
who created the lock.
Set this to `null` to remove the lock.
required:
- type
properties:
access:
type: string
description: The type of this object.
enum:
- lock
example: lock
expires_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: Defines the time at which the lock expires.
is_download_prevented:
type: boolean
example: true
description: >-
Defines if the file can be downloaded while it is
locked.
disposition_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: |-
The retention expiration timestamp for the given file. This
date cannot be shortened once set on a file.
permissions:
description: Defines who can download a file.
type: object
properties:
can_download:
description: >-
Defines who is allowed to download this file. The
possible
values are either `open` for everyone or `company` for
the other members of the user's enterprise.
This setting overrides the download permissions that are
normally part of the `role` of a collaboration. When set
to
`company`, this essentially removes the download option
for
external users with `viewer` or `editor` a roles.
type: string
example: open
enum:
- open
- company
collections:
type: array
description: |-
An array of collections to make this file
a member of. Currently
we only support the `favorites` collection.
To get the ID for a collection, use the
[List all collections][1] endpoint.
Passing an empty array `[]` or `null` will remove
the file from all collections.
[1]: e://get-collections
items:
title: Reference
description: The bare basic reference for an object
type: object
properties:
id:
type: string
description: The unique identifier for this object
example: '11446498'
type:
type: string
description: The type for this object
example: file
tags:
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.
responses:
'200':
description: |-
Returns a file object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
'400':
description: Returned when the new retention time > maximum retention length.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returned if the user does not have all the permissions to complete
the
update.
* `access_denied_insufficient_permissions` returned
when the authenticated user does not have access
to the destination folder to move the file to.
* Returned when retention time is shorter or equal to current
retention
timestamp.
* Returned when a `file_id` that is not under retention is entered.
* Returned when a file that is retained but the disposition action
is set
to `remove_retention`
* `forbidden_by_policy` is returned if copying a folder is
forbidden due to information barrier restrictions.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'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'
delete:
operationId: delete_files_id
summary: Box Delete file
tags:
- Files
x-box-tag: files
x-box-sanitized: true
description: |-
Deletes a file, either permanently or by moving it to
the trash.
The the enterprise settings determine whether the item will
be permanently deleted from Box or moved to the trash.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: if-match
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.
in: header
required: false
example: '1'
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the file has been successfully
deleted.
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returned if the file is not found or has already been deleted, or
the user
does not have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'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'
/files/{file_id}/content:
get:
operationId: get_files_id_content
summary: Box Download file
tags:
- Files
x-box-tag: downloads
description: Returns the contents of a file in binary format.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: range
description: |-
The byte range of the content to download.
The format `bytes={start_byte}-{end_byte}` can be used to specify
what section of the file to download.
example: bytes=0-1024
in: header
required: false
schema:
type: string
- name: boxapi
description: >-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required
then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on
any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
required: false
schema:
type: string
- name: version
description: The file version to download
example: '4'
in: query
required: false
schema:
type: string
- name: access_token
description: >-
An optional access token that can be used to pre-authenticate this
request, which means that a download link can be shared with a
browser or a third party service without them needing to know how to
handle the authentication.
When using this parameter, please make sure that the access token is
sufficiently scoped down to only allow read access to that file and
no other files or folders.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
in: query
required: false
schema:
type: string
responses:
'200':
description: |-
Returns the requested file if the client has the **follow
redirects** setting enabled to automatically
follow HTTP `3xx` responses as redirects. If not, the request
will return `302` instead.
For details, see
the [download file guide](g://downloads/file#download-url).
content:
application/octet-stream:
schema:
type: string
format: binary
description: The binary content of the file
'202':
description: >-
If the file is not ready to be downloaded yet `Retry-After` header
will
be returned indicating the time in seconds after which the file will
be available for the client to download.
This response can occur when the file was uploaded immediately
before the
download request.
headers:
Retry-After:
description: The time in seconds after which to retry the download
schema:
type: integer
'302':
description: |-
If the file is available for download the response will include a
`Location` header for the file on `dl.boxcloud.com`.
The `dl.boxcloud.com` URL is not persistent and clients will need
to follow the redirect to actually download the file.
headers:
Location:
description: A pointer to the download URL
schema:
type: string
format: url
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_id_content
tags:
- Files
x-box-tag: uploads
summary: Box Upload file version
description: |-
Update a file's content. For file sizes over 50MB we recommend
using the Chunk Upload APIs.
# Request body order
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.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: if-match
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.
in: header
required: false
example: '1'
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: content-md5
required: false
schema:
type: string
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
in: header
description: |-
An optional header containing the SHA1 hash of the file to
ensure that the file was not corrupted in transit.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- attributes
- file
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
required:
- name
properties:
name:
type: string
description: >-
An optional new name for the file. If specified, the
file
will be renamed when the new version is uploaded.
example: Photo 2.0.png
content_modified_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: |-
Defines the time the file was last modified at.
If not set, the upload time will be used.
file:
type: string
format: binary
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.
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'
/files/content:
options:
operationId: options_files_content
summary: Box Preflight check before upload
tags:
- Files
x-box-tag: uploads
description: |-
Performs a check to verify that a file will be accepted by Box
before you upload the entire file.
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name for the file
example: File.mp4
size:
type: integer
format: int32
description: The size of the file in bytes
example: 1024
parent:
allOf:
- type: object
description: The parent for this item
properties:
id:
type: string
description: The ID of parent item
example: '123'
- description: The parent folder to upload the file to
responses:
'200':
description: |-
If the check passed, the response will include a session URL that
can be used to upload the file to.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadUrl'
'409':
description: |-
If the check did not pass, the response will include some details on
why it did not pass.
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_content
tags:
- Files
x-box-tag: uploads
summary: Box Upload file
description: |-
Uploads a small file to Box. For file sizes over 50MB we recommend
using the Chunk Upload APIs.
# Request body order
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.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
parameters:
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: content-md5
required: false
schema:
type: string
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
in: header
description: |-
An optional header containing the SHA1 hash of the file to
ensure that the file was not corrupted in transit.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- attributes
- file
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
required:
- name
- parent
properties:
name:
type: string
description: The name of the file
example: Photo.png
parent:
type: object
description: The parent folder to upload the file to
required:
- id
properties:
id:
type: string
example: '124132'
description: |-
The id of the parent folder. Use
`0` for the user's root folder.
content_created_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: |-
Defines the time the file was originally created at.
If not set, the upload time will be used.
content_modified_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: |-
Defines the time the file was last modified at.
If not set, the upload time will be used.
file:
type: string
format: binary
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.
responses:
'201':
description: Returns the new file object in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/Files'
'400':
description: |-
Returns an error if some of the parameters are missing or
not valid.
* `bad_request` when a parameter is missing or incorrect.
* `item_name_too_long` when the folder name is too long.
* `item_name_invalid` when the folder name contains
non-valid characters.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returns an error if the parent folder
does not exist or if the user
is not authorized to access the parent folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: |-
Returns an error if the file already exists,
or the account has run out of disk space.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/upload_sessions:
post:
operationId: post_files_upload_sessions
summary: Box Create upload session
tags:
- Files
x-box-tag: chunked_uploads
description: Creates an upload session for a new file.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
requestBody:
content:
application/json:
schema:
type: object
required:
- folder_id
- file_size
- file_name
properties:
folder_id:
description: The ID of the folder to upload the new file to.
type: string
example: '0'
file_size:
description: The total number of bytes of the file to be uploaded
example: 104857600
type: integer
format: int64
file_name:
description: The name of new file
example: Project.mov
type: string
responses:
'201':
description: Returns a new upload session.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadSession'
'400':
description: |-
Returns an error if some of the parameters are missing or
not valid.
* `missing_destination`: No `folder_id` was provided
* `invalid_folder_id`: `folder_id` is not valid
* `item_name_invalid`: `file_name` is not valid
* `missing_file_size`: `file_size` was not provided
* `invalid_file_size`: `file_size` was not a valid number
* `file_size_too_small`: `file_size` is below minimum file size for
uploads via this API
* `missing_file_name`: `file_name` was not provided
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
Returns an error if the operation is not allowed for some reason.
* `storage_limit_exceeded`: Account storage limit reached
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returns an error if the parent folder could not be found, or
the authenticated user does not have access to it.
* `invalid_parameter`: The `folder_id` value represents a
folder that the user does not have access to, or does not
exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: |-
Returns an error if the file already exists,
or the account has run out of disk space.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/upload_sessions:
post:
operationId: post_files_id_upload_sessions
summary: Box Create upload session for existing file
tags:
- Files
x-box-tag: chunked_uploads
description: Creates an upload session for an existing file.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- file_size
properties:
file_size:
description: The total number of bytes of the file to be uploaded
example: 104857600
type: integer
format: int64
file_name:
description: The optional new name of new file
example: Project.mov
type: string
responses:
'201':
description: Returns a new upload session.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadSession'
'409':
description: |-
Returns an error if the file already exists,
or if the account has run out of disk space.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/upload_sessions/{upload_session_id}:
get:
operationId: get_files_upload_sessions_id
summary: Box Get upload session
tags:
- Files
description: Return information about an upload session.
x-box-tag: chunked_uploads
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
parameters:
- name: upload_session_id
description: The ID of the upload session.
example: D5E3F7A
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns an upload session object.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadSession'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_upload_sessions_id
summary: Box Upload part of file
tags:
- Files
x-box-tag: chunked_uploads
description: Updates a chunk of an upload session for a file.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
parameters:
- name: upload_session_id
description: The ID of the upload session.
example: D5E3F7A
in: path
required: true
schema:
type: string
- name: digest
description: |-
The [RFC3230][1] message digest of the chunk uploaded.
Only SHA1 is supported. The SHA1 digest must be base64
encoded. The format of this header is as
`sha=BASE64_ENCODED_DIGEST`.
To get the value for the `SHA` digest, use the
openSSL command to encode the file part:
`openssl sha1 -binary | base64`
[1]: https://tools.ietf.org/html/rfc3230
example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
in: header
required: true
schema:
type: string
- name: content-range
description: |-
The byte range of the chunk.
Must not overlap with the range of a part already
uploaded this session. Each part’s size must be
exactly equal in size to the part size specified
in the upload session that you created.
One exception is the last part of the file, as this can be smaller.
When providing the value for `content-range`, remember that:
* The lower bound of each part's byte range
must be a multiple of the part size.
* The higher bound must be a multiple of the part size - 1.
example: bytes 8388608-16777215/445856194
in: header
required: true
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
description: The binary content of the file
responses:
'200':
description: Chunk has been uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadedPart'
'409':
description: |-
Returns an error if the chunk conflicts with another
chunk previously uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'412':
description: Returns an error if a precondition was not met.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'416':
description: >-
Returns an error if the content range does not match a specified
range
for the session.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_upload_sessions_id
summary: Box Remove upload session
tags:
- Files
description: |-
Abort an upload session and discard all data uploaded.
This cannot be reversed.
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
x-box-tag: chunked_uploads
parameters:
- name: upload_session_id
description: The ID of the upload session.
example: D5E3F7A
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
A blank response is returned if the session was
successfully aborted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/upload_sessions/{upload_session_id}/parts:
get:
operationId: get_files_upload_sessions_id_parts
summary: Box List parts
tags:
- Files
x-box-tag: chunked_uploads
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
description: |-
Return a list of the chunks uploaded to the upload
session so far.
parameters:
- name: upload_session_id
description: The ID of the upload session.
example: D5E3F7A
in: path
required: true
schema:
type: string
- name: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: Returns a list of parts that have been uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadParts'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/upload_sessions/{upload_session_id}/commit:
post:
operationId: post_files_upload_sessions_id_commit
summary: Box Commit upload session
tags:
- Files
x-box-tag: chunked_uploads
servers:
- url: https://upload.box.com/api/2.0
description: Server for file uploads
description: |-
Close an upload session and create a file from the
uploaded chunks.
parameters:
- name: upload_session_id
description: The ID of the upload session.
example: D5E3F7A
in: path
required: true
schema:
type: string
- name: digest
description: |-
The [RFC3230][1] message digest of the whole file.
Only SHA1 is supported. The SHA1 digest must be Base64
encoded. The format of this header is as
`sha=BASE64_ENCODED_DIGEST`.
[1]: https://tools.ietf.org/html/rfc3230
in: header
example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
required: true
schema:
type: string
- name: if-match
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.
in: header
required: false
example: '1'
schema:
type: string
- name: if-none-match
description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
in: header
required: false
example: '1'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- parts
properties:
parts:
type: array
description: The list details for the uploaded parts
items:
$ref: '#/components/schemas/UploadPart'
responses:
'201':
description: Returns the file object in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/Files'
'202':
description: |-
Returns when all chunks have been uploaded but not yet processed.
Inspect the upload session to get more information about the
progress of processing the chunks, then retry committing the file
when all chunks have processed.
headers:
Retry-After:
description: |-
Indicates the number of seconds the client should wait before
attempting their commit request again.
schema:
type: integer
'409':
description: |-
Returns an error if there is already a file with the same name
in the target folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'412':
description: >-
Returns an error if the `If-Match` or `If-None-Match` conditions
fail.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/copy:
post:
operationId: post_files_id_copy
summary: Box Copy file
description: Creates a copy of a file.
tags:
- Files
x-box-tag: files
x-box-enable-explorer: true
x-box-sanitized: true
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- parent
nullable: false
properties:
name:
type: string
description: >-
An optional new name for the copied file.
There are some restrictions to the file name. Names
containing
non-printable ASCII characters, forward and backward slashes
(`/`, `\`), and protected names like `.` and `..` are
automatically sanitized by removing the non-allowed
characters.
example: FileCopy.txt
maxLength: 255
version:
type: string
description: An optional ID of the specific file version to copy.
example: '0'
parent:
type: object
description: The destination folder to copy the file to.
required:
- id
properties:
id:
type: string
description: The ID of folder to copy the file to.
example: '0'
responses:
'201':
description: |-
Returns a new file object representing the copied file.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
'304':
description: |-
Returns an empty response when the `If-None-Match` header matches
the current `etag` value of the file. This indicates that the file
has not changed since it was last requested.
'400':
description: |-
Returns an error if some of the parameters are missing or
not valid.
* `bad_request` when a parameter is missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
Returns an error when the user does not have the
right permissions to create the copy a file.
* `forbidden_by_policy`: Returned if copying a file is
forbidden due to information barrier restrictions.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returns an error if either the source file or the destination
folder could not be found, or the authenticated user does not
have access to either.
* `not_found` when the authenticated user does not have access
to the source file or the destination folder
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
* `operation_blocked_temporary`: Returned if either of the
destination
or source folders is locked due to another move, copy, delete or
restore operation in process.
The operation can be retried at a later point.
* `item_name_in_use` when a folder with the same name already
exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/thumbnail.{extension}:
get:
operationId: get_files_id_thumbnail_id
summary: Box Get file thumbnail
description: >-
Retrieves a thumbnail, or smaller image representation, of a file.
Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in
the `.png` format and sizes of `32x32`, `160x160`, and `320x320`
can be returned in the `.jpg` format.
Thumbnails can be generated for the image and video file formats listed
[found on our community site][1].
[1]:
https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327
tags:
- Files
x-box-tag: files
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: extension
description: The file format for the thumbnail
in: path
required: true
example: png
schema:
type: string
enum:
- png
- jpg
- name: min_height
description: The minimum height of the thumbnail
in: query
example: 32
schema:
type: integer
minimum: 32
maximum: 320
- name: min_width
description: The minimum width of the thumbnail
in: query
example: 32
schema:
type: integer
minimum: 32
maximum: 320
- name: max_height
description: The maximum height of the thumbnail
in: query
required: false
example: 320
schema:
type: integer
minimum: 32
maximum: 320
- name: max_width
description: The maximum width of the thumbnail
in: query
required: false
example: 320
schema:
type: integer
minimum: 32
maximum: 320
responses:
'200':
description: |-
When a thumbnail can be created the thumbnail data will be
returned in the body of the response.
content:
image/png:
schema:
type: string
format: binary
description: The thumbnail
image/jpg:
schema:
type: string
format: binary
description: The thumbnail
'202':
description: >-
Sometimes generating a thumbnail can take a few seconds. In these
situations the API returns a `Location`-header pointing to a
placeholder graphic for this file type.
The placeholder graphic can be used in a user interface until the
thumbnail generation has completed. The `Retry-After`-header
indicates
when to the thumbnail will be ready. At that time, retry this
endpoint
to retrieve the thumbnail.
headers:
Retry-After:
description: |-
The time in seconds after which the thumbnail will be available.
Your application only attempt to get the thumbnail again after
this time.
schema:
type: integer
format: int64
Location:
description: |-
A pointer to a placeholder graphic that can be used until the
thumbnail has been generated.
schema:
type: string
format: url
'302':
description: |-
Returns an error when Box is not able to create a thumbnail for this
file type.
Instead, a `Location`-header pointing to a placeholder graphic for
this file type will be returned.
headers:
Location:
description: |-
A pointer to a placeholder graphic that can be used for this
file type.
schema:
type: string
format: url
'400':
description: |-
Returns an error if some of the parameters are missing or
not valid.
* `requested_preview_unavailable` - an incorrect dimension was
requested. This will happen if the dimension requested is
larger or smaller than the available file sizes for the thumbnail
format, or when when any of the size constraints contradict
each other.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file, or for additional reasons.
* `preview_cannot_be_generated` - Box does not support thumbnails
for this type of file
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/collaborations:
get:
operationId: get_files_id_collaborations
summary: Box List file collaborations
description: |-
Retrieves a list of pending and active collaborations for a
file. This returns all the users that have access to the file
or have been invited to the file.
tags:
- Files
x-box-tag: list_collaborations
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
responses:
'200':
description: >-
Returns a collection of collaboration objects. If there are no
collaborations on this file an empty collection will be returned.
This list includes pending collaborations, for which the `status`
is set to `pending`, indicating invitations that have been sent but
not
yet accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaborations'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/comments:
get:
operationId: get_files_id_comments
summary: Box List file comments
description: Retrieves a list of comments for a file.
tags:
- Files
x-box-tag: comments
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
- name: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
responses:
'200':
description: |-
Returns a collection of comment objects. If there are no
comments on this file an empty collection will be returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Comments'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/tasks:
get:
operationId: get_files_id_tasks
summary: Box List tasks on file
description: |-
Retrieves a list of all the tasks for a file. This
endpoint does not support pagination.
tags:
- Files
x-box-tag: tasks
x-box-sanitized: true
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'200':
description: |-
Returns a list of tasks on a file.
If there are no tasks on this file an empty collection is returned
instead.
content:
application/json:
schema:
$ref: '#/components/schemas/Tasks'
'404':
description: >-
Returns an error when the file could not be found or the user does
not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returns an error when the `file_id` was not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: >-
Returns an error when an attempt was made to retrieve tasks for the
file
with ID `0`.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/trash:
get:
operationId: get_files_id_trash
summary: Box Get trashed file
tags:
- Files
x-box-tag: trashed_files
description: |-
Retrieves a file that has been moved to the trash.
Please note that only if the file itself has been moved to the
trash can it be retrieved with this API call. If instead one of
its parent folders was moved to the trash, only that folder
can be inspected using the
[`GET /folders/:id/trash`](e://get_folders_id_trash) API.
To list all items that have been moved to the trash, please
use the [`GET /folders/trash/items`](e://get-folders-trash-items/)
API.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: |-
Returns the file that was trashed,
including information about when the it
was moved to the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/TrashFile'
'404':
description: |-
Returns an error if the file can not be found directly
in the trash.
Please note that a `HTTP 404` is also returned if any of
the file's parent folders have been moved to the trash.
In that case, only that parent folder can be inspected using
the [`GET /folders/:id/trash`](e://get_folders_id_trash) API.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_trash
summary: Box Permanently remove file
tags:
- Files
x-box-tag: trashed_files
description: |-
Permanently deletes a file that is in the trash.
This action cannot be undone.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the file was
permanently deleted.
'404':
description: Returns an error if the file is not in the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/versions:
get:
operationId: get_files_id_versions
summary: Box List all file versions
tags:
- Files
x-box-tag: file_versions
description: >-
Retrieve a list of the past versions for a file.
Versions are only tracked by Box users with premium accounts. To fetch
the ID
of the current version of a file, use the `GET /file/:id` API.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
- name: offset
description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
responses:
'200':
description: Returns an array of past versions for this file.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersions'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/versions/{file_version_id}:
get:
operationId: get_files_id_versions_id
summary: Box Get file version
tags:
- Files
x-box-tag: file_versions
description: |-
Retrieve a specific version of a file.
Versions are only tracked for Box users with premium accounts.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: file_version_id
description: The ID of the file version
in: path
required: true
example: '1234'
schema:
type: string
responses:
'200':
description: |-
Returns a specific version of a file.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersion--Full'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_versions_id
summary: Box Remove file version
tags:
- Files
x-box-tag: file_versions
description: |-
Move a file version to the trash.
Versions are only tracked for Box users with premium accounts.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: file_version_id
description: The ID of the file version
in: path
required: true
example: '1234'
schema:
type: string
- name: if-match
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.
in: header
required: false
example: '1'
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the file has been successfully
deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id_versions_id
summary: Box Restore file version
tags:
- Files
x-box-tag: file_versions
description: |-
Restores a specific version of a file after it was deleted.
Don't use this endpoint to restore Box Notes,
as it works with file formats such as PDF, DOC,
PPTX or similar.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: file_version_id
description: The ID of the file version
in: path
required: true
example: '1234'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: |-
The file version to be
restored
properties:
trashed_at:
type: string
description: |-
Set this to `null` to clear
the date and restore the file.
example: 'null'
responses:
'200':
description: Returns a restored file version object.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersion--Full'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/versions/current:
post:
operationId: post_files_id_versions_current
summary: Box Promote file version
tags:
- Files
x-box-tag: file_versions
description: |-
Promote a specific version of a file.
If previous versions exist, this method can be used to
promote one of the older versions to the top of the version history.
This creates a new copy of the old version and puts it at the
top of the versions history. The file will have the exact same contents
as the older version, with the the same hash digest, `etag`, and
name as the original.
Other properties such as comments do not get updated to their
former values.
Don't use this endpoint to restore Box Notes,
as it works with file formats such as PDF, DOC,
PPTX or similar.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
description: The file version to promote
properties:
id:
type: string
description: The file version ID
example: '11446498'
type:
type: string
description: The type to promote
example: file_version
enum:
- file_version
responses:
'201':
description: Returns a newly created file version object.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersion--Full'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/metadata:
get:
operationId: get_files_id_metadata
summary: Box List metadata instances on file
tags:
- Files
x-box-tag: file_metadata
x-box-sanitized: true
description: Retrieves all metadata for a given file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'200':
description: >-
Returns all the metadata associated with a file.
This API does not support pagination and will therefore always
return
all of the metadata associated to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/Metadatas'
'403':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Returned when the user does not have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo:
get:
operationId: get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
summary: Box Get classification on file
tags:
- Files
x-box-tag: file_classifications
x-box-sanitized: true
description: |-
Retrieves the classification metadata instance that
has been applied to a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'201':
description: |-
Returns an instance of the `securityClassification` metadata
template, which contains a `Box__Security__Classification__Key`
field that lists all the classifications available to this
enterprise.
content:
application/json:
schema:
$ref: '#/components/schemas/Classification'
'403':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returned if the metadata template specified
was not applied to this file or the user does not have access to the
file.
* `instance_not_found` - The metadata template was not applied to
the
file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned when the method was not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
summary: Box Add classification to file
tags:
- Files
x-box-tag: file_classifications
x-box-sanitized: true
description: |-
Adds a classification to a file by specifying the label of the
classification to add.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
Box__Security__Classification__Key:
type: string
description: >-
The name of the classification to apply to this file.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification
template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
responses:
'201':
description: |-
Returns the classification template instance
that was applied to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/Classification'
'400':
description: >-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for
a for
a field that either does not exist, or for which the value or type
does
not match the expected field type. An example might be an unknown
option
for an `enum` or `multiSelect` field.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the file or metadata template was not found.
* `not_found` - The file could not be found, or the user does not
have
access to the file.
* `instance_tuple_not_found` - The metadata template was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
Returns an error when an instance of this metadata template is
already
present on the file.
* `tuple_already_exists` - An instance of them metadata template
already
exists on the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
summary: Box Update classification on file
tags:
- Files
x-box-tag: file_classifications
x-box-sanitized: true
description: >-
Updates a classification on a file.
The classification can only be updated if a classification has already
been
applied to the file before. When editing classifications, only values
are
defined for the enterprise will be accepted.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
required:
- items
description: |-
A list containing the one change to make, to
update the classification label.
type: array
items:
type: object
description: |-
The operation to perform on the classification
metadata template instance. In this case, it use
used to replace the value stored for the
`Box__Security__Classification__Key` field with a new
value.
required:
- op
- path
- value
properties:
op:
type: string
example: replace
description: '`replace`'
enum:
- replace
path:
type: string
example: /Box__Security__Classification__Key
description: |-
Defines classifications
available in the enterprise.
enum:
- /Box__Security__Classification__Key
value:
type: string
description: >-
The name of the classification to apply to this file.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification
template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
responses:
'200':
description: Returns the updated classification metadata template instance.
content:
application/json:
schema:
$ref: '#/components/schemas/Classification'
'400':
description: >-
Returns an error when the request body is not valid.
* `bad_request` - The request body format is not an array of valid
JSON
Patch operations.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: >-
Returns an error in some edge cases when the request body is not a
valid
array of JSON Patch items.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
summary: Box Remove classification from file
tags:
- Files
x-box-tag: file_classifications
x-box-sanitized: true
description: |-
Removes any classifications from a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the classification is
successfully deleted.
'400':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the file does not have any classification
applied
to it, or when the user does not have access to the
file.
* `instance_not_found` - An instance of the classification metadata
template with the was not found on this file.
* `not_found` - The file was not found, or the user does not have
access
to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned when the method was not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/metadata/{scope}/{template_key}:
get:
operationId: get_files_id_metadata_id_id
summary: Box Get metadata instance on file
tags:
- Files
x-box-tag: file_metadata
x-box-sanitized: true
description: |-
Retrieves the instance of a metadata template that has been applied to a
file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
responses:
'201':
description: |-
An instance of the metadata template that includes
additional "key:value" pairs defined by the user or
an application.
content:
application/json:
schema:
$ref: '#/components/schemas/Metadata--Full'
'403':
description: Returned when the request parameters are not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returned if the metadata template specified
was not applied to this file or the user does not have access to the
file.
* `instance_not_found` - The metadata template was not applied to
the
file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned when the method was not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_id_metadata_id_id
summary: Box Create metadata instance on file
tags:
- Files
x-box-tag: file_metadata
x-box-sanitized: true
description: >-
Applies an instance of a metadata template to a file.
In most cases only values that are present in the metadata template
will be accepted, except for the `global.properties` template which
accepts
any key-value pair.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
example:
name: Aaron Levie
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
responses:
'201':
description: |-
Returns the instance of the template that was applied to the file,
including the data that was applied to the template.
content:
application/json:
schema:
$ref: '#/components/schemas/Metadata--Full'
'400':
description: >-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for
a for
a field that either does not exist, or for which the value or type
does
not match the expected field type. An example might be an unknown
option
for an `enum` or `multiSelect` field.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the file or metadata template was not found.
* `not_found` - The file could not be found, or the user does not
have
access to the file.
* `instance_tuple_not_found` - The metadata template was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
Returns an error when an instance of this metadata template is
already
present on the file.
* `tuple_already_exists` - An instance of them metadata template
already
exists on the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id_metadata_id_id
summary: Box Update metadata instance on file
tags:
- Files
x-box-tag: file_metadata
x-box-sanitized: true
description: >-
Updates a piece of metadata on a file.
The metadata instance can only be updated if the template has already
been
applied to the file before. When editing metadata, only values that
match
the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be
changed.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
instance.
The changes are represented as a JSON array of
operation objects.
type: array
items:
title: A metadata instance update operation
description: >-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation
for a
change to make to the metadata instance.
type: object
properties:
op:
type: string
example: add
enum:
- add
- replace
- remove
- test
- move
- copy
description: >-
The type of change to perform on the template. Some
of these are hazardous as they will change existing
templates.
path:
type: string
example: /currentState
description: >-
The location in the metadata JSON object
to apply the changes to, in the format of a
[JSON-Pointer](https://tools.ietf.org/html/rfc6901).
The path must always be prefixed with a `/` to represent
the root
of the template. The characters `~` and `/` are reserved
characters and must be escaped in the key.
value:
type: string
example: reviewed
description: >-
The value to be set or tested.
Required for `add`, `replace`, and `test` operations. For
`add`,
if the value exists already the previous value will be
overwritten
by the new value. For `replace`, the value must exist
before
replacing.
For `test`, the existing value at the `path` location must
match
the specified value.
from:
type: string
example: /nextState
description: >-
The location in the metadata JSON object to move or copy a
value
from. Required for `move` or `copy` operations and must be
in the
format of a
[JSON-Pointer](https://tools.ietf.org/html/rfc6901).
responses:
'200':
description: |-
Returns the updated metadata template instance, with the
custom template data included.
content:
application/json:
schema:
$ref: '#/components/schemas/Metadata--Full'
'400':
description: >-
Returns an error when the request body is not valid.
* `bad_request` - The request body format is not an array of valid
JSON
Patch objects.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'500':
description: >-
Returns an error in some edge cases when the request body is not a
valid
array of JSON Patch items.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_metadata_id_id
summary: Box Remove metadata instance from file
tags:
- Files
x-box-tag: file_metadata
x-box-sanitized: true
description: Deletes a piece of file metadata.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: scope
description: The scope of the metadata template
example: global
in: path
required: true
schema:
type: string
enum:
- global
- enterprise
- name: template_key
description: The name of the metadata template
example: properties
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the metadata is
successfully deleted.
'400':
description: >-
Returned when the request parameters are not valid. This may happen
of the
`scope` is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the file does not have an instance of the
metadata
template applied to it, or when the user does not have access to the
file.
* `instance_not_found` - An instance of the metadata template with
the
given `scope` and `templateKey` was not found on this file.
* `not_found` - The file was not found, or the user does not have
access
to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned when the method was not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/metadata/global/boxSkillsCards:
get:
operationId: get_files_id_metadata_global_boxSkillsCards
summary: List Box Skill cards on file
tags:
- Files
x-box-tag: skills
description: List the Box Skills metadata cards that are attached to a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'200':
description: >-
Returns all the metadata associated with a file.
This API does not support pagination and will therefore always
return
all of the metadata associated to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/SkillCardsMetadata'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_files_id_metadata_global_boxSkillsCards
summary: Create Box Skill cards on file
tags:
- Files
x-box-tag: skills
description: Applies one or more Box Skills metadata cards to a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- cards
properties:
cards:
type: array
description: A list of Box Skill cards to apply to this file.
items:
oneOf:
- $ref: '#/components/schemas/KeywordSkillCard'
- $ref: '#/components/schemas/TimelineSkillCard'
- $ref: '#/components/schemas/TranscriptSkillCard'
- $ref: '#/components/schemas/StatusSkillCard'
responses:
'201':
description: |-
Returns the instance of the template that was applied to the file,
including the data that was applied to the template.
content:
application/json:
schema:
$ref: '#/components/schemas/SkillCardsMetadata'
'400':
description: >-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for
a for
a field that either does not exist, or for which the value or type
does
not match the expected field type. An example might be an unknown
option
for an `enum` or `multiSelect` field.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when the file or metadata template was not found.
* `not_found` - The file could not be found, or the user does not
have
access to the file.
* `instance_tuple_not_found` - The metadata template was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
Returns an error when an instance of this metadata template is
already
present on the file.
* `tuple_already_exists` - An instance of them metadata template
already
exists on the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id_metadata_global_boxSkillsCards
summary: Update Box Skill cards on file
tags:
- Files
x-box-tag: skills
description: Updates one or more Box Skills metadata cards to a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
template.
The changes are represented as a JSON array of
operation objects.
type: array
items:
type: object
description: An operation that replaces an existing card.
properties:
op:
type: string
description: '`replace`'
example: replace
enum:
- replace
path:
type: string
description: >-
The JSON Path that represents the card to replace. In most
cases
this will be in the format `/cards/{index}` where `index`
is the
zero-indexed position of the card in the list of cards.
example: /cards/0
value:
allOf:
- oneOf:
- $ref: '#/components/schemas/KeywordSkillCard'
- $ref: '#/components/schemas/TimelineSkillCard'
- $ref: '#/components/schemas/TranscriptSkillCard'
- $ref: '#/components/schemas/StatusSkillCard'
- description: |-
The card to insert into the list of cards at the
position defined by `path`.
responses:
'200':
description: |-
Returns the updated metadata template, with the
custom template data included.
content:
application/json:
schema:
$ref: '#/components/schemas/SkillCardsMetadata'
'404':
description: The requested file could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_metadata_global_boxSkillsCards
summary: Remove Box Skill cards from file
tags:
- Files
x-box-tag: skills
x-box-sanitized: true
description: Removes any Box Skills cards metadata from a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
Returns an empty response when the cards are
successfully deleted.
'404':
description: >-
Returns an error when the file does not have an instance of the Box
Skill
cards applied to it, or when the user does not have access to the
file.
* `instance_not_found` - An instance of the metadata template for
Box
Skill cards was not found on this file.
* `not_found` - The file was not found, or the user does not have
access
to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned when the method was not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}/watermark:
get:
operationId: get_files_id_watermark
summary: Box Get watermark on file
tags:
- Files
x-box-tag: file_watermarks
description: Retrieve the watermark for a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'200':
description: |-
Returns an object containing information about the
watermark associated for to this file.
content:
application/json:
schema:
$ref: '#/components/schemas/Watermark'
'404':
description: Returns an error if the file does not have a watermark applied.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_files_id_watermark
summary: Box Apply watermark to file
tags:
- Files
x-box-tag: file_watermarks
description: Applies or update a watermark on a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- watermark
properties:
watermark:
type: object
description: The watermark to imprint on the file
required:
- imprint
properties:
imprint:
type: string
example: default
description: |-
The type of watermark to apply.
Currently only supports one option.
enum:
- default
responses:
'200':
description: |-
Returns an updated watermark if a watermark already
existed on this file.
content:
application/json:
schema:
$ref: '#/components/schemas/Watermark'
'201':
description: |-
Returns a new watermark if no watermark existed on
this file yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Watermark'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_files_id_watermark
summary: Box Remove watermark from file
tags:
- Files
x-box-tag: file_watermarks
description: Removes the watermark from a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
responses:
'204':
description: Removes the watermark and returns an empty response.
'404':
description: |-
Returns an error if the file did not have
a watermark applied to it.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}#get_shared_link:
get:
operationId: get_files_id#get_shared_link
summary: Box Get shared link for file
tags:
- Files
x-box-tag: shared_links_files
x-box-enable-explorer: true
x-box-sanitized: true
description: Gets the information for a shared link on a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
required: true
schema:
type: string
responses:
'200':
description: |-
Returns the base representation of a file with the
additional shared link information.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
examples:
default:
value:
id: '12345'
type: file
etag: '1'
shared_link:
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
download_url: >-
https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
vanity_url:
vanity_name:
effective_access: open
effective_permission: can_download
is_password_enabled: false
unshared_at: '2020-09-21T10:34:41-07:00'
download_count: 0
preview_count: 0
access: open
permissions:
can_preview: true
can_download: true
can_edit: true
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/files/{file_id}#add_shared_link:
put:
operationId: put_files_id#add_shared_link
summary: Box Add shared link to file
tags:
- Files
x-box-tag: shared_links_files
x-box-enable-explorer: true
x-box-sanitized: true
description: Adds a shared link to a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
shared_link:
description: >-
The settings for the shared link to create on the file.
Use an empty object (`{}`) to use the default settings for
shared
links.
type: object
properties:
access:
type: string
description: >-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the file (`collaborators`).
If not set, this field defaults to the access level
specified
by the enterprise admin. To create a shared link with
this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
password:
type: string
description: >-
The password required to access the shared link. Set the
password to `null` to remove it.
Passwords must now be at least eight characters
long and include a number, upper case letter, or
a non-numeric or non-alphabetic character.
A password can only be set when `access` is set to
`open`.
example: do-n8t-use-this-Password
vanity_name:
type: string
description: >-
Defines a custom vanity name to use in the shared link
URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive
content
as vanity URLs are a lot easier to guess than regular
shared
links.
minLength: 12
example: my-shared-link
unshared_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: >-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than
the
current date and time.
permissions:
type: object
properties:
can_download:
type: boolean
example: true
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
can_preview:
type: boolean
example: true
description: >-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on
folders
this also applies to any items in the folder.
can_edit:
type: boolean
example: true
description: |-
If the shared link allows for editing of files.
This can only be set when `access` is set to
`open` or `company`.
This value can only be `true` is `can_download` is
also `true`.
responses:
'200':
description: |-
Returns the base representation of a file with a new shared
link attached.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
examples:
default:
value:
id: '12345'
type: file
etag: '1'
shared_link:
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
download_url: >-
https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
vanity_url:
vanity_name:
effective_access: open
effective_permission: can_download
is_password_enabled: false
unshared_at: '2020-09-21T10:34:41-07:00'
download_count: 0
preview_count: 0
access: open
permissions:
can_preview: true
can_download: true
can_edit: true
'400':
description: Returned when there is an incorrect permission combination
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returned if the user does not have all the permissions to complete
the
update.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'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'
/files/{file_id}#update_shared_link:
put:
operationId: put_files_id#update_shared_link
summary: Box Update shared link on file
tags:
- Files
x-box-tag: shared_links_files
x-box-enable-explorer: true
x-box-sanitized: true
description: Updates a shared link on a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
shared_link:
description: The settings for the shared link to update.
type: object
properties:
access:
type: string
description: >-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level
specified
by the enterprise admin. To create a shared link with
this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
password:
type: string
description: >-
The password required to access the shared link. Set the
password to `null` to remove it.
Passwords must now be at least eight characters
long and include a number, upper case letter, or
a non-numeric or non-alphabetic character.
A password can only be set when `access` is set to
`open`.
example: do-n8t-use-this-Password
vanity_name:
type: string
description: >-
Defines a custom vanity name to use in the shared link
URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive
content
as vanity URLs are a lot easier to guess than regular
shared
links.
minLength: 12
example: my-shared-link
unshared_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: >-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than
the
current date and time.
permissions:
type: object
properties:
can_download:
type: boolean
example: true
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
can_preview:
type: boolean
example: true
description: >-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on
folders
this also applies to any items in the folder.
can_edit:
type: boolean
example: true
description: |-
If the shared link allows for editing of files.
This can only be set when `access` is set to
`open` or `company`.
This value can only be `true` is `can_download` is
also `true`.
responses:
'200':
description: |-
Returns a basic representation of the file, with the updated shared
link attached.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
examples:
default:
value:
id: '12345'
type: file
etag: '1'
shared_link:
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
download_url: >-
https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
vanity_url:
vanity_name:
effective_access: open
effective_permission: can_download
is_password_enabled: false
unshared_at: '2020-09-21T10:34:41-07:00'
download_count: 0
preview_count: 0
access: open
permissions:
can_preview: true
can_download: true
can_edit: true
'400':
description: Returned when there is an incorrect permission combination
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returned if the user does not have all the permissions to complete
the
update.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'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'
/files/{file_id}#remove_shared_link:
put:
operationId: put_files_id#remove_shared_link
summary: Box Remove shared link from file
tags:
- Files
x-box-tag: shared_links_files
x-box-enable-explorer: true
x-box-sanitized: true
description: Removes a shared link from a file.
parameters:
- name: file_id
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`.
example: '12345'
in: path
required: true
schema:
type: string
- name: fields
description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
shared_link:
description: |-
By setting this value to `null`, the shared link
is removed from the file.
type: object
example:
nullable: true
responses:
'200':
description: >-
Returns a basic representation of a file, with the shared link
removed.
content:
application/json:
schema:
$ref: '#/components/schemas/File--Full'
examples:
default:
value:
id: '12345'
type: file
etag: '1'
shared_link:
'401':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
Returned if the user does not have all the permissions to complete
the
update.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the file is not found, or the user does not
have access to the file.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `file_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'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'
/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention:
get:
operationId: get_retention_policy_assignments_id_files_under_retention
summary: Box Get files under retention
tags:
- Retention Policy Assignments
x-box-tag: retention_policy_assignments
description: >-
Returns a list of files under retention for a retention policy
assignment.
parameters:
- name: retention_policy_assignment_id
description: The ID of the retention policy assignment.
example: '1233123'
in: path
required: true
schema:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: |-
Returns a list of files under retention that are associated with the
specified retention policy assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/FilesUnderRetention'
'400':
description: >-
Returns an error if `retention_policy_assignment_id` is not
specified.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold:
get:
operationId: get_legal_hold_policy_assignments_id_files_on_hold
summary: Box List current file versions for legal hold policy assignment
tags:
- Legal Hold Policy Assignments
x-box-tag: legal_hold_policy_assignments
description: >-
Get a list of current file versions for a legal hold
assignment.
In some cases you may want to get previous file versions instead. In
these
cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold`
API instead to return any previous versions of a file for this legal
hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all
file
versions held for this policy ID. Instead, this API will only return the
latest file version held in the newly developed architecture. The `GET
/file_version_legal_holds` API can be used to fetch current and past
versions
of files held within the legacy architecture.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used
to
find a list of policy assignments for a given policy ID.
parameters:
- name: legal_hold_policy_assignment_id
description: The ID of the legal hold policy assignment
example: '753465'
in: path
required: true
schema:
type: string
- name: marker
description: >-
Defines the position marker at which to begin returning results.
This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
- name: fields
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.
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: >-
Returns the list of current file versions held under legal hold for
a
specific legal hold policy assignment.
content:
application/json:
schema:
$ref: '#/components/schemas/FileVersionLegalHolds'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
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
file 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
users to collaborate on this item, and if the user
can
update the role of a user already collaborated on
this
item.
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
existing 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
on this file
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:
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
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.
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
be `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,
this is set to an empty string.
is_package:
type: boolean
example: true
description: |-
Indicates if the file is a package. Packages are commonly used
by 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,
providing a list of resources (files, folders, etc)
and 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
from the file ID and access tokens specified in this
object.
- 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:
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
via the direct shared link or a shared link
to 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
when 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
authenticated 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`
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'
- 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:
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
the 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.
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.
info:
type: object
description: >-
An object containing the URL that can be used to
fetch more info
on 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
representation. Make sure to make an
authenticated API call
to this endpoint.
properties:
type: object
description: >-
An object containing the size and type of this
presentation.
properties:
dimensions:
type: string
format: x
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
pages.
thumb:
type: boolean
example: true
description: >-
Indicates if the representation can be used as
a thumbnail of
the 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.
* `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.
- 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:
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
classification label in a user-interface. Colors are
defined by the admin
or 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
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:
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
when sharing this file.
items:
type: string
enum:
- can_preview
- can_download
- can_edit
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
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.
example: Method Not Allowed
type: string
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
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
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
Files:
title: Files
type: object
x-box-resource-id: files
x-box-tag: files
description: A list of files
properties:
total_count:
description: The number of files.
example: 1
type: integer
format: int64
entries:
type: array
description: A list of files
items:
$ref: '#/components/schemas/File--Full'
UploadUrl:
title: Upload URL
type: object
x-box-resource-id: upload_url
x-box-tag: uploads
description: The details for the upload session for the file.
properties:
upload_url:
type: string
example: >-
https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234
description: |-
A URL for an upload session that can be used to upload
the file.
upload_token:
type: string
example: Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP
description: An optional access token to use to upload the file
UploadSession:
title: Upload session
type: object
x-box-resource-id: upload_session
description: An upload session for chunk uploading a file.
x-box-tag: chunked_uploads
properties:
id:
type: string
description: The unique identifier for this session
example: F971964745A5CD0C001BBE4E58196BFD
type:
type: string
description: '`upload_session`'
example: upload_session
enum:
- upload_session
session_expires_at:
description: The date and time when this session expires.
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
part_size:
type: integer
format: int64
example: 1024
description: |-
The size in bytes that must be used for all parts of of the
upload.
Only the last part is allowed to be of a smaller size.
total_parts:
type: integer
format: int32
example: 1000
description: |-
The total number of parts expected in this upload session,
as determined by the file size and part size.
num_parts_processed:
type: integer
format: int32
example: 455
description: |-
The number of parts that have been uploaded and processed
by the server. This starts at `0`.
When committing a file files, inspecting this property can
provide insight if all parts have been uploaded correctly.
session_endpoints:
allOf:
- title: Session endpoints
description: A list of endpoints for a chunked upload session.
type: object
properties:
upload_part:
type: string
description: The URL to upload parts to
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
commit:
type: string
description: The URL used to commit the file
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit
abort:
type: string
description: The URL for used to abort the session.
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
list_parts:
type: string
description: The URL users to list all parts.
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts
status:
type: string
description: The URL used to get the status of the upload.
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
log_event:
type: string
description: The URL used to get the upload log from.
example: >-
https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log
- description: A list of endpoints for this session.
UploadedPart:
title: Uploaded part
type: object
x-box-resource-id: uploaded_part
description: |-
A chunk of a file uploaded as part of
an upload session, as returned by some endpoints.
x-box-tag: chunked_uploads
properties:
part:
$ref: '#/components/schemas/UploadPart'
UploadParts:
title: Upload parts
type: object
x-box-resource-id: upload_parts
x-box-tag: chunked_uploads
description: |-
A list of uploaded chunks for an upload
session.
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: |-
A list of uploaded chunks for an upload
session
items:
$ref: '#/components/schemas/UploadPart'
Collaborations:
title: Collaborations
type: object
x-box-resource-id: collaborations
x-box-tag: user_collaborations
description: A list of collaborations
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: A list of collaborations
items:
$ref: '#/components/schemas/Collaboration'
Comments:
title: Comments
type: object
x-box-resource-id: comments
x-box-tag: comments
description: A list of comments
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: A list of comments
items:
$ref: '#/components/schemas/Comment--Full'
Tasks:
title: Tasks
type: object
x-box-resource-id: tasks
x-box-tag: tasks
description: A list of tasks
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
example: 5000
type: integer
format: int64
entries:
type: array
description: A list of tasks
items:
$ref: '#/components/schemas/Task'
TrashFile:
title: Trashed File
type: object
x-box-resource-id: trash_file
x-box-tag: trashed_files
description: Represents a trashed file.
required:
- id
- type
- sequence_id
- sha1
- description
- size
- path_collection
- created_at
- modified_at
- modified_by
- owned_by
- item_status
properties:
id:
type: string
nullable: false
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`.
example: '123456789'
etag:
type: string
example: '1'
nullable: true
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:
type: string
description: '`file`'
example: file
enum:
- file
nullable: false
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:
type: string
description: The name of the file
example: Contract.pdf
sha1:
type: string
format: digest
nullable: false
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
description: |-
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:
allOf:
- $ref: '#/components/schemas/FileVersion--Mini'
- description: The information about the current version of the file.
description:
type: string
nullable: false
description: The optional description of this file
maxLength: 256
example: Contract for Q1 renewal
size:
type: integer
nullable: false
description: |-
The file size in bytes. Be careful parsing this integer as it can
get very large and cause an integer overflow.
example: 629644
path_collection:
allOf:
- title: Path collection (Trash)
description: A list of parent folders for an item in the trash.
type: object
required:
- total_count
- entries
properties:
total_count:
description: The number of folders in this list.
example: 1
type: integer
format: int64
nullable: false
entries:
description: Array of folders for this item's path collection
type: array
items:
type: object
description: The parent folder for this item
properties:
type:
type: string
description: '`folder`'
enum:
- folder
example: folder
id:
type: string
description: The unique identifier that represent a folder.
example: '123456789'
sequence_id:
type: string
nullable: true
example:
description: This field is null for the Trash folder
etag:
type: string
nullable: true
example:
description: This field is null for the Trash folder
name:
type: string
description: The name of the Trash folder.
example: Trash
nullable: false
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
created_at:
type: string
format: date-time
nullable: false
description: The date and time when the file was created on Box.
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
nullable: false
description: The date and time when the file was last updated on Box.
example: '2012-12-12T10:53:43-08:00'
trashed_at:
type: string
format: date-time
nullable: true
description: The time at which this file was put in the trash.
example: '2012-12-12T10:53:43-08:00'
purged_at:
type: string
format: date-time
nullable: true
description: |-
The time at which this file is expected to be purged
from the trash.
example: '2012-12-12T10:53:43-08:00'
content_created_at:
type: string
format: date-time
nullable: true
description: |-
The date and time at which this file was originally
created, which might be before it was uploaded to Box.
example: '2012-12-12T10:53:43-08:00'
content_modified_at:
type: string
format: date-time
nullable: true
description: |-
The date and time at which this file was last updated,
which might be before it was uploaded to Box.
example: '2012-12-12T10:53:43-08:00'
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:
type: string
description: |-
The shared link for this file. This will
be `null` if a file has been trashed, since the link will no longer
be active.
example:
nullable: true
parent:
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: The folder that this file is located within.
- nullable: true
item_status:
type: string
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.
enum:
- active
- trashed
- deleted
nullable: false
example: trashed
FileVersions:
title: File versions
type: object
x-box-resource-id: file_versions
x-box-tag: file_versions
description: A list of file versions
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: A list of file versions
items:
$ref: '#/components/schemas/FileVersion--Full'
FileVersion--Full:
title: File version (Full)
type: object
x-box-resource-id: file_version--full
x-box-variant: full
description: |-
A full representation of a file version, as can be returned from any
file version API endpoints by default
allOf:
- $ref: '#/components/schemas/FileVersion'
- properties:
version_number:
type: string
example: '1'
description: The version number of this file version
Metadatas:
title: Metadata instances
type: object
x-box-resource-id: metadatas
x-box-tag: file_metadata
description: A list of metadata instances that have been applied to a file or folder.
properties:
entries:
type: array
description: A list of metadata instances, as applied to this file or folder.
items:
$ref: '#/components/schemas/Metadata'
limit:
description: The limit that was used for this page of results.
example: 100
type: integer
Classification:
title: Classification
type: object
x-box-resource-id: classification
x-box-tag: classifications
description: |-
An instance of the classification metadata template, containing
the classification applied to the file or folder.
To get more details about the classification applied to an item,
request the classification metadata template.
properties:
Box__Security__Classification__Key:
type: string
example: Sensitive
description: The name of the classification applied to the item.
$parent:
type: string
example: folder_59449484661,
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}`.
$template:
type: string
example: securityClassification-6VMVochwUWo
description: '`securityClassification-6VMVochwUWo`'
enum:
- securityClassification-6VMVochwUWo
$scope:
type: string
example: enterprise_27335
description: |-
The scope of the enterprise that this classification has been
applied for.
This will be in the format `enterprise_{enterprise_id}`.
$version:
type: integer
example: 1
description: |-
The version of the metadata instance. This version starts at 0 and
increases every time a classification is updated.
$type:
type: string
example: >-
securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8
description: |-
The unique ID of this classification instance. This will be include
the name of the classification template and a unique ID.
$typeVersion:
type: number
example: 5
description: >-
The version of the metadata template. This version starts at 0 and
increases every time the template is updated. This is mostly for
internal
use.
$canEdit:
type: boolean
example: true
description: Whether an end user can change the classification.
Metadata--Full:
title: Metadata instance (Full)
type: object
x-box-resource-id: metadata--full
x-box-variant: full
description: |-
An instance of a metadata template, which has been applied to a file or
folder.
allOf:
- $ref: '#/components/schemas/Metadata'
- properties:
$canEdit:
type: boolean
example: true
description: Whether the user can edit this metadata instance.
$id:
type: string
format: uuid
example: 01234500-12f1-1234-aa12-b1d234cb567e
maxLength: 36
description: A UUID to identify the metadata instance.
$type:
type: string
example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
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.
$typeVersion:
type: integer
example: 2
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.
- 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
SkillCardsMetadata:
title: Skills metadata instance
type: object
x-box-resource-id: skill_cards_metadata
x-box-tag: skills
description: The metadata assigned to a using for Box skills.
properties:
$canEdit:
type: boolean
example: true
description: Whether the user can edit this metadata
$id:
type: string
format: uuid
example: 01234500-12f1-1234-aa12-b1d234cb567e
maxLength: 36
description: A UUID to identify the metadata object
$parent:
type: string
example: folder_59449484661,
description: An ID for the parent folder
$scope:
type: string
example: enterprise_27335
description: |-
An ID for the scope in which this template
has been applied
$template:
type: string
example: properties
description: The name of the template
$type:
type: string
example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
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.
$typeVersion:
type: integer
example: 2
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.
$version:
type: integer
example: 1
description: >-
The version of the metadata object. Starts at 0 and increases every
time
a user-defined property is modified.
cards:
type: array
description: A list of Box Skill cards that have been applied to this file.
items:
oneOf:
- $ref: '#/components/schemas/KeywordSkillCard'
- $ref: '#/components/schemas/TimelineSkillCard'
- $ref: '#/components/schemas/TranscriptSkillCard'
- $ref: '#/components/schemas/StatusSkillCard'
Watermark:
title: Watermark
type: object
x-box-resource-id: watermark
x-box-tag: file_watermarks
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 a file's content
properties:
watermark:
type: object
properties:
created_at:
type: string
format: date-time
description: When this watermark was created
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
description: When this task was modified
example: '2012-12-12T10:53:43-08:00'
FilesUnderRetention:
title: Files under retention
type: object
x-box-resource-id: files_under_retention
x-box-tag: retention_policy_assignments
description: A list of files under retention.
allOf:
- type: object
description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of files
items:
$ref: '#/components/schemas/File--Mini'
FileVersionLegalHolds:
title: File version legal holds
type: object
x-box-resource-id: file_version_legal_holds
x-box-tag: file_version_legal_holds
description: A list of file version legal holds.
allOf:
- type: object
description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of file version legal holds
items:
$ref: '#/components/schemas/FileVersionLegalHold'
tags:
- name: Files
- name: Legal Hold Policy Assignments
- name: Retention Policy Assignments