Box Collaborations API

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: [email protected]
                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: [email protected]
          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