Box Collaborations API
The Box Collaborations API manages sharing permissions for files and folders, allowing applications to invite users, set access levels, accept or reject collaboration invitations, and list existing collaborations.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Collaborations API
description: Needs a description.
paths:
/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'
/folders/{folder_id}/collaborations:
get:
operationId: get_folders_id_collaborations
summary: Box List folder collaborations
description: |-
Retrieves a list of pending and active collaborations for a
folder. This returns all the users that have access to the folder
or have been invited to the folder.
tags:
- Folders
x-box-tag: list_collaborations
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`.
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
responses:
'200':
description: >-
Returns a collection of collaboration objects. If there are no
collaborations on this folder 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'
/collaborations/{collaboration_id}:
get:
operationId: get_collaborations_id
summary: Box Get collaboration
x-box-tag: user_collaborations
tags:
- Collaborations
description: Retrieves a single collaboration.
parameters:
- name: collaboration_id
description: The ID of the collaboration
in: path
required: true
example: '1234'
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 a collaboration object.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaboration'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_collaborations_id
tags:
- Collaborations
x-box-tag: user_collaborations
summary: Box Update collaboration
description: |-
Updates a collaboration.
Can be used to change the owner of an item, or to
accept collaboration invites.
parameters:
- name: collaboration_id
description: The ID of the collaboration
in: path
required: true
example: '1234'
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- role
properties:
role:
type: string
description: The level of access granted.
example: editor
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
- owner
status:
type: string
description: |-
<!--alex ignore reject-->
Set the status of a `pending` collaboration invitation,
effectively accepting, or rejecting the invite.
example: accepted
enum:
- pending
- accepted
- rejected
expires_at:
type: string
format: date-time
description: >-
Update the expiration date for the collaboration. At this
date,
the collaboration will be automatically removed from the
item.
This feature will only work if the **Automatically remove
invited
collaborators: Allow folder owners to extend the expiry
date**
setting has been enabled in the **Enterprise Settings**
of the **Admin Console**. When the setting is not enabled,
collaborations can not have an expiry date and a value for
this
field will be result in an error.
Additionally, a collaboration can only be given an
expiration if it was created after the **Automatically
remove
invited collaborator** setting was enabled.
example: '2019-08-29T23:59:00-07:00'
can_view_path:
type: boolean
description: >-
Determines if the invited users can see the entire parent
path to
the associated folder. The user will not gain privileges in
any
parent folder and therefore can not see content the user is
not
collaborated on.
Be aware that this meaningfully increases the time required
to load the
invitee's **All Files** page. We recommend you limit the
number of
collaborations with `can_view_path` enabled to 1,000 per
user.
Only owner or co-owners can invite collaborators with a
`can_view_path` of
`true`.
`can_view_path` can only be used for folder collaborations.
example: true
responses:
'200':
description: >-
Returns an updated collaboration object unless the owner has
changed.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaboration'
'204':
description: |-
If the role is changed to `owner`, the collaboration is deleted
and a new collaboration is created. The previous `owner` of
the old collaboration will be a `co-owner` on the new collaboration.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaboration'
'403':
description: >-
Returns an error if the authenticated user does not have the right
permissions to update the collaboration.
Additionally, this error may occur when attempting to update the
`expires_at` field for the collaboration without the **Automatically
remove invited collaborators: Allow folder owners to extend the
expiry
date** setting enabled in the admin dashboard of the enterprise.
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_collaborations_id
summary: Box Remove collaboration
tags:
- Collaborations
x-box-tag: user_collaborations
description: Deletes a single collaboration.
parameters:
- name: collaboration_id
description: The ID of the collaboration
in: path
required: true
example: '1234'
schema:
type: string
responses:
'204':
description: |-
A blank response is returned if the collaboration was
successfully deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/collaborations:
get:
operationId: get_collaborations
summary: Box List pending collaborations
tags:
- Collaborations
x-box-tag: list_collaborations
description: Retrieves all pending collaboration invites for this user.
parameters:
- name: status
description: The status of the collaborations to retrieve
in: query
required: true
example: pending
schema:
type: string
enum:
- pending
- 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: 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 collection of pending collaboration objects.
If the user has no pending collaborations, the collection
will be empty.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaborations'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_collaborations
tags:
- Collaborations
x-box-tag: user_collaborations
summary: Box Create collaboration
description: |-
Adds a collaboration for a single user or a single group to a file
or folder.
Collaborations can be created using email address, user IDs, or a
group IDs.
If a collaboration is being created with a group, access to
this endpoint is dependent on the group's ability to be invited.
If collaboration is in `pending` status, the following fields
are redacted:
- `login` and `name` are hidden if a collaboration was created
using `user_id`,
- `name` is hidden if a collaboration was created using `login`.
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: notify
description: |-
Determines if users should receive email notification
for the action performed.
in: query
required: false
example: true
schema:
type: boolean
requestBody:
content:
application/json:
schema:
type: object
required:
- item
- accessible_by
- role
properties:
item:
type: object
description: The item to attach the comment to.
properties:
type:
type: string
description: |-
The type of the item that this collaboration will be
granted access to
example: file
enum:
- file
- folder
id:
type: string
description: The ID of the item that will be granted access to
example: '11446498'
accessible_by:
type: object
description: The user or group to give access to the item.
required:
- type
properties:
type:
type: string
description: The type of collaborator to invite.
example: user
enum:
- user
- group
id:
type: string
description: |-
The ID of the user or group.
Alternatively, use `login` to specify a user by email
address.
example: '23522323'
login:
type: string
description: >-
The email address of the user to grant access to the
item.
Alternatively, use `id` to specify a user by user ID.
example: john@example.com
role:
type: string
description: The level of access granted.
example: editor
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
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.
can_view_path:
type: boolean
description: >-
Determines if the invited users can see the entire parent
path to
the associated folder. The user will not gain privileges in
any
parent folder and therefore can not see content the user is
not
collaborated on.
Be aware that this meaningfully increases the time required
to load the
invitee's **All Files** page. We recommend you limit the
number of
collaborations with `can_view_path` enabled to 1,000 per
user.
Only owner or co-owners can invite collaborators with a
`can_view_path` of
`true`.
`can_view_path` can only be used for folder collaborations.
example: true
expires_at:
type: string
format: date-time
description: >-
Set the expiration date for the collaboration. At this date,
the
collaboration will be automatically removed from the item.
This feature will only work if the **Automatically remove
invited
collaborators: Allow folder owners to extend the expiry
date**
setting has been enabled in the **Enterprise Settings**
of the **Admin Console**. When the setting is not enabled,
collaborations can not have an expiry date and a value for
this
field will be result in an error.
example: '2019-08-29T23:59:00-07:00'
responses:
'201':
description: Returns a new collaboration object.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaboration'
'403':
description: |-
Returns an error when the user does not have the
right permissions to create the collaboration.
* `forbidden_by_policy`: Creating a
collaboration is forbidden due to information
barrier restrictions.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/groups/{group_id}/collaborations:
get:
operationId: get_groups_id_collaborations
summary: Box List group collaborations
x-box-tag: list_collaborations
tags:
- Groups
description: |-
Retrieves all the collaborations for a group. The user
must have admin permissions to inspect enterprise's groups.
Each collaboration object has details on which files or
folders the group has access to and with what role.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
in: path
required: true
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
- name: 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 collaboration objects. If there are no
collaborations, an empty collection will be returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaborations'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
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'
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
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: bool
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/collaborations-openapi-original.yml