openapi: 3.1.0
info:
  title: Box Collections API
  description: Needs a description.
paths:
  /collections:
    get:
      operationId: get_collections
      summary: Box List all collections
      tags:
        - Collections
      x-box-tag: collections
      description: |-
        Retrieves all collections for a given user.

        Currently, only the `favorites` collection
        is supported.
      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: 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 all collections for the given user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collections'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /collections/{collection_id}/items:
    get:
      operationId: get_collections_id_items
      summary: Box List collection items
      tags:
        - Collections
      x-box-tag: collections
      description: |-
        Retrieves the files and/or folders contained within
        this collection.
      parameters:
        - name: collection_id
          description: The ID of the collection.
          example: '926489'
          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: 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 an array of items in the collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Items'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Collections:
      title: Collections
      type: object
      x-box-resource-id: collections
      x-box-tag: collections
      description: A list of collections
      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 collections
              items:
                $ref: '#/components/schemas/Collection'
    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
    Items:
      title: Items
      type: object
      x-box-resource-id: items
      x-box-tag: folders
      description: |-
        A list of files, folders, and web links in
        their mini representation.
      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:
              description: The items in this collection.
              type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/File--Full'
                  - $ref: '#/components/schemas/Folder--Mini'
                  - $ref: '#/components/schemas/WebLink'
tags:
  - name: Collections