Box Trashed Web Links API

openapi: 3.2.0
info:
  title: Box Platform Trashed web links API
  description: Box Platform provides functionality to provide access to content stored within Box. 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://developer.box.com
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2024.0'
  x-box-commit-hash: 53bdced3cd
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server.
security:
- OAuth2Security: []
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: Restore web link
      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
        in: path
        description: The ID of the web link.
        required: true
        schema:
          type: string
        example: '12345'
      - name: fields
        in: query
        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.'
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - id
        - type
        - name
        explode: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: An optional new name for the web link.
                  type: string
                  example: Restored.docx
                parent:
                  allOf:
                  - type: object
                    description: The parent for this item.
                    properties:
                      id:
                        description: The ID of parent item.
                        type: string
                        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'
      x-box-tag: trashed_web_links
      tags:
      - Trashed web links
      x-codeSamples:
      - lang: curl
        label: Restore web link
        source: "curl -i -X POST \"https://api.box.com/2.0/web_links/12345\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\""
      - lang: dotnet
        label: Restore web link
        source: 'await client.TrashedWebLinks.RestoreWeblinkFromTrashAsync(webLinkId: weblink.Id);'
      - lang: swift
        label: Restore web link
        source: 'try await client.trashedWebLinks.restoreWeblinkFromTrash(webLinkId: weblink.id)'
      - lang: java
        label: Restore web link
        source: client.getTrashedWebLinks().restoreWeblinkFromTrash(weblink.getId())
      - lang: node
        label: Restore web link
        source: await client.trashedWebLinks.restoreWeblinkFromTrash(weblink.id);
      - lang: python
        label: Restore web link
        source: client.trashed_web_links.restore_weblink_from_trash(weblink.id)
  /web_links/{web_link_id}/trash:
    get:
      operationId: get_web_links_id_trash
      summary: Get trashed web link
      description: Retrieves a web link that has been moved to the trash.
      parameters:
      - name: web_link_id
        in: path
        description: The ID of the web link.
        required: true
        schema:
          type: string
        example: '12345'
      - name: fields
        in: query
        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.'
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - id
        - type
        - name
        explode: false
      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'
      x-box-tag: trashed_web_links
      tags:
      - Trashed web links
      x-codeSamples:
      - lang: curl
        label: Get trashed web link
        source: "curl -i -X GET \"https://api.box.com/2.0/web_links/12345/trash\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\""
      - lang: dotnet
        label: Get trashed web link
        source: 'await client.TrashedWebLinks.GetTrashedWebLinkByIdAsync(webLinkId: weblink.Id);'
      - lang: swift
        label: Get trashed web link
        source: 'try await client.trashedWebLinks.getTrashedWebLinkById(webLinkId: weblink.id)'
      - lang: java
        label: Get trashed web link
        source: client.getTrashedWebLinks().getTrashedWebLinkById(weblink.getId())
      - lang: node
        label: Get trashed web link
        source: await client.trashedWebLinks.getTrashedWebLinkById(weblink.id);
      - lang: python
        label: Get trashed web link
        source: client.trashed_web_links.get_trashed_web_link_by_id(weblink.id)
    delete:
      operationId: delete_web_links_id_trash
      summary: Permanently remove web link
      description: Permanently deletes a web link that is in the trash. This action cannot be undone.
      parameters:
      - name: web_link_id
        in: path
        description: The ID of the web link.
        required: true
        schema:
          type: string
        example: '12345'
      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'
      x-box-tag: trashed_web_links
      tags:
      - Trashed web links
      x-codeSamples:
      - lang: curl
        label: Permanently remove web link
        source: "curl -i -X DELETE \"https://api.box.com/2.0/web_links/12345/trash\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\""
      - lang: dotnet
        label: Permanently remove web link
        source: 'await client.TrashedWebLinks.DeleteTrashedWebLinkByIdAsync(webLinkId: weblink.Id);'
      - lang: swift
        label: Permanently remove web link
        source: 'try await client.trashedWebLinks.deleteTrashedWebLinkById(webLinkId: weblink.id)'
      - lang: java
        label: Permanently remove web link
        source: client.getTrashedWebLinks().deleteTrashedWebLinkById(weblink.getId())
      - lang: node
        label: Permanently remove web link
        source: await client.trashedWebLinks.deleteTrashedWebLinkById(weblink.id);
      - lang: python
        label: Permanently remove web link
        source: client.trashed_web_links.delete_trashed_web_link_by_id(weblink.id)
