Box Collaborations (List) API

openapi: 3.2.0
info:
  title: Box Platform Collaborations (List) API
  description: '[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.'
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
tags:
- name: Collaborations (List)
  description: 'A set of endpoints used to

    retrieve file, folder,

    pending, and group collaborations.'
  x-box-tag: list_collaborations
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:
      - Collaborations (List)
      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:
      - Collaborations (List)
      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
      - 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:
    get:
      operationId: get_collaborations
      summary: Box List pending collaborations
      tags:
      - Collaborations (List)
      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'
  /groups/{group_id}/collaborations:
    get:
      operationId: get_groups_id_collaborations
      summary: Box List group collaborations
      x-box-tag: list_collaborations
      tags:
      - Collaborations (List)
      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:
    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
            - 'null'
            format: date-time
            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
            - 'null'
            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'
          description:
            allOf:
            - type: string
              description: The optional description of this folder
              maxLength: 256
              example: Legal contracts for the new ACME deal
            - {}
          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
          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
                entries:
                  type: array
                  description: The parent folders for this item
                  items:
                    $ref: '#/components/schemas/Folder--Mini'
            - description: 'The tree of folders that this folder is contained in,

                starting at the root.'
            - {}
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this folder
            - {}
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this folder.
            - {}
          trashed_at:
            type:
            - string
            - 'null'
            format: date-time
            description: The time at which this folder was put in the trash.
            example: '2012-12-12T10:53:43-08:00'
          purged_at:
            type:
            - string
            - 'null'
            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'
          content_created_at:
            type:
            - string
            - 'null'
            format: date-time
            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
            - 'null'
            format: date-time
            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.
            - {}
          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
                download_url:
                  type:
                  - string
                  - 'null'
                  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
                vanity_url:
                  type:
                  - string
                  - 'null'
                  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/
                vanity_name:
                  type:
                  - string
                  - 'null'
                  description: The custom name of a shared link, as used in the `vanity_url` field.
                  example: my_url
                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
                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
                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
                unshared_at:
                  type:
                  - string
                  - 'null'
                  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'
                is_password_enabled:
                  type: boolean
                  description: Defines if the shared link requires a password to access the item.
                  example: true
                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
                      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
                      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
                      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.
                preview_count:
                  type: integer
                  example: 3
                  description: The number of times this item has been previewed.
            - description: 'The shared link for this folder. This will be

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

                folder.'
          folder_upload_email:
            type:
            - object
            - 'null'
            properties:
              access:
                type: string
                example: open
                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
          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.'
          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
            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.'
            - {}
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    FileVersion--Mini:
      title: File version (Mini)
      type: object
      x-box-resource-id: file_version--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested within another resource.'
      allOf:
      - $ref: '#/components/schemas/FileVersion--Base'
      - properties:
          sha1:
            type: string
            description: The SHA1 hash of this version of the file.
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    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`.'
        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
          - 'null'
          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
          - 'null'
          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
                  - 'null'
                  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
                  - 'null'
                  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
                  - 'null'
                  example: true
                  description: 'Whether or not the user has two-factor authentication

                    enabled. The field is `null` when two-factor

                    authentication is not required.'
    FileVersion--Base:
      title: File version (Base)
      type: object
      x-box-resource-id: file_version--base
      x-box-sanitized: true
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a file version, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
  

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