Box Trashed Web Links API

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

    are in trash.'
  x-box-tag: trashed_web_links
paths:
  /web_links/{web_link_id}:
    post:
      operationId: post_web_links_id
      summary: Box Restore web link
      tags:
      - Trashed Web Links
      x-box-tag: trashed_web_links
      description: 'Restores a web link that has been moved to the trash.


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

        the original folder has been deleted.'
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        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 web link.
                  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 web link

                      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 web link to if the original location

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

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

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

            in the folder the web link 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'
  /web_links/{web_link_id}/trash:
    get:
      operationId: get_web_links_id_trash
      summary: Box Get trashed web link
      tags:
      - Trashed Web Links
      x-box-tag: trashed_web_links
      description: Retrieves a web link that has been moved to the trash.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        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 web link that was trashed,

            including information about when the it

            was moved to the trash.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrashWebLink'
        '404':
          description: Returns an error if the web link 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'
    delete:
      operationId: delete_web_links_id_trash
      summary: Box Permanently remove web link
      tags:
      - Trashed Web Links
      x-box-tag: trashed_web_links
      description: 'Permanently deletes a web link that is in the trash.

        This action cannot be undone.'
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'Returns an empty response when the web link was

            permanently deleted.'
        '404':
          description: Returns an error if the web link 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
    TrashWebLink:
      title: Trashed Web Link
      type: object
      x-box-resource-id: trash_web_link
      x-box-tag: trashed_web_links
      description: Represents a trashed web link.
      properties:
        type:
          type: string
          description: '`web_link`'
          example: web_link
          enum:
          - web_link
        id:
          type: string
          description: The unique identifier for this web link
          example: '11446498'
        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
        etag:
          type: string
          example: '1'
          description: 'The entity tag of this web link. Used with `If-Match`

            headers.'
        name:
          type: string
          description: The name of the web link
          example: My Bookmark
        url:
          type: string
          example: https://www.example.com/example/1234
          description: The URL this web link points to
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: The parent object the web link belongs to
        description:
          type: string
          example: Example page
          description: 'The description accompanying the web link. This is

            visible within the Box web application.'
        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 web link is contained in,

              starting at the root.'
          - nullable: false
        created_at:
          type: string
          format: date-time
          description: When this file was created on Box’s servers.
          example: '2012-12-12T10:53:43-08:00'
        modified_at:
          type: string
          format: date-time
          description: 'When this file was last updated on the Box

            servers.'
          example: '2012-12-12T10:53:43-08:00'
        trashed_at:
          type: string
          format: date-time
          nullable: true
          description: When this file was last moved to the trash.
          example: '2012-12-12T10:53:43-08:00'
        purged_at:
          type: string
          format: date-time
          nullable: true
          description: When this file will be permanently deleted.
          example: '2012-12-12T10:53:43-08:00'
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who created this web link
        modified_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who last modified this web link
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this web link
        shared_link:
          type: string
          description: 'The shared link for this bookmark. This will

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

            be active.'
          example: null
          nullable: true
        item_status:
          type: string
          example: trashed
          enum:
          - active
          - trashed
          - deleted
          description: 'Whether this item is deleted or not. Values include `active`,

            `trashed` if the file has been moved to the trash, and `deleted` if

            the file has been permanently deleted'
    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
    TrashWebLinkRestored:
      title: Trashed Web Link (Restored)
      type: object
      x-box-resource-id: trash_web_link_restored
      x-box-tag: trashed_web_links
      description: Represents a web link restored from the trash.
      required:
      - sequence_id
      - path_collection
      properties:
        type:
          type: string
          description: '`web_link`'
          example: web_link
          enum:
          - web_link
        id:
          type: string
          description: The unique identifier for this web link
          example: '11446498'
        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
        etag:
          type: string
          example: '1'
          description: 'The entity tag of this web link. Used with `If-Match`

            headers.'
        name:
          type: string
          description: The name of the web link
          example: My Bookmark
        url:
          type: string
          example: https://www.example.com/example/1234
          description: The URL this web link points to
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: The parent object the web link belongs to
        description:
          type: string
          example: Example page
          description: 'The description accompanying the web link. This is

            visible within the Box web application.'
        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 web link is contained in,

              starting at the root.'
          - nullable: false
        created_at:
          type: string
          format: date-time
          description: When this file was created on Box’s servers.
          example: '2012-12-12T10:53:43-08:00'
        modified_at:
          type: string
          format: date-time
          description: 'When this file was last updated on the Box

            servers.'
          example: '2012-12-12T10:53:43-08:00'
        trashed_at:
          type: string
          nullable: true
          description: 'The time at which this bookmark was put in the

            trash - becomes `null` after restore.'
          example: null
        purged_at:
          type: string
          nullable: true
          description: 'The time at which this bookmark will be permanently

            deleted - becomes `null` after restore.'
          example: null
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who created this web link
        modified_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who last modified this web link
        owned_by:
          allOf:
          - $ref: '#/components/schemas/User--Mini'
          - description: The user who owns this web link
        shared_link:
          type: string
          description: 'The shared link for this bookmark. This will

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

            link does become active again.'
          nullable: true
          example: null
        item_status:
          type: string
          example: trashed
          enum:
          - active
          - trashed
          - deleted
          description: 'Whether this item is deleted or not. Values include `active`,

            `trashed` if the file has been moved to the trash, and `deleted` if

            the file has been permanently deleted'
    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