components:
  schemas:
    TrashWebLink:
      description: Represents a trashed web link.
      type: object
      properties:
        type:
          description: The value will always be `web_link`.
          type: string
          example: web_link
          enum:
          - web_link
        id:
          description: The unique identifier for this web link.
          type: string
          example: '11446498'
        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.'
          - {}
        etag:
          description: The entity tag of this web link. Used with `If-Match` headers.
          type: string
          example: '1'
        name:
          description: The name of the web link.
          type: string
          example: My Bookmark
        url:
          description: The URL this web link points to.
          type: string
          example: https://www.example.com/example/1234
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: The parent object the web link belongs to.
        description:
          description: The description accompanying the web link. This is visible within the Box web application.
          type: string
          example: Example page
        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.
                type: integer
                format: int64
                example: 1
              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:
                      description: The value will always be `folder`.
                      type: string
                      example: folder
                      enum:
                      - folder
                    id:
                      description: The unique identifier that represent a folder.
                      type: string
                      example: '123456789'
                    sequence_id:
                      description: This field is null for the Trash folder.
                      type:
                      - string
                      - 'null'
                      example: null
                    etag:
                      description: This field is null for the Trash folder.
                      type:
                      - string
                      - 'null'
                      example: null
                    name:
                      description: The name of the Trash folder.
                      type: string
                      example: Trash
          - description: The tree of folders that this web link is contained in, starting at the root.
          - {}
        created_at:
          description: When this file was created on Box’s servers.
          type: string
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        modified_at:
          description: When this file was last updated on the Box servers.
          type: string
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        trashed_at:
          description: When this file was last moved to the trash.
          type:
          - string
          - 'null'
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        purged_at:
          description: When this file will be permanently deleted.
          type:
          - string
          - 'null'
          format: date-time
          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:
          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.
          type:
          - string
          - 'null'
          example: null
        item_status:
          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.
          type: string
          example: trashed
          enum:
          - active
          - trashed
          - deleted
      title: Trashed Web Link
      x-box-resource-id: trash_web_link
      x-box-tag: trashed_web_links
    Folder--Mini:
      description: A mini representation of a file version, used when nested under another resource.
      type: object
      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:
            description: The name of the folder.
            type: string
            example: Contracts
      title: Folder (Mini)
      x-box-resource-id: folder--mini
      x-box-tag: folders
      x-box-variant: mini
    ClientError:
      description: A generic error.
      type: object
      properties:
        type:
          description: The value will always be `error`.
          type: string
          example: error
          enum:
          - error
        status:
          description: The HTTP status of the response.
          type: integer
          format: int32
          example: 400
        code:
          description: A Box-specific error code.
          type: string
          example: item_name_invalid
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - unprocessable_entity
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          type: string
          example: Method Not Allowed
        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'
          example:
            message: Something went wrong
          additionalProperties: {}
        help_url:
          description: A URL that links to more information about why this error occurred.
          type: string
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
        request_id:
          description: A unique identifier for this response, which can be used when contacting Box support.
          type: string
          example: abcdef123456
      title: Client error
      x-box-resource-id: client_error
    User--Mini:
      description: A mini representation of a user, as can be returned when nested within other resources.
      type: object
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            description: The display name of this user.
            type: string
            example: Aaron Levie
            maxLength: 50
          login:
            description: The primary email address of this user.
            type: string
            format: email
            example: ceo@example.com
      title: User (Mini)
      x-box-resource-id: user--mini
      x-box-tag: users
      x-box-variant: mini
    Folder--Base:
      description: The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.
      type: object
      properties:
        id:
          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`.'
          type: string
          example: '12345'
        etag:
          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:
          - string
          - 'null'
          example: '1'
        type:
          description: The value will always be `folder`.
          type: string
          example: folder
          enum:
          - folder
      required:
      - id
      - type
      title: Folder (Base)
      x-box-resource-id: folder--base
      x-box-tag: folders
      x-box-variant: base
      x-box-variants:
      - base
      - mini
      - standard
      - full
    TrashWebLinkRestored:
      description: Represents a web link restored from the trash.
      type: object
      properties:
        type:
          description: The value will always be `web_link`.
          type: string
          example: web_link
          enum:
          - web_link
        id:
          description: The unique identifier for this web link.
          type: string
          example: '11446498'
        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.'
          - {}
        etag:
          description: The entity tag of this web link. Used with `If-Match` headers.
          type: string
          example: '1'
        name:
          description: The name of the web link.
          type: string
          example: My Bookmark
        url:
          description: The URL this web link points to.
          type: string
          example: https://www.example.com/example/1234
        parent:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: The parent object the web link belongs to.
        description:
          description: The description accompanying the web link. This is visible within the Box web application.
          type: string
          example: Example page
        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.
                type: integer
                format: int64
                example: 1
              entries:
                description: The parent folders for this item.
                type: array
                items:
                  $ref: '#/components/schemas/Folder--Mini'
          - description: The tree of folders that this web link is contained in, starting at the root.
          - {}
        created_at:
          description: When this file was created on Box’s servers.
          type: string
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        modified_at:
          description: When this file was last updated on the Box servers.
          type: string
          format: date-time
          example: '2012-12-12T10:53:43-08:00'
        trashed_at:
          description: The time at which this bookmark was put in the trash - becomes `null` after restore.
          type:
          - string
          - 'null'
          example: null
        purged_at:
          description: The time at which this bookmark will be permanently deleted - becomes `null` after restore.
          type:
          - string
          - 'null'
          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:
          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.
          type:
          - string
          - 'null'
          example: null
        item_status:
          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.
          type: string
          example: trashed
          enum:
          - active
          - trashed
          - deleted
      required:
      - sequence_id
      - path_collection
      title: Trashed Web Link (Restored)
      x-box-resource-id: trash_web_link_restored
      x-box-tag: trashed_web_links
    User--Base:
      description: A mini representation of a user, used when nested within another resource.
      type: object
      properties:
        id:
          description: The unique identifier for this user.
          type: string
          example: '11446498'
        type:
          description: The value will always be `user`.
          type: string
          example: user
          enum:
          - user
      required:
      - type
      - id
      title: User (Base)
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variant: base
      x-box-variants:
      - base
      - mini
      - standard
      - full
  securitySchemes:
    OAuth2Security:
      type: oauth2
      description: The access token received from the authorization server in the OAuth 2.0 flow.
      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
x-mint:
  mcp:
    enabled: true
x-provenance:
  method: harvested
  publisher: Box
  source: https://developer.box.com/box-openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)