openapi: 3.1.0
info:
version: "1.0"
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<Message warning>\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</Message>"
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<Message warning>\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</Message>"
responses:
'201':
description: Returns the new file object in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/Files'
'400':
description: "Returns an erro
# --- truncated at 32 KB (243 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-files-api-openapi.yml