Box Trashed Items API

openapi: 3.2.0
info:
  title: Box Platform Trashed Items 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 Items
  description: 'Items that were deleted and

    are in trash.'
  x-box-tag: trashed_items
paths:
  /folders/trash/items:
    get:
      operationId: get_folders_trash_items
      summary: Box List trashed items
      tags:
      - Trashed Items
      x-box-tag: trashed_items
      description: 'Retrieves the files and folders that have been moved

        to the trash.


        Any attribute in the full files or folders objects can be passed

        in with the `fields` parameter to retrieve those specific

        attributes that are not returned by default.


        This endpoint defaults to use offset-based pagination, yet also supports

        marker-based pagination using the `marker` parameter.'
      parameters:
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: offset
        description: 'The offset of the item at which to begin the response.


          Queries with offset parameter value

          exceeding 10000 will be rejected

          with a 400 response.'
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          default: 0
      - name: usemarker
        description: 'Specifies whether to use marker-based pagination instead of

          offset-based pagination. Only one pagination method can

          be used at a time.


          By setting this value to true, the API will return a `marker` field

          that can be passed as a parameter to this endpoint to get the next

          page of the response.'
        in: query
        required: false
        example: true
        schema:
          type: boolean
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          type: string
      - name: direction
        description: 'The direction to sort results in. This can be either in alphabetical ascending

          (`ASC`) or descending (`DESC`) order.'
        in: query
        required: false
        example: ASC
        schema:
          type: string
          enum:
          - ASC
          - DESC
      - name: sort
        description: 'Defines the **second** attribute by which items

          are sorted.


          Items are always sorted by their `type` first, with

          folders listed before files, and files listed

          before web links.


          This parameter is not supported when using marker-based pagination.'
        in: query
        required: false
        example: name
        schema:
          type: string
          enum:
          - name
          - date
          - size
      responses:
        '200':
          description: Returns a list of items that have been deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Items'
        '400':
          description: 'Returns an error if some of the parameters are missing or

            not valid.


            * `invalid_parameter` can appear when the `sort`, `direction` or `offset`

            parameter is provided when using marker based pagination, or when the

            `marker` parameter is provided but `usemarker` is set to `false` or

            `null`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    File--Full:
      title: File (Full)
      type: object
      x-box-resource-id: file--full
      x-box-variant: full
      description: 'A full representation of a file, as can be returned from any

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

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

                      update the role of a user already collaborated on this

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

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

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

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

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


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

                modify them, and then update this field.


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

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

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

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

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

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

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

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

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

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

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

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

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

                embedded preview session in an `iframe`.


                This URL will expire after 60 seconds and the session will

                expire after 60 minutes.


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

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

                experiences designed for mobile devices. Many UI elements, like

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

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

              via the direct shared link or a shared link

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

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

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

                and `templateKey`.


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

                metadata endpoints to determine the metadata templates available to your

                enterprise.


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

                endpoint with the `fields` query parameter to get

                the metadata by ID.


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

                use the following format for the `fields` parameter:

                `metadata.<scope>.<templateKey>`


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

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

                attached to this file.


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

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

                template attached to each file. Each metadata instance is nested

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

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

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

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

                              representation. Make sure to make an authenticated API call

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

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

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

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

                this returns all representations and we recommend using the

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

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

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

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

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


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

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

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

                to return a value of `File Request`.


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

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

              when sharing this file.'
            items:
              type: string
              enum:
              - can_preview
              - can_download
              - can_edit
    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
    Items:
      title: Items
      type: object
      x-box-resource-id: items
      x-box-tag: folders
      description: 'A list of files, folders, and web links in

        their mini representation.'
      allOf:
      - type: object
        description: The part of an API response that describes pagination
        properties:
          total_count:
            description: 'One greater than the offset of the last entry in the entire collection.

              The total number of entries in the collection may be less than

              `total_count`.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            example: 5000
            type: integer
            format: int64
          limit:
            description: 'The limit that was used for these entries. This will be the same as the

              `limit` query parameter unless that value exceeded the maximum value

              allowed. The maximum value varies by API.'
            example: 1000
            type: integer
            format: int64
          offset:
            description: 'The 0-based offset of the first entry in this set. This will be the same

              as the `offset` query parameter.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            example: 2000
            type: integer
            format: int64
          order:
            description: 'The order by which items are returned.


              This field is only returned for calls that use offset-based pagination.

              For marker-based paginated APIs, this field will be omitted.'
            type: array
            items:
              type: object
              description: The order in which a pagination is ordered
              properties:
                by:
                  description: The field to order by
                  example: type
                  type: string
                direction:
                  type: string
                  description: The direction to order by, either ascending or descending
                  example: ASC
                  enum:
                  - ASC
                  - DESC
      - properties:
          entries:
            description: The items in this collection.
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/File--Full'
              - $ref: '#/components/schemas/Folder--Mini'
              - $ref: '#/components/schemas/WebLink'
    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
            maxLeng

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-trashed-items-api-openapi.yml