openapi: 3.1.0
info:
title: Box Authorize Authorization Files API
description: Needs a description.
tags:
- name: Files
description: 'Files, together with Folders,
are at the core of the Box API.
Files can be uploaded and downloaded,
as well as hold important metadata
information about the content.'
x-box-tag: files
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\nincorrect media type.\n\n* `unsupported_media_type` when requesting an `expiring_embed_link`\n 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'
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'
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'
/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\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n"
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.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n"
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\nnot valid.\n* `bad_request` when a parameter is missing or incorrect.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n 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/{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\nfolder could not be found, or the authenticated user does not\nhave access to either.\n\n* `not_found` when the authenticated user does not have access\n 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\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use` when a folder with the same name already\n 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\nnot valid.\n\n* `requested_preview_unavailable` - an incorrect dimension was\n requested. This will happen if the dimension requested is\n larger or smaller than the available file sizes for the thumbnail\n format, or when when any of the size constraints contradict\n 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\nhave access to the file, or for additional reasons.\n\n* `preview_cannot_be_generated` - Box does not support thumbnails\n 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}/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\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n"
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.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n"
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/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\nnot valid.\n\n* `missing_destination`: No `folder_id` was provided\n* `invalid_folder_id`: `folder_id` is not valid\n* `item_name_invalid`: `file_name` is not valid\n* `missing_file_size`: `file_size` was not provided\n* `invalid_file_size`: `file_size` was not a valid number\n* `file_size_too_small`: `file_size` is below minimum file size for\n uploads via this API\n* `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\nthe authenticated user does not have access to it.\n\n* `invalid_parameter`: The `folder_id` value represents a\n folder that the user does not have access to, or does not\n 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.\n\nMust not overlap with the range of a part already\nuploaded this session. Each part’s size must be\nexactly equal in size to the part size specified\nin the upload session that you created.\nOne exception is the last part of the file, as this can be smaller.\n\nWhen providing the value for `content-range`, remember that:\n\n* The lower bound of each part's byte range\n must be a multiple of the part size.\n* 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}/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 \navailable 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\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto 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: null
vanity_name: null
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: null
vanity_name: null
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: null
vanity_name: null
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: null
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: null
'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'
components:
schemas:
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.
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'
File:
title: File
type: object
x-box-resource-id: file
x-box-variant: standard
description: 'A standard representation of a file, as returned from any
file API endpoints by default'
allOf:
- $ref: '#/components/schemas/File--Mini'
- properties:
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
description: A list of parent folders for an item.
type: object
required:
- total_count
- entries
properties:
total_count:
description: The number of folders in this list.
example: 1
type: integer
format: int64
nullable: false
entries:
type: array
description: The parent folders for this item
nullable: false
items:
$ref: '#/components/schemas/Folder--Mini'
- 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
description: The time at which this file was put in the trash.
example: '2012-12-12T10:53:43-08:00'
nullable: true
purged_at:
type: string
format: date-time
description: 'The time at which this file is expected to be purged
from the trash.'
example: '2012-12-12T10:53:43-08:00'
nullable: true
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:
allOf:
- title: Shared link
description: 'Shared links provide direct, read-only access to files or folder on Box.
Shared links with open access level allow anyone with the URL
to access the item, while shared links with company or collaborators access
levels can only be accessed by appropriately authenticated Box users.'
type: object
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
properties:
url:
type: string
format: url
description: 'The URL that can be used to access the item on Box.
This URL will display the item in Box''s preview UI where the file
can be downloaded if allowed.
This URL will continue to work even when a custom `vanity_url`
has been set for this shared link.'
example: https://www.box.com/s/vspke7y05sb214wjokpk
nullable: false
download_url:
type: string
format: url
x-box-premium-feature: true
description: 'A URL that can be used to download the file. This URL can be used in
a browser to download the file. This URL includes the file
extension so that the file will be saved with the right file type.
This property will be `null` for folders.'
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
nullable: true
vanity_url:
type: string
format: url
description: 'The "Custom URL" that can also be used to preview the item on Box. Custom
URLs can only be created or modified in the Box Web application.'
example: https://acme.app.box.com/v/my_url/
nullable: true
vanity_name:
type: string
description: The custom name of a shared link, as used in the `vanity_url` field.
example: my_url
nullable: true
access:
type: string
description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
enum:
- open
- company
- collaborators
example: open
nullable: false
effective_access:
type: string
description: 'The effective access level for the shared link. This can be a more
restrictive access level than the value in the `access` field when the
enterprise settings restrict the allowed access levels.'
enum:
- open
- company
- collaborators
example: company
nullable: false
effective_permission:
type: string
description: 'The effective permissions for this shared link.
These result in the more restrictive combination of
the share link permissions and the item permissions set
by the administrator, the owner, and any ancestor item
such as a folder.'
enum:
- can_edit
- can_download
- can_preview
- no_access
example: can_download
nullable: false
unshared_at:
type: string
format: date-time
description: 'The date and time when this link will be unshared. This field can only be
set by users with paid accounts.'
example: '2018-04-13T13:53:23-07:00'
nullable: true
is_password_enabled:
type: boolean
description: Defines if the shared link requires a password to access the item.
example: true
nullable: false
permissions:
type: object
description: 'Defines if this link allows a user to preview, edit, and download an item.
These permissions refer to the shared link only and
do not supersede permissions applied to the item itself.'
required:
- can_download
- can_preview
- can_edit
properties:
can_download:
type: boolean
example: true
nullable: false
description: 'Defines if the shared link allows for the item to be downloaded. For
shared links on folders, this also applies to any items in the folder.
This value can be set to `true` when the effective access level is
set to `open` or `company`, not `collaborators`.'
can_preview:
type: boolean
example: true
nullable: false
description: 'Defines if the shared link allows for the item to be previewed.
This value is always `true`. For shared links on folders this also
applies to any items in the folder.'
can_edit:
type: boolean
example: false
nullable: false
description: 'Defines if the shared link allows for the item to be edited.
This value can only be `true` if `can_download` is also `true` and if
the item has a type of `file`.'
download_count:
type: integer
example: 3
description: The number of times this item has been downloaded.
nullable: false
preview_count:
type: integer
example: 3
description: The number of times this item has been previewed.
nullable: false
- description: 'The shared link for this file. This will be
`null` if no shared link has been created for this
file.'
- nullable: true
parent:
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: The folder that this file is located within.
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: active
User--Base:
title: User (Base)
type: object
x-box-resource-id: user--base
x-box-tag: users
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
description: 'A mini representation of a user, used when
nested within another resource.'
required:
- type
- id
properties:
id:
type: string
description: The unique identifier for this user
example: '11446498'
type:
type: string
description: '`user`'
example: user
nullable: false
enum:
- user
FileOrFolderScope:
title: File or folder scope
type: object
description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed
properties:
scope:
type: string
description: The scopes for the resource access
example: item_download
enum:
- annotation_edit
- annotation_view_all
- annotation_view_self
- base_explorer
- base_picker
- base_preview
- base_upload
- item_delete
- item_download
- item_preview
- item_rename
- item_share
object:
allOf:
- oneOf:
- $ref: '#/components/schemas/Folder--Mini'
- $ref: '#/components/schemas/File--Mini'
- description: The file or folder resource
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: null
description: This field is null for the Trash folder
etag:
type: string
nullable: true
example: null
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: null
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
Metadata--Base:
title: Metadata instance (Base)
type: object
x-box-resource-id: metadata--base
x-box-sanitized: true
x-box-tag: file_metadata
x-box-variants:
- base
- standard
- full
x-box-variant: base
description: The base representation of a metadata instance.
properties:
$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: marketingCollateral
description: The name of the template
$scope:
type: string
example: enterprise_27335
description: 'An ID for the scope in which this template
has been applied. This will be `enterprise_{enterprise_id}` for templates
defined for use in this enterprise, and `global` for general templates
that are available to all enterprises using Box.'
$version:
type: integer
example: 1
description: 'The version of the metadata instance. This version starts at 0 and
increases every time a user-defined property is modified.'
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'
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
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:
title: Metadata instance
type: object
x-box-resource-id: metadata
x-box-tag: file_metadata
x-box-variant: standard
description: 'An instance of a metadata template, which has been applied to a file or
folder.'
allOf:
- $ref: '#/components/schemas/Metadata--Base'
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'
Task:
title: Task
type: object
x-box-resource-id: task
x-box-tag: tasks
description: 'A task allows for file-centric workflows within Box. Users can
create tasks on files and assign them to other users for them to complete the
tasks.'
properties:
id:
type: string
description: The unique identifier for this task
example: '11446498'
type:
type: string
description: '`task`'
example: task
enum:
- task
item:
allOf:
- $ref: '#/components/schemas/File--Mini'
- description: The file associated with the task
due_at:
type: string
format: date-time
description: When the task is due
example: '2012-12-12T10:53:43-08:00'
action:
type: string
example: review
description: 'The type of task the task assignee will be prompted to
perform.'
enum:
- review
- complete
message:
type: string
description: A message that will be included with the task
example: Legal review
task_assignment_collection:
allOf:
- $ref: '#/components/schemas/TaskAssignments'
- description: 'A collection of task assignment objects
associated with the task'
is_completed:
type: boolean
description: Whether the task has been completed
example: true
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created the task
created_at:
type: string
format: date-time
description: When the task object was created
example: '2012-12-12T10:53:43-08:00'
completion_rule:
type: string
description: 'Defines which assignees need to complete this task before the task
is considered completed.
* `all_assignees` requires all assignees to review or
approve the the task in order for it to be considered completed.
* `any_assignee` accepts any one assignee to review or
approve the the task in order for it to be considered completed.'
example: all_assignees
enum:
- all_assignees
- any_assignee
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'
Comment--Full:
title: Comment (Full)
type: object
x-box-resource-id: comment--full
x-box-variant: full
description: 'Comments are messages created on files. Comments
can be made independently or created as responses to other
comments'
allOf:
- $ref: '#/components/schemas/Comment'
- properties:
tagged_message:
type: string
example: '@[1234567:Aaron Levie] these tigers are cool!'
description: 'The string representing the comment text with
@mentions included. @mention format is @[id:username]
where `id` is user''s Box ID and `username` is
their display name.'
Collaboration:
title: Collaboration
type: object
x-box-resource-id: collaboration
x-box-tag: user_collaborations
description: 'Collaborations define access permissions for users and groups to files and
folders, similar to access control lists. A collaboration object grants a
user or group access to a file or folder with permissions defined by a
specific role.'
required:
- id
- type
properties:
id:
type: string
description: The unique identifier for this collaboration.
example: '12345678'
type:
type: string
description: '`collaboration`'
example: collaboration
enum:
- collaboration
item:
allOf:
- oneOf:
- $ref: '#/components/schemas/File'
- $ref: '#/components/schemas/Folder'
- $ref: '#/components/schemas/WebLink'
- description: 'The file or folder to which access is granted. The field is
`null` when the collaboration `status` is `pending`.'
nullable: true
accessible_by:
allOf:
- oneOf:
- $ref: '#/components/schemas/User--Collaborations'
- $ref: '#/components/schemas/Group--Mini'
- description: The user or group that is granted access.
invite_email:
type: string
nullable: true
example: john@example.com
description: 'The email address used to invite an unregistered collaborator, if
they are not a registered user.'
role:
type: string
example: editor
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
- owner
description: The level of access granted.
expires_at:
type: string
nullable: true
format: date-time
example: '2012-12-26T10:53:43-08:00'
description: 'When the collaboration will expire, or `null` if no expiration
date is set.'
is_access_only:
type: boolean
example: true
description: 'If set to `true`, collaborators have access to
shared items, but such items won''t be visible in the
All Files list. Additionally, collaborators won''t
see the the path to the root folder for the
shared item.'
status:
type: string
example: accepted
enum:
- accepted
- pending
- rejected
description: 'The status of the collaboration invitation. If the status
is `pending`, `login` and `name` return an empty string.'
acknowledged_at:
type: string
format: date-time
example: '2012-12-12T10:55:20-08:00'
description: 'When the `status` of the collaboration object changed to
`accepted` or `rejected`.'
created_by:
allOf:
- $ref: '#/components/schemas/User--Collaborations'
- description: The user who created the collaboration object.
- example:
- id: 33224412
- type: user
- login: dylan@example.com
- name: Dylan Smith
created_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: When the collaboration object was created.
modified_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: When the collaboration object was last modified.
acceptance_requirements_status:
type: object
properties:
terms_of_service_requirement:
type: object
properties:
is_accepted:
type: boolean
nullable: true
example: true
description: 'Whether or not the terms of service have been accepted. The
field is `null` when there is no terms of service required.'
terms_of_service:
allOf:
- $ref: '#/components/schemas/TermsOfService--Base'
- description: 'The terms of service that must be accepted before the
collaboration can be accepted. The field is `null` when
there is no terms of service required.'
strong_password_requirement:
type: object
properties:
enterprise_has_strong_password_required_for_external_users:
type: boolean
example: true
description: 'Whether or not the enterprise that owns the content requires
a strong password to collaborate on the content.'
user_has_strong_password:
type: boolean
nullable: true
example: true
description: 'Whether or not the user has a strong password set for their
account. The field is `null` when a strong password is not
required.'
two_factor_authentication_requirement:
type: object
properties:
enterprise_has_two_factor_auth_enabled:
type: boolean
example: true
description: 'Whether or not the enterprise that owns the content requires
two-factor authentication to be enabled in order to
collaborate on the content.'
user_has_two_factor_authentication_enabled:
type: boolean
nullable: true
example: true
description: 'Whether or not the user has two-factor authentication
enabled. The field is `null` when two-factor
authentication is not required.'
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'
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'
TaskAssignments:
title: Task assignments
type: object
x-box-resource-id: task_assignments
x-box-tag: task_assignments
description: A list of task assignments
properties:
total_count:
description: The total number of items in this collection.
example: 100
type: integer
format: int64
entries:
type: array
description: A list of task assignments
items:
$ref: '#/components/schemas/TaskAssignment'
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\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template."
x-box-example-key: name
Folder--Mini:
title: Folder (Mini)
type: object
x-box-resource-id: folder--mini
x-box-variant: mini
description: 'A mini representation of a file version, used when
nested under another resource.'
allOf:
- $ref: '#/components/schemas/Folder--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: 'A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.'
- nullable: false
name:
type: string
description: The name of the folder.
example: Contracts
nullable: false
File--Base:
title: File (Base)
type: object
x-box-resource-id: file--base
x-box-sanitized: true
x-box-tag: files
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
nullable: true
description: 'The bare basic representation of a file, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
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: '12345'
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
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
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'
FileVersion--Mini:
title: File version (Mini)
type: object
x-box-resource-id: file_version--mini
x-box-variant: mini
description: 'A mini representation of a file version, used when
nested within another resource.'
allOf:
- $ref: '#/components/schemas/FileVersion--Base'
- properties:
sha1:
type: string
description: The SHA1 hash of this version of the file.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
File--Mini:
title: File (Mini)
type: object
x-box-resource-id: file--mini
x-box-variant: mini
description: 'A mini representation of a file, used when
nested under another resource.'
nullable: true
allOf:
- $ref: '#/components/schemas/File--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: 'A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.'
- nullable: false
name:
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.
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.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation."
info:
type: object
description: 'An object containing the URL that can be used to fetch more info
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.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation."
- description: 'A list of representations for a file that can be used to
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
FileVersion--Base:
title: File version (Base)
type: object
x-box-resource-id: file_version--base
x-box-sanitized: true
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
description: 'The bare basic representation of a file version, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
properties:
id:
type: string
nullable: false
description: The unique identifier that represent a file version.
example: '12345'
type:
type: string
description: '`file_version`'
example: file_version
enum:
- file_version
nullable: false
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
Folder--Base:
title: Folder (Base)
type: object
x-box-resource-id: folder--base
x-box-sanitized: true
x-box-tag: folders
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
description: 'The bare basic representation of a folder, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
properties:
id:
type: string
nullable: false
description: 'The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting a folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folders/123`
the `folder_id` is `123`.'
example: '12345'
etag:
type: string
nullable: true
example: '1'
description: 'The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.'
type:
type: string
description: '`folder`'
example: folder
enum:
- folder
nullable: false
FileConflict:
title: File (Conflict)
type: object
x-box-sanitized: true
x-box-resource-id: file_conflict
x-box-tag: null
description: A representation of a file that is used to show
allOf:
- $ref: '#/components/schemas/File--Mini'
- properties:
sha1:
type: string
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
description: The SHA1 hash of the file.
file_version:
$ref: '#/components/schemas/FileVersion--Mini'
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
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'
ConflictError:
title: Conflict error
type: object
x-box-resource-id: conflict_error
x-box-tag: uploads
description: 'The error that occurs when a file can not be created due
to a conflict.'
allOf:
- $ref: '#/components/schemas/ClientError'
- properties:
context_info:
type: object
properties:
conflicts:
type: array
description: A list of the file conflicts that caused this error.
items:
$ref: '#/components/schemas/FileConflict'
User--Mini:
title: User (Mini)
type: object
x-box-resource-id: user--mini
x-box-variant: mini
description: 'A mini representation of a user, as can be returned when nested within other
resources.'
allOf:
- $ref: '#/components/schemas/User--Base'
- properties:
name:
type: string
description: The display name of this user
example: Aaron Levie
maxLength: 50
nullable: false
login:
type: string
format: email
description: The primary email address of this user
example: ceo@example.com
nullable: false
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'