Box Collaborations API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Collaborations API
  description: Needs a description.
tags:
- name: Collaborations
  description: 'Collaborations define access permissions

    for users and groups to files and folders,

    similar to access control lists.'
  x-box-tag: user_collaborations
paths:
  /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:
    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'
    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'
components:
  schemas:
    Folder:
      title: Folder
      type: object
      x-box-resource-id: folder
      x-box-variant: standard
      description: 'A standard representation of a folder, as returned from any

        folder API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Folder--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            nullable: true
            description: 'The date and time when the folder was created. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: 'The date and time when the folder was last updated. This value may

              be `null` for some folders such as the root folder or the trash

              folder.'
            example: '2012-12-12T10:53:43-08:00'
            nullable: true
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
              nullable: false
            - nullable: false
          size:
            type: integer
            format: int64
            description: 'The folder size in bytes.


              Be careful parsing this integer as its

              value can get very large.'
            example: 629644
            nullable: false
          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 folder is contained in,

                starting at the root.'
            - nullable: false
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - nullable: false
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - nullable: false
          trashed_at:
            type: string
            format: date-time
            description: The time at which this folder 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 folder 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 folder was originally

              created.'
            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 folder was last updated.
            example: '2012-12-12T10:53:43-08:00'
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this folder.
            - 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 folder. This will be

                `null` if no shared link has been created for this

                folder.'
            nullable: true
          folder_upload_email:
            type: object
            nullable: true
            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.'
              email:
                description: The optional upload email address for this folder.
                type: string
                format: email
                example: upload.Contracts.asd7asd@u.box.com
                nullable: false
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: 'The optional folder that this folder is located within.


                This value may be `null` for some folders such as the

                root folder or the trash folder.'
            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
          item_collection:
            allOf:
            - $ref: '#/components/schemas/Items'
            - description: 'A page of the items that are in the folder.


                This field can only be requested when querying a folder''s

                information, not when querying a folder''s items.'
            - nullable: false
    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.
            exam

# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-collaborations-api-openapi.yml