Box Folders API
The Box Folders API provides endpoints for managing folders in Box, including creating, copying, listing items, getting folder information, updating, and deleting folders, as well as managing folder collaborations and metadata.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Folders API
description: Needs a description.
paths:
/folders/{folder_id}:
get:
operationId: get_folders_id
summary: Box Get folder information
tags:
- Folders
x-box-tag: folders
x-box-enable-explorer: true
x-box-sanitized: true
description: |-
Retrieves details for a folder, including the first 100 entries
in the folder.
Passing `sort`, `direction`, `offset`, and `limit`
parameters in query allows you to manage the
list of returned
[folder items](r://folder--full#param-item-collection).
To fetch more items within the folder, use the
[Get items in a folder](e://get-folders-id-items) endpoint.
parameters:
- name: folder_id
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: '12345'
in: path
required: true
schema:
type: string
nullable: false
- 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: sort
description: |-
Defines the **second** attribute by which items
are sorted.
The folder type affects the way the items
are sorted:
* **Standard folder**:
Items are always sorted by
their `type` first, with
folders listed before files,
and files listed
before web links.
* **Root folder**:
This parameter is not supported
for marker-based pagination
on the root folder
(the folder with an `id` of `0`).
* **Shared folder with parent path
to the associated folder visible to
the collaborator**:
Items are always sorted by
their `type` first, with
folders listed before files,
and files listed
before web links.
in: query
required: false
example: id
schema:
type: string
enum:
- id
- name
- date
- size
- name: direction
description: >-
The direction to sort results in. This can be either in alphabetical
ascending
(`ASC`) or descending (`DESC`) order.
in: query
required: false
example: ASC
schema:
type: string
enum:
- ASC
- DESC
- 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 folder, including the first 100 entries in the folder.
If you used query parameters like
`sort`, `direction`, `offset`, or `limit`
the *folder items list* will be affected accordingly.
To fetch more items within the folder, use the
[Get items in a folder](e://get-folders-id-items)) endpoint.
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/Folder--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.
'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 folder is not found, or the user does not
have access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `folder_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'
post:
operationId: post_folders_id
summary: Box Restore folder
tags:
- Folders
x-box-tag: trashed_folders
description: >-
Restores a folder that has been moved to the trash.
An optional new parent ID can be provided to restore the folder to in
case the
original folder has been deleted.
# Folder locking
During this operation, part of the file tree will be locked, mainly
the source folder and all of its descendants, as well as the destination
folder.
For the duration of the operation, no other move, copy, delete, or
restore
operation can performed on any of the locked folders.
parameters:
- name: folder_id
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: '12345'
in: path
required: true
schema:
type: string
nullable: false
- 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 folder.
example: Restored Photos
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
folder
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 folder to if the original
location
has been deleted.
responses:
'201':
description: Returns a folder object when the folder has been restored.
content:
application/json:
schema:
$ref: '#/components/schemas/TrashFolderRestored'
'403':
description: >-
Returns an error if the user does not have access to the folder
the folder is being restored to, or the user does not have
permission
to restore folders from the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Returns an error if the folder is not in the trash.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
* Returned an error if there is a folder with the same name
in the destination folder.
* `operation_blocked_temporary`: Returned if either of the
destination
or source folders is locked due to another move, copy, delete or
restore operation in process.
The operation can be retried at a later point.
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_folders_id
summary: Box Update folder
description: |-
Updates a folder. This can be also be used to move the folder,
create shared links, update collaborations, and more.
tags:
- Folders
x-box-tag: folders
x-box-sanitized: true
x-box-enable-explorer: true
parameters:
- name: folder_id
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: '12345'
in: path
required: true
schema:
type: string
nullable: false
- 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: The optional new name for this folder.
example: New Folder
description:
type: string
description: The optional description of this folder
maxLength: 256
example: Legal contracts for the new ACME deal
nullable: false
sync_state:
type: string
example: synced
nullable: false
description: |-
Specifies whether a folder should be synced to a
user's device or not. This is used by Box Sync
(discontinued) and is not used by Box Drive.
enum:
- synced
- not_synced
- partially_synced
can_non_owners_invite:
type: boolean
example: true
description: |-
Specifies if users who are not the owner
of the folder can invite new collaborators to the folder.
parent:
type: object
description: |-
The parent folder for this folder. Use this to move
the folder or to restore it out of the trash.
properties:
id:
type: string
description: The ID of the new parent folder
example: '0'
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: Enables the creation of a shared link for a folder.
folder_upload_email:
allOf:
- title: Folder upload email
type: object
description: The Write Folder Upload Email object
properties:
access:
type: string
example: open
nullable: false
enum:
- open
- collaborators
description: >-
When this parameter has been set, users can email
files
to the email address that has been automatically
created for this folder.
To create an email address, set this property either
when
creating or updating the folder.
When set to `collaborators`, only emails from
registered email
addresses for collaborators will be accepted. This
includes
any email aliases a user might have registered.
When set to `open` it will accept emails from any
email
address.
- description: >-
Setting this object enables the upload email address.
This email address can be used by users to directly
upload files directly to the folder via email.
Setting the value to `null` will disable the email
address.
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.
is_collaboration_restricted_to_enterprise:
type: boolean
example: true
description: >-
Specifies if new invites to this folder are restricted to
users
within the enterprise. This does not affect existing
collaborations.
collections:
type: array
description: |-
An array of collections to make this folder
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 folder 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
can_non_owners_view_collaborators:
type: boolean
example: true
description: |-
Restricts collaborators who are not the owner of
this folder from viewing other collaborations on
this folder.
It also restricts non-owners from inviting new
collaborators.
When setting this field to `false`, it is required
to also set `can_non_owners_invite_collaborators` to
`false` if it has not already been set.
responses:
'200':
description: |-
Returns a folder object for the updated folder
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
This call will return synchronously. This holds true even when
moving folders with a large a large number of items in all of its
descendants. For very large folders, this means the call could
take minutes or hours to return.
content:
application/json:
schema:
$ref: '#/components/schemas/Folder--Full'
'400':
description: >-
Returns an error if some of the parameters are missing or
not valid, or if a folder lock is preventing a move operation.
* `bad_request` when a parameter is missing or incorrect. This error
also
happens when a password is set for a shared link with an access type
of `open`.
* `item_name_too_long` when the folder name is too long.
* `item_name_invalid` when the folder name contains
non-valid characters.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
Returns an error if the user does not have the required
access to perform the action.
* `access_denied_insufficient_permissions`: Returned when the
user does not have access to the folder or parent folder, or if the
folder is being moved and a folder lock has been applied to prevent
such operations.
* `insufficient_scope`: Returned an error if the application
does not have the right scope to update folders. Make sure
your application has been configured to read and write all files
and folders stored in Box.
* `forbidden`: Returned when the user is not allowed to perform this
action for other users. This can include trying to create a
Shared Link with a `company` access level on a free account.
* `forbidden_by_policy`: Returned if copying a folder is
forbidden due to information barrier restrictions.
Returns an error if there are too many actions in the request body.
* `operation_limit_exceeded`: Returned when the user passes any
parameters in addition to the `parent.id` in the request body.
The calls to this endpoint have to be split up.
The first call needs to include only the `parent.id`,
the next call can include other parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returns an error if the folder or parent folder could not be found,
or the authenticated user does not have access to either folder.
* `not_found` when the authenticated user does not have access
to the folder or parent folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'409':
description: >-
* `operation_blocked_temporary`: Returned if either of the
destination
or source folders is locked due to another move, copy, delete or
restore operation in progress.
The operation can be retried at a later point.
* `item_name_in_use`: Returned if a folder with the name
already exists in the parent folder.
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 folder. This indicates that the
folder has changed since it was last requested.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'503':
description: |-
Returns an error when the operation takes longer
than 60 seconds. The operation will continue after
this response has been returned.
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_folders_id
summary: Box Delete folder
description: |-
Deletes a folder, either permanently or by moving it to
the trash.
tags:
- Folders
x-box-tag: folders
x-box-sanitized: true
parameters:
- name: folder_id
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: '12345'
in: path
required: true
schema:
type: string
nullable: false
- 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: recursive
description: |-
Delete a folder that is not empty by recursively deleting the
folder and all of its content.
in: query
required: false
example: true
schema:
type: boolean
responses:
'204':
description: |-
Returns an empty response when the folder is successfully deleted
or moved to the trash.
'400':
description: |-
Returns an error if the user makes a bad request.
* `folder_not_empty`: Returned if the folder is not empty. Use the
`recursive` query parameter to recursively delete the folder and
its contents.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: |-
Returns an error if the user does not have the required
access to perform the action.
* `access_denied_insufficient_permissions`: Returned when the
user does not have access to the folder, or when a folder lock has been
applied to the folder to prevent deletion.
# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/folders-openapi-original.yml