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: |- 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: 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. tags: - name: Collaborations - name: Files - name: Folders - name: Groups