Box Trashed Folders API

openapi: 3.2.0
info:
  title: Box Platform Trashed Folders API
  description: '[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.'
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://box.dev
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: 2.0.0
  x-box-commit-hash: '5819125043'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
security:
- OAuth2Security: []
tags:
- name: 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
      - 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
      - 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
      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:
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type:
          - object
          - 'null'
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    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
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    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
              - 'null'
              example: '3'
              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.'
            - {}
          name:
            type: string
            description: The name of the folder.
            example: Contracts
    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
          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
          - 'null'
          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
        sequence_id:
          allOf:
          - type:
            - string
            - 'null'
            example: '3'
            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.'
          - {}
        name:
          type: string
          description: The name of the folder.
          example: Contracts
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'The date and time when the folder was created. This value may

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

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

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

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


            Be careful parsing this integer as its

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

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

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

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

            created.'
          example: '2012-12-12T10:53:43-08:00'
        content_modified_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time at which this folder was last updated.
          example: '2012-12-12T10:53:43-08:00'
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this folder.
          - {}
        shared_link:
          type:
          - string
          - 'null'
          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
        folder_upload_email:
          type:
          - string
          - 'null'
          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
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: 'The optional folder that this folder is located within.


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

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


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

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

            * `deleted` when the item has been permanently deleted.'
          enum:
          - active
          - trashed
          - deleted
          example: active
    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
          enum:
          - user
    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
          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
          - 'null'
          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
    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
          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
          - 'null'
          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
        sequence_id:
          allOf:
          - type:
            - string
            - 'null'
            example: '3'
            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.'
          - {}
        name:
          type: string
          description: The name of the folder.
          example: Contracts
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: 'The date and time when the folder was created. This value may

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

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

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

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


            Be careful parsing this integer as its

            value can get very large.'
          example: 629644
        path_collection:
          allOf:
          - title: Path collection (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
              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
                      - 'null'
                      example: null
                      description: This field is null for the Trash folder
                    etag:
                      type:
                      - string
                      - 'null'
                      example: null
                      description: This field is null for the Trash folder
                    name:
                      type: string
                      description: The name of the Trash folder.
                      example: Trash
          - description: 'The tree of folders that this file is contained in,

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

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

            created.'
          example: '2012-12-12T10:53:43-08:00'
        content_modified_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time at which this folder was last updated.
          example: '2012-12-12T10:53:43-08:00'
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this folder.
          - {}
        shared_link:
          type:
          - string
          - 'null'
          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
        folder_upload_email:
          type:
          - string
          - 'null'
          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
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: 'The optional folder that this folder is located within.


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

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


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

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

            * `deleted` when the item has been permanently deleted.'
          enum:
          - active
          - trashed
          - deleted
          example: trashed
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds
externalDocs:
  description: Box Developer Documentation
  url: https://developer.box.com