Box Trashed Files API

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

    are in trash.'
  x-box-tag: trashed_files
paths:
  /files/{file_id}:
    post:
      operationId: post_files_id
      summary: Box Restore file
      tags:
      - Trashed Files
      x-box-tag: trashed_files
      description: 'Restores a file that has been moved to the trash.


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

        original folder has been deleted.'
      parameters:
      - name: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: An optional new name for the file.
                  example: Restored.docx
                  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 file 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 file to if the original location

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

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

            to restore files from the trash.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the file is not in the trash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error if there is an file with the same name

            in the folder the file is being restored to.'
          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}/trash:
    get:
      operationId: get_files_id_trash
      summary: Box Get trashed file
      tags:
      - Trashed Files
      x-box-tag: trashed_files
      description: 'Retrieves a file that has been moved to the trash.


        Please note that only if the file 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: file_id
        description: 'The unique identifier that represents a file.


          The ID for any file can be determined

          by visiting a file in the web application

          and copying the ID from the URL. For example,

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

          the `file_id` is `123`.'
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

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

            including information about when the it

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

            in the trash.


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

            the file''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_files_id_trash
      summary: Box Permanently remove file
      tags:
      - Trashed Files
      x-box-tag: trashed_files
      description: 'Permanently deletes a file that is in the trash.

        This action cannot be undone.'
      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
      responses:
        '204':
          description: 'Returns an empty response when the file was

            permanently deleted.'
        '404':
          description: Returns an error if the file 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:
    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
    TrashFileRestored:
      title: Trashed File (Restored)
      type: object
      x-box-resource-id: trash_file_restored
      x-box-tag: trashed_files
      description: Represents a file restored from the trash.
      required:
      - id
      - type
      - sequence_id
      - sha1
      - description
      - size
      - path_collection
      - created_at
      - modified_at
      - modified_by
      - owned_by
      - item_status
      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: '123456789'
        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
        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.
        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
          nullable: true
          description: 'The time at which this file was put in the

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

            from the trash  - becomes `null` after restore.'
          example: null
        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:
          type: string
          description: 'The shared link for this file. This will

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

            link does become active again.'
          nullable: true
          example: null
        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
    TrashFile:
      title: Trashed File
      type: object
      x-box-resource-id: trash_file
      x-box-tag: trashed_files
      description: Represents a trashed file.
      required:
      - id
      - type
      - sequence_id
      - sha1
      - description
      - size
      - path_collection
      - created_at
      - modified_at
      - modified_by
      - owned_by
      - item_status
      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: '123456789'
        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
        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.
        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 (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_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
          nullable: true
          description: The time at which this file was put in the trash.
          example: '2012-12-12T10:53:43-08:00'
        purged_at:
          type: string
          format: date-time
          nullable: true
          description: 'The time at which this file is expected to be purged

            from the trash.'
          example: '2012-12-12T10:53:43-08:00'
        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:
          type: string
          description: 'The shared link for this file. This will

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

            be active.'
          example: null
          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: trashed
    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
    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
    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