Box Trashed Folders API

openapi: 3.1.0
info:
  title: Box Authorize Authorization Trashed Folders API
  description: Needs a description.
tags:
- name: Trashed Folders
  description: 'Folders that were deleted and

    are in trash.'
  x-box-tag: trashed_folders
paths:
  /folders/{folder_id}:
    post:
      operationId: post_folders_id
      summary: Box Restore folder
      tags:
      - Trashed Folders
      x-box-tag: trashed_folders
      description: 'Restores a folder that has been moved to the trash.


        An optional new parent ID can be provided to restore the folder to in case the

        original folder has been deleted.


        # Folder locking


        During this operation, part of the file tree will be locked, mainly

        the source folder and all of its descendants, as well as the destination

        folder.


        For the duration of the operation, no other move, copy, delete, or restore

        operation can performed on any of the locked folders.'
      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`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: An optional new name for the folder.
                  example: Restored Photos
                  type: string
                parent:
                  allOf:
                  - type: object
                    description: The parent for this item
                    properties:
                      id:
                        type: string
                        description: The ID of parent item
                        example: '123'
                  - description: 'Specifies an optional ID of a folder to restore the folder

                      to when the original folder no longer exists.


                      Please be aware that this ID will only be used if the original

                      folder no longer exists. Use this ID to provide a fallback

                      location to restore the folder to if the original location

                      has been deleted.'
      responses:
        '201':
          description: Returns a folder object when the folder has been restored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrashFolderRestored'
        '403':
          description: 'Returns an error if the user does not have access to the folder

            the folder is being restored to, or the user does not have permission

            to restore folders from the trash.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the folder is not in the trash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: "* Returned an error if there is a folder with the same name\n  in the destination folder.\n\n* `operation_blocked_temporary`: Returned if either of the destination\n  or source folders is locked due to another move, copy, delete or\n  restore operation in process.\n\n  The operation can be retried at a later point."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /folders/{folder_id}/trash:
    get:
      operationId: get_folders_id_trash
      summary: Box Get trashed folder
      tags:
      - Trashed Folders
      x-box-tag: trashed_folders
      description: 'Retrieves a folder that has been moved to the trash.


        Please note that only if the folder itself has been moved to the

        trash can it be retrieved with this API call. If instead one of

        its parent folders was moved to the trash, only that folder

        can be inspected using the

        [`GET /folders/:id/trash`](e://get_folders_id_trash) API.


        To list all items that have been moved to the trash, please

        use the [`GET /folders/trash/items`](e://get-folders-trash-items/)

        API.'
      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`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: 'Returns the folder that was trashed,

            including information about when the it

            was moved to the trash.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrashFolder'
        '404':
          description: 'Returns an error if the folder can not be found directly

            in the trash.


            Please note that a `HTTP 404` is also returned if any of

            the folder''s parent folders have been moved to the trash.


            In that case, only that parent folder can be inspected using

            the [`GET /folders/:id/trash`](e://get_folders_id_trash) API.'
          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_folders_id_trash
      summary: Box Permanently remove folder
      tags:
      - Trashed Folders
      x-box-tag: trashed_folders
      description: 'Permanently deletes a folder that is in the trash.

        This action cannot be undone.'
      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`.


          The root folder of a Box account is

          always represented by the ID `0`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
          nullable: false
      responses:
        '204':
          description: 'Returns an empty response when the folder was

            permanently deleted.'
        '404':
          description: Returns an error if the folder is not in the trash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    TrashFolderRestored:
      title: Trashed Folder (Restored)
      type: object
      x-box-resource-id: trash_folder_restored
      x-box-tag: trashed_folders
      description: Represents a folder restored from the trash.
      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: '123456789'
        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
        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
        created_at:
          type: string
          format: date-time
          nullable: true
          description: 'The date and time when the folder was created. This value may

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

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

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

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


            Be careful parsing this integer as its

            value can get very large.'
          example: 629644
          nullable: false
        path_collection:
          allOf:
          - title: Path collection
            description: A list of parent folders for an item.
            type: object
            required:
            - total_count
            - entries
            properties:
              total_count:
                description: The number of folders in this list.
                example: 1
                type: integer
                format: int64
                nullable: false
              entries:
                type: array
                description: The parent folders for this item
                nullable: false
                items:
                  $ref: '#/components/schemas/Folder--Mini'
          - description: 'The tree of folders that this file is contained in,

              starting at the root.'
          - nullable: false
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who created this folder
          - nullable: false
        modified_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who last modified this folder.
          - nullable: false
        trashed_at:
          type: string
          description: 'The time at which this folder was put in the

            trash - becomes `null` after restore.'
          example: null
          nullable: true
        purged_at:
          type: string
          description: 'The time at which this folder is expected to be purged

            from the trash  - becomes `null` after restore.'
          example: null
          nullable: true
        content_created_at:
          type: string
          format: date-time
          nullable: true
          description: 'The date and time at which this folder was originally

            created.'
          example: '2012-12-12T10:53:43-08:00'
        content_modified_at:
          type: string
          format: date-time
          nullable: true
          description: The date and time at which this folder was last updated.
          example: '2012-12-12T10:53:43-08:00'
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this folder.
          - nullable: false
        shared_link:
          type: string
          description: 'The shared link for this file. This will

            be `null` if a folder had been trashed, even though the original shared

            link does become active again.'
          example: null
          nullable: true
        folder_upload_email:
          type: string
          description: 'The folder upload email for this folder. This will

            be `null` if a folder has been trashed, even though the original upload

            email does become active again.'
          example: null
          nullable: true
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: 'The optional folder that this folder is located within.


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

              root folder or the trash folder.'
          - nullable: true
        item_status:
          type: string
          description: 'Defines if this item has been deleted or not.


            * `active` when the item has is not in the trash

            * `trashed` when the item has been moved to the trash but not deleted

            * `deleted` when the item has been permanently deleted.'
          enum:
          - active
          - trashed
          - deleted
          nullable: false
          example: active
    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
    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
    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
    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
    TrashFolder:
      title: Trashed Folder
      type: object
      x-box-resource-id: trash_folder
      x-box-tag: trashed_folders
      description: Represents a trashed folder.
      required:
      - id
      - type
      - name
      - description
      - size
      - path_collection
      - created_by
      - modified_by
      - owned_by
      - item_status
      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: '123456789'
        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
        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
        created_at:
          type: string
          format: date-time
          nullable: true
          description: 'The date and time when the folder was created. This value may

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

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

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

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


            Be careful parsing this integer as its

            value can get very large.'
          example: 629644
          nullable: false
        path_collection:
          allOf:
          - title: Path collection (Trash)
            description: A list of parent folders for an item in the trash.
            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:
                description: Array of folders for this item's path collection
                type: array
                items:
                  type: object
                  description: The parent folder for this item
                  properties:
                    type:
                      type: string
                      description: '`folder`'
                      enum:
                      - folder
                      example: folder
                    id:
                      type: string
                      description: The unique identifier that represent a folder.
                      example: '123456789'
                    sequence_id:
                      type: string
                      nullable: true
                      example: null
                      description: This field is null for the Trash folder
                    etag:
                      type: string
                      nullable: true
                      example: null
                      description: This field is null for the Trash folder
                    name:
                      type: string
                      description: The name of the Trash folder.
                      example: Trash
                      nullable: false
          - description: 'The tree of folders that this file is contained in,

              starting at the root.'
          - nullable: false
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who created this folder
          - nullable: false
        modified_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who last modified this folder.
          - nullable: false
        trashed_at:
          type: string
          format: date-time
          description: The time at which this folder was put in the trash.
          example: '2012-12-12T10:53:43-08:00'
          nullable: true
        purged_at:
          type: string
          format: date-time
          description: 'The time at which this folder is expected to be purged

            from the trash.'
          example: '2012-12-12T10:53:43-08:00'
          nullable: true
        content_created_at:
          type: string
          format: date-time
          nullable: true
          description: 'The date and time at which this folder was originally

            created.'
          example: '2012-12-12T10:53:43-08:00'
        content_modified_at:
          type: string
          format: date-time
          nullable: true
          description: The date and time at which this folder was last updated.
          example: '2012-12-12T10:53:43-08:00'
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this folder.
          - nullable: false
        shared_link:
          type: string
          description: 'The shared link for this folder. This will

            be `null` if a folder has been trashed, since the link will no longer

            be active.'
          example: null
          nullable: true
        folder_upload_email:
          type: string
          description: 'The folder upload email for this folder. This will

            be `null` if a folder has been trashed, since the upload will no longer

            work.'
          example: null
          nullable: true
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: 'The optional folder that this folder is located within.


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

              root folder or the trash folder.'
          - nullable: true
        item_status:
          type: string
          description: 'Defines if this item has been deleted or not.


            * `active` when the item has is not in the trash

            * `trashed` when the item has been moved to the trash but not deleted

            * `deleted` when the item has been permanently deleted.'
          enum:
          - active
          - trashed
          - deleted
          nullable: false
          example: trashed
    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