openapi: 3.1.0
info:
  title: Box Authorize Authorization Uploads (Chunked) API
  description: Needs a description.
tags:
- name: Uploads (Chunked)
  description: 'The chunked upload endpoints support files from

    20MB in size and allow an application

    to upload the file in parts,

    allowing for more control to catch any errors

    and retry parts individually.'
  x-box-tag: chunked_uploads
paths:
  /files/upload_sessions:
    post:
      operationId: post_files_upload_sessions
      summary: Box Create upload session
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Creates an upload session for a new file.
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - folder_id
              - file_size
              - file_name
              properties:
                folder_id:
                  description: The ID of the folder to upload the new file to.
                  type: string
                  example: '0'
                file_size:
                  description: The total number of bytes of the file to be uploaded
                  example: 104857600
                  type: integer
                  format: int64
                file_name:
                  description: The name of new file
                  example: Project.mov
                  type: string
      responses:
        '201':
          description: Returns a new upload session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '400':
          description: "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `missing_destination`: No `folder_id` was provided\n* `invalid_folder_id`: `folder_id` is not valid\n* `item_name_invalid`: `file_name` is not valid\n* `missing_file_size`: `file_size` was not provided\n* `invalid_file_size`: `file_size` was not a valid number\n* `file_size_too_small`: `file_size` is below minimum file size for\n  uploads via this API\n* `missing_file_name`: `file_name` was not provided"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error if the operation is not allowed for some reason.


            * `storage_limit_exceeded`: Account storage limit reached'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: "Returns an error if the parent folder could not be found, or\nthe authenticated user does not have access to it.\n\n* `invalid_parameter`: The `folder_id` value represents a\n  folder that the user does not have access to, or does not\n  exist."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error if the file already exists,

            or the account has run out of disk space.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/{file_id}/upload_sessions:
    post:
      operationId: post_files_id_upload_sessions
      summary: Box Create upload session for existing file
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Creates an upload session for an existing file.
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      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
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - file_size
              properties:
                file_size:
                  description: The total number of bytes of the file to be uploaded
                  example: 104857600
                  type: integer
                  format: int64
                file_name:
                  description: The optional new name of new file
                  example: Project.mov
                  type: string
      responses:
        '201':
          description: Returns a new upload session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '409':
          description: 'Returns an error if the file already exists,

            or if the account has run out of disk space.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/upload_sessions/{upload_session_id}:
    get:
      operationId: get_files_upload_sessions_id
      summary: Box Get upload session
      tags:
      - Uploads (Chunked)
      description: Return information about an upload session.
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns an upload session object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_files_upload_sessions_id
      summary: Box Upload part of file
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      description: Updates a chunk of an upload session for a file.
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      - name: digest
        description: 'The [RFC3230][1] message digest of the chunk uploaded.


          Only SHA1 is supported. The SHA1 digest must be base64

          encoded. The format of this header is as

          `sha=BASE64_ENCODED_DIGEST`.


          To get the value for the `SHA` digest, use the

          openSSL command to encode the file part:

          `openssl sha1 -binary <FILE_PART_NAME> | base64`


          [1]: https://tools.ietf.org/html/rfc3230'
        example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
        in: header
        required: true
        schema:
          type: string
      - name: content-range
        description: "The byte range of the chunk.\n\nMust not overlap with the range of a part already\nuploaded this session. Each part’s size must be\nexactly equal in size to the part size specified\nin the upload session that you created.\nOne exception is the last part of the file, as this can be smaller.\n\nWhen providing the value for `content-range`, remember that:\n\n* The lower bound of each part's byte range\n  must be a multiple of the part size.\n* The higher bound must be a multiple of the part size - 1."
        example: bytes 8388608-16777215/445856194
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: The binary content of the file
      responses:
        '200':
          description: Chunk has been uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedPart'
        '409':
          description: 'Returns an error if the chunk conflicts with another

            chunk previously uploaded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: Returns an error if a precondition was not met.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '416':
          description: 'Returns an error if the content range does not match a specified range

            for the session.'
          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_files_upload_sessions_id
      summary: Box Remove upload session
      tags:
      - Uploads (Chunked)
      description: 'Abort an upload session and discard all data uploaded.


        This cannot be reversed.'
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      x-box-tag: chunked_uploads
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'A blank response is returned if the session was

            successfully aborted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/upload_sessions/{upload_session_id}/parts:
    get:
      operationId: get_files_upload_sessions_id_parts
      summary: Box List parts
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      description: 'Return a list of the chunks uploaded to the upload

        session so far.'
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          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 list of parts that have been uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadParts'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /files/upload_sessions/{upload_session_id}/commit:
    post:
      operationId: post_files_upload_sessions_id_commit
      summary: Box Commit upload session
      tags:
      - Uploads (Chunked)
      x-box-tag: chunked_uploads
      servers:
      - url: https://upload.box.com/api/2.0
        description: Server for file uploads
      description: 'Close an upload session and create a file from the

        uploaded chunks.'
      parameters:
      - name: upload_session_id
        description: The ID of the upload session.
        example: D5E3F7A
        in: path
        required: true
        schema:
          type: string
      - name: digest
        description: 'The [RFC3230][1] message digest of the whole file.


          Only SHA1 is supported. The SHA1 digest must be Base64

          encoded. The format of this header is as

          `sha=BASE64_ENCODED_DIGEST`.


          [1]: https://tools.ietf.org/html/rfc3230'
        in: header
        example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
        required: true
        schema:
          type: string
      - name: if-match
        description: 'Ensures this item hasn''t recently changed before

          making changes.


          Pass in the item''s last observed `etag` value

          into this header and the endpoint will fail

          with a `412 Precondition Failed` if it

          has changed since.'
        in: header
        required: false
        example: '1'
        schema:
          type: string
      - name: if-none-match
        description: 'Ensures an item is only returned if it has changed.


          Pass in the item''s last observed `etag` value

          into this header and the endpoint will fail

          with a `304 Not Modified` if the item has not

          changed since.'
        in: header
        required: false
        example: '1'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - parts
              properties:
                parts:
                  type: array
                  description: The list details for the uploaded parts
                  items:
                    $ref: '#/components/schemas/UploadPart'
      responses:
        '201':
          description: Returns the file object in a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Files'
        '202':
          description: 'Returns when all chunks have been uploaded but not yet processed.


            Inspect the upload session to get more information about the

            progress of processing the chunks, then retry committing the file

            when all chunks have processed.'
          headers:
            Retry-After:
              description: 'Indicates the number of seconds the client should wait before

                attempting their commit request again.'
              schema:
                type: integer
        '409':
          description: 'Returns an error if there is already a file with the same name

            in the target folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: Returns an error if the `If-Match` or `If-None-Match` conditions fail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    UploadSession:
      title: Upload session
      type: object
      x-box-resource-id: upload_session
      description: An upload session for chunk uploading a file.
      x-box-tag: chunked_uploads
      properties:
        id:
          type: string
          description: The unique identifier for this session
          example: F971964745A5CD0C001BBE4E58196BFD
        type:
          type: string
          description: '`upload_session`'
          example: upload_session
          enum:
          - upload_session
        session_expires_at:
          description: The date and time when this session expires.
          type: string
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        part_size:
          type: integer
          format: int64
          example: 1024
          description: 'The  size in bytes that must be used for all parts of of the

            upload.


            Only the last part is allowed to be of a smaller size.'
        total_parts:
          type: integer
          format: int32
          example: 1000
          description: 'The total number of parts expected in this upload session,

            as determined by the file size and part size.'
        num_parts_processed:
          type: integer
          format: int32
          example: 455
          description: 'The number of parts that have been uploaded and processed

            by the server. This starts at `0`.


            When committing a file files, inspecting this property can

            provide insight if all parts have been uploaded correctly.'
        session_endpoints:
          allOf:
          - title: Session endpoints
            description: A list of endpoints for a chunked upload session.
            type: object
            properties:
              upload_part:
                type: string
                description: The URL to upload parts to
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
              commit:
                type: string
                description: The URL used to commit the file
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit
              abort:
                type: string
                description: The URL for used to abort the session.
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
              list_parts:
                type: string
                description: The URL users to list all parts.
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts
              status:
                type: string
                description: The URL used to get the status of the upload.
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
              log_event:
                type: string
                description: The URL used to get the upload log from.
                example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log
          - description: A list of endpoints for this session.
    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.
            example: '2012-12-12T10:53:43-08:00'
          trashed_at:
            type: string
            format: date-time
            description: The time at which this file 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 file 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 file was originally

              created, which might be before it was uploaded to Box.'
            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 file was last updated,

              which might be before it was uploaded to Box.'
            example: '2012-12-12T10:53:43-08:00'
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created this file
          modified_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who last modified this file
            - nullable: false
          owned_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who owns this file
            - 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 file. This will be

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

                file.'
            - nullable: true
          parent:
            allOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - description: The folder that this file is located within.
            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
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    FileOrFolderScope:
      title: File or folder scope
      type: object
      description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed
      properties:
        scope:
          type: string
          description: The scopes for the resource access
          example: item_download
          enum:
          - annotation_edit
          - annotation_view_all
          - annotation_view_self
          - base_explorer
          - base_picker
          - base_preview
          - base_upload
          - item_delete
          - item_download
          - item_preview
          - item_rename
          - item_share
        object:
          allOf:
          - oneOf:
            - $ref: '#/components/schemas/Folder--Mini'
            - $ref: '#/components/schemas/File--Mini'
          - description: The file or folder resource
    Metadata--Base:
      title: Metadata instance (Base)
      type: object
      x-box-resource-id: metadata--base
      x-box-sanitized: true
      x-box-tag: file_metadata
      x-box-variants:
      - base
      - standard
      - full
      x-box-variant: base
      description: The base representation of a metadata instance.
      properties:
        $parent:
          type: string
          example: folder_59449484661,
          description: 'The identifier of the item that this metadata instance

            has been attached to. This combines the `type` and the `id`

            of the parent in the form `{type}_{id}`.'
        $template:
          type: string
          example: marketingCollateral
          description: The name of the template
        $scope:
          type: string
          example: enterprise_27335
          description: 'An ID for the scope in which this template

            has been applied. This will be `enterprise_{enterprise_id}` for templates

            defined for use in this enterprise, and `global` for general templates

            that are available to all enterprises using Box.'
        $version:
          type: integer
          example: 1
          description: 'The version of the metadata instance. This version starts at 0 and

            increases every time a user-defined property is modified.'
    Metadata:
      title: Metadata instance
      type: object
      x-box-resource-id: metadata
      x-box-tag: file_metadata
      x-box-variant: standard
      description: 'An instance of a metadata template, which has been applied to a file or

        folder.'
      allOf:
      - $ref: '#/components/schemas/Metadata--Base'
    Files:
      title: Files
      type: object
      x-box-resource-id: files
      x-box-tag: files
      description: A list of files
      properties:
        total_count:
          description: The number of files.
          example: 1
          type: integer
          format: int64
        entries:
          type: array
          description: A list of files
          items:
            $ref: '#/components/schemas/File--Full'
    UploadParts:
      title: Upload parts
      type: object
      x-box-resource-id: upload_parts
      x-box-tag: chunked_uploads
      description: 'A list of uploaded chunks for an upload

        session.'
      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 uploaded chunks for an upload

              session'
            items:
              $ref: '#/components/schemas/UploadPart'
    UploadPart--Mini:
      title: Upload part (Mini)
      type: object
      x-box-resource-id: upload_part--mini
      x-box-tag: chunked_uploads
      x-box-variants:
      - mini
      - standard
      x-box-variant: mini
      description: 'The basic representation of an upload

        session chunk.'
      properties:
        part_id:
          description: The unique ID of the chunk.
          type: string
          example: 6F2D3486
        offset:
          description: 'The offset of the chunk within the file

            in bytes. The lower bound of the position

            of the chunk within the file.'
          type: integer
          format: int64
          example: 16777216
        size:
          description: The size of the chunk in bytes.
          type: integer
          format: int64
          example: 3222784
    Folder--Mini:
      title: Folder (Mini)
      type: object
      x-box-resource-id: folder--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - nullable: false
          name:
            type: string
            description: The name of the folder.
            example: Contracts
            nullable: false
    File--Base:
      title: File (Base)
      type: object
      x-box-resource-id: file--base
      x-box-sanitized: true
      x-box-tag: files
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      nullable: true
      description: 'The bare basic representation of a file, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent 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'
        etag:
          type: string
          example: '1'
          nullable: true
          description: 'The HTTP `etag` of this file. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the file if (no) changes have happened.'
        type:
          type: string
          description: '`file`'
          example: file
          enum:
          - file
          nullable: false
    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
    File--Mini:
      title: File (Mini)
      type: object
      x-box-resource-id: file--mini
      x-box-variant: mini
      description: 'A mini representation of a file, used when

        nested under another resource.'
      nullable: true
      allOf:
      - $ref: '#/components/schemas/File--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              description: 'A numeric identifier that represents the most recent user event

                that has been applied to this item.


                This can be used in combination with the `GET /events`-endpoint

                to filter out user events that would have occurred before this

                identifier was read.


                An example would be where a Box Drive-like application

                would fetch an item via the API, and then listen to incoming

                user events for changes to the item. The application would

                ignore any user events where the `sequence_id` in the event

                is smaller than or equal to the `sequence_id` in the originally

                fetched resource.'
            - nullable: false
          name:
            type: string
            description: The name of the file
            example: Contract.pdf
          sha1:
            type: string
            format: digest
            nullable: false
            example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
            description: 'The SHA1 hash of the file. This can be used to compare the contents

              of a file on Box with a local file.'
          file_version:
            allOf:
            - $ref: '#/components/schemas/FileVersion--Mini'
            - description: The information about the current version of the file.
    File--Full:
      title: File (Full)
      type: object
      x-box-resource-id: file--full
      x-box-variant: full
      description: 'A full representation of a file, as can be returned from any

        file API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/File'
      - properties:
          version_number:
            type: string
            example: '1'
            description: The version number of this file
          comment_count:
            type: integer
            example: 10
            description: The number of comments on this file
          permissions:
            allOf:
            - type: object
              description: The permissions that the authenticated user has for a file.
              required:
              - can_annotate
              - can_comment
              - can_preview
              - can_upload
              - can_view_annotations_all
              - can_view_annotations_self
              allOf:
              - type: object
                description: The permissions that the authenticated user has for an item.
                required:
                - can_delete
                - can_download
                - can_invite_collaborator
                - can_rename
                - can_set_share_access
                - can_share
                properties:
                  can_delete:
                    type: boolean
                    description: Specifies if the current user can delete this item.
                    example: true
                    nullable: false
                  can_download:
                    type: boolean
                    description: Specifies if the current user can download this item.
                    example: true
                    nullable: false
                  can_invite_collaborator:
                    type: boolean
                    description: 'Specifies if the current user can invite new

                      users to collaborate on this item, and if the user can

                      update the role of a user already collaborated on this

                      item.'
                    example: true
                    nullable: false
                  can_rename:
                    type: boolean
                    description: Specifies if the user can rename this item.
                    example: true
                    nullable: false
                  can_set_share_access:
                    type: boolean
                    description: 'Specifies if the user can change the access level of an

                      existing shared link on this item.'
                    example: true
                    nullable: false
                  can_share:
                    type: boolean
                    description: Specifies if the user can create a shared link for this item.
                    example: true
                    nullable: false
              - properties:
                  can_annotate:
                    type: boolean
                    description: Specifies if the user can place annotations on this file.
                    example: true
                    nullable: false
                  can_comment:
                    type: boolean
                    description: Specifies if the user can place comments on this file.
                    example: true
                    nullable: false
                  can_preview:
                    type: boolean
                    description: Specifies if the user can preview this file.
                    example: true
                    nullable: false
                  can_upload:
                    type: boolean
                    description: Specifies if the user can upload a new version of this file.
                    example: true
                    nullable: false
                  can_view_annotations_all:
                    type: boolean
                    description: Specifies if the user view all annotations placed on this file
                    example: true
                    nullable: false
                  can_view_annotations_self:
                    type: boolean
                    description: 'Specifies if the user view annotations placed by themselves

                      on this file'
                    example: true
                    nullable: false
            - description: 'Describes the permissions that the current user has

                for this file.'
            - nullable: false
          tags:
            allOf:
            - type: array
              example:
              - approved
              items:
                type: string
              minItems: 1
              maxItems: 100
              description: 'The tags for this item. These tags are shown in

                the Box web app and mobile apps next to an item.


                To add or remove a tag, retrieve the item''s current tags,

                modify them, and then update this field.


                There is a limit of 100 tags per item, and 10,000

                unique tags per enterprise.'
            - nullable: false
          lock:
            allOf:
            - title: Lock
              type: object
              description: 'The lock held on a file. A lock prevents a file from being moved,

                renamed, or otherwise changed by anyone else than the user who created the

                lock.'
              properties:
                id:
                  type: string
                  description: The unique identifier for this lock
                  example: '11446498'
                type:
                  type: string
                  description: '`lock`'
                  example: lock
                  enum:
                  - lock
                created_by:
                  allOf:
                  - $ref: '#/components/schemas/User--Mini'
                  - description: The user who created the lock.
                created_at:
                  type: string
                  format: date-time
                  example: '2012-12-12T10:53:43-08:00'
                  description: The time this lock was created at.
                expired_at:
                  type: string
                  format: date-time
                  example: '2012-12-12T10:53:43-08:00'
                  description: The time this lock is to expire at, which might be in the past.
                is_download_prevented:
                  type: boolean
                  example: true
                  description: Whether or not the file can be downloaded while locked.
                app_type:
                  type: string
                  description: 'If the lock is managed by an application rather than a user, this

                    field identifies the type of the application that holds the lock.

                    This is an open enum and may be extended with additional values in

                    the future.'
                  enum:
                  - gsuite
                  - office_wopi
                  - office_wopiplus
                  - other
                  example: office_wopiplus
                  nullable: true
            - description: 'The lock held on this file. If there is no lock, this can either

                be `null` or have a timestamp in the past.'
            nullable: true
          extension:
            type: string
            example: pdf
            description: 'Indicates the (optional) file extension for this file. By default,

              this is set to an empty string.'
          is_package:
            type: boolean
            example: true
            description: 'Indicates if the file is a package. Packages are commonly used

              by Mac Applications and can include iWork files.'
          expiring_embed_link:
            allOf:
            - title: Expiring embed link
              type: object
              description: An expiring Box Embed Link.
              allOf:
              - type: object
                description: The basics of an access token
                properties:
                  access_token:
                    type: string
                    format: token
                    example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
                    description: The requested access token.
                  expires_in:
                    type: integer
                    format: int64
                    example: 3600
                    description: The time in seconds by which this token will expire.
                  token_type:
                    type: string
                    enum:
                    - bearer
                    example: bearer
                    description: The type of access token returned.
                  restricted_to:
                    type: array
                    description: 'The permissions that this access token permits,

                      providing a list of resources (files, folders, etc)

                      and the scopes permitted for each of those resources.'
                    items:
                      $ref: '#/components/schemas/FileOrFolderScope'
              - properties:
                  url:
                    type: string
                    format: url
                    example: https://cloud.app.box.com/preview/expiring_embed/...
                    description: 'The actual expiring embed URL for this file, constructed

                      from the file ID and access tokens specified in this object.'
            - description: 'Requesting this field creates an expiring Box Embed URL for an

                embedded preview session in an `iframe`.


                This URL will expire after 60 seconds and the session will

                expire after 60 minutes.


                Not all file types are supported for these embed URLs. Box Embed

                is not optimized for mobile browsers and should not be used in web

                experiences designed for mobile devices. Many UI elements, like

                the **download** and **print** options might not show in mobile

                browsers.'
          watermark_info:
            allOf:
            - type: object
              description: Details about the watermark applied to this item
              properties:
                is_watermarked:
                  type: boolean
                  description: Specifies if this item has a watermark applied.
                  example: true
                  nullable: false
            - description: Details about the watermark applied to this file
          is_accessible_via_shared_link:
            type: boolean
            description: 'Specifies if the file can be accessed

              via the direct shared link or a shared link

              to a parent folder.'
            example: true
            enum:
            - true
            - false
          allowed_invitee_roles:
            type: array
            example:
            - editor
            nullable: false
            description: 'A list of the types of roles that user can be invited at

              when sharing this file.'
            items:
              type: string
              enum:
              - editor
              - viewer
              - previewer
              - uploader
              - previewer uploader
              - viewer uploader
              - co-owner
          is_externally_owned:
            type: boolean
            example: true
            nullable: false
            description: 'Specifies if this file is owned by a user outside of the

              authenticated enterprise.'
          has_collaborations:
            type: boolean
            example: true
            nullable: false
            description: Specifies if this file has any other collaborators.
          metadata:
            allOf:
            - title: Item metadata instances
              type: object
              description: 'A list of metadata instances, nested within key-value pairs of their `scope`

                and `templateKey`.


                To access the metadata for a file or folder, first use the

                metadata endpoints to determine the metadata templates available to your

                enterprise.


                Then use the `GET /files/:id` or `GET /folder/:id`

                endpoint with the `fields` query parameter to get

                the metadata by ID.


                To request a metadata instance for a particular `scope` and `templateKey`

                use the following format for the `fields` parameter:

                `metadata.<scope>.<templateKey>`


                For example, `?fields=metadata.enterprise_27335.marketingCollateral`.'
              example:
                enterprise_27335:
                  marketingCollateral:
                    $canEdit: true
                    $id: 01234500-12f1-1234-aa12-b1d234cb567e
                    $parent: folder_59449484661
                    $scope: enterprise_27335
                    $template: marketingCollateral
                    $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                    $typeVersion: 2
                    $version: 1
              additionalProperties:
                type: object
                description: 'A list of metadata instances, nested within key-value pairs of their `scope`

                  and `templateKey`.'
                example:
                  marketingCollateral:
                    $canEdit: true
                    $id: 01234500-12f1-1234-aa12-b1d234cb567e
                    $parent: folder_59449484661
                    $scope: enterprise_27335
                    $template: marketingCollateral
                    $type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
                    $typeVersion: 2
                    $version: 1
                additionalProperties:
                  $ref: '#/components/schemas/Metadata'
            - description: 'An object containing the metadata instances that have been

                attached to this file.


                Each metadata instance is uniquely identified by its `scope` and

                `templateKey`. There can only be one instance of any metadata

                template attached to each file. Each metadata instance is nested

                within an object with the `templateKey` as the key, which again

                itself is nested in an object with the `scope` as the key.'
          expires_at:
            type: string
            format: date-time
            nullable: true
            description: When the file will automatically be deleted
            example: '2012-12-12T10:53:43-08:00'
          representations:
            allOf:
            - title: Representations
              description: A list of file representations
              type: object
              properties:
                entries:
                  type: array
                  description: A list of files
                  items:
                    type: object
                    description: A file representation
                    properties:
                      content:
                        type: object
                        description: 'An object containing the URL that can be used to actually fetch

                          the representation.'
                        properties:
                          url_template:
                            type: string
                            example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567
                            description: "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n  define the representation's file name used in the\n  `Content-Disposition` header.  If not defined, the filename\n  is derived from the source file name in Box combined with the\n  extension of the representation."
                      info:
                        type: object
                        description: 'An object containing the URL that can be used to fetch more info

                          on this representation.'
                        properties:
                          url:
                            type: string
                            example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
                            description: 'The API URL that can be used to get more info on this file

                              representation. Make sure to make an authenticated API call

                              to this endpoint.'
                      properties:
                        type: object
                        description: An object containing the size and type of this presentation.
                        properties:
                          dimensions:
                            type: string
                            format: <width>x<height>
                            example: 2048x2048
                            description: The width by height size of this representation in pixels.
                          paged:
                            type: boolean
                            example: true
                            description: 'Indicates if the representation is build up out of multiple

                              pages.'
                          thumb:
                            type: boolean
                            example: true
                            description: 'Indicates if the representation can be used as a thumbnail of

                              the file.'
                      representation:
                        type: string
                        example: png
                        description: Indicates the file type of the returned representation.
                      status:
                        type: object
                        description: An object containing the status of this representation.
                        properties:
                          state:
                            type: string
                            example: success
                            enum:
                            - success
                            - viewable
                            - pending
                            - none
                            description: "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n  this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n  requested. Request the URL defined in the `info` object to\n  trigger this generation."
            - description: 'A list of representations for a file that can be used to

                display a placeholder of the file in your application. By default

                this returns all representations and we recommend using the

                `x-rep-hints` header to further customize the desired

                representations.'
          classification:
            allOf:
            - type: object
              description: The classification applied to an item
              properties:
                name:
                  type: string
                  example: Top Secret
                  description: The name of the classification
                definition:
                  type: string
                  example: Content that should not be shared outside the company.
                  description: An explanation of the meaning of this classification.
                color:
                  type: string
                  example: '#FF0000'
                  description: 'The color that is used to display the

                    classification label in a user-interface. Colors are defined by the admin

                    or co-admin who created the classification in the Box web app.'
            - description: Details about the classification applied to this file.
            - nullable: true
          uploader_display_name:
            allOf:
            - title: Uploader display name
              type: string
              example: Ellis Wiggins
              nullable: false
              description: 'The display name of the user that uploaded the file. In most cases this is the

                name of the user logged in at the time of the upload.


                If the file was uploaded using a File Request form that requires the user to

                provide an email address, this field is populated with that email address. If

                an email address was not required in the File Request form, this field is set

                to return a value of `File Request`.


                In all other anonymous cases where no email was provided this field

                will default to a value of `Someone`.'
          disposition_at:
            type: string
            format: date-time
            nullable: true
            description: The retention expiration timestamp for the given file
            example: '2012-12-12T10:53:43-08:00'
          shared_link_permission_options:
            type: array
            example:
            - can_preview
            nullable: true
            description: 'A list of the types of roles that user can be invited at

              when sharing this file.'
            items:
              type: string
              enum:
              - can_preview
              - can_download
              - can_edit
    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.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: The unique identifier that represent a file version.
          example: '12345'
        type:
          type: string
          description: '`file_version`'
          example: file_version
          enum:
          - file_version
          nullable: false
    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
    UploadPart:
      title: Upload part
      type: object
      x-box-resource-id: upload_part
      x-box-variant: standard
      description: 'The representation of an upload

        session chunk.'
      allOf:
      - $ref: '#/components/schemas/UploadPart--Mini'
      - properties:
          sha1:
            description: The SHA1 hash of the chunk.
            type: string
            example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          description: 'The unique identifier that represent a folder.


            The ID for any folder can be determined

            by visiting a folder in the web application

            and copying the ID from the URL. For example,

            for the URL `https://*.app.box.com/folders/123`

            the `folder_id` is `123`.'
          example: '12345'
        etag:
          type: string
          nullable: true
          example: '1'
          description: 'The HTTP `etag` of this folder. This can be used within some API

            endpoints in the `If-Match` and `If-None-Match` headers to only

            perform changes on the folder if (no) changes have happened.'
        type:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
          nullable: false
    UploadedPart:
      title: Uploaded part
      type: object
      x-box-resource-id: uploaded_part
      description: 'A chunk of a file uploaded as part of

        an upload session, as returned by some endpoints.'
      x-box-tag: chunked_uploads
      properties:
        part:
          $ref: '#/components/schemas/UploadPart'
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false