Box Web Links API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Web Links API
  description: Needs a description.
tags:
- name: Web Links
  description: 'Web links are objects that point to URLs.

    These objects are also known as bookmarks

    within the Box web application.'
  x-box-tag: web_links
paths:
  /web_links:
    post:
      operationId: post_web_links
      summary: Box Create web link
      tags:
      - Web Links
      x-box-tag: web_links
      description: Creates a web link object within a folder.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - parent
              - url
              properties:
                url:
                  type: string
                  example: https://box.com
                  description: 'The URL that this web link links to. Must start with

                    `"http://"` or `"https://"`.'
                parent:
                  type: object
                  description: The parent folder to create the web link within.
                  required:
                  - id
                  properties:
                    id:
                      type: string
                      description: The ID of parent folder
                      example: '0'
                name:
                  type: string
                  example: Box Website
                  description: Name of the web link. Defaults to the URL if not set.
                description:
                  type: string
                  example: Cloud Content Management
                  description: Description of the web link.
      responses:
        '200':
          description: Returns the newly created web link object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /web_links/{web_link_id}:
    get:
      operationId: get_web_links_id
      summary: Box Get web link
      tags:
      - Web Links
      x-box-tag: web_links
      description: Retrieve information about a web link.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: boxapi
        description: 'The URL, and optional password, for the shared link of this item.


          This header can be used to access items that have not been

          explicitly shared with a user.


          Use the format `shared_link=[link]` or if a password is required then

          use `shared_link=[link]&shared_link_password=[password]`.


          This header can be used on the file or folder shared, as well as on any files

          or folders nested within the item.'
        example: shared_link=[link]&shared_link_password=[password]
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Returns the web link object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_web_links_id
      summary: Box Update web link
      tags:
      - Web Links
      x-box-tag: web_links
      description: Updates a web link object.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  example: https://box.com
                  description: 'The new URL that the web link links to. Must start with

                    `"http://"` or `"https://"`.'
                parent:
                  allOf:
                  - type: object
                    description: The parent for this item
                    properties:
                      id:
                        type: string
                        description: The ID of parent item
                        example: '123'
                  - description: 'The new parent folder to put the web link in.

                      Use this to move the web link to a different folder.'
                name:
                  type: string
                  example: Box Website
                  description: A new name for the web link. Defaults to the URL if not set.
                description:
                  type: string
                  example: Cloud Content Management
                  description: A new description of the web link.
                shared_link:
                  description: The settings for the shared link to update.
                  type: object
                  properties:
                    access:
                      type: string
                      description: 'The level of access for the shared link. This can be

                        restricted to anyone with the link (`open`), only people

                        within the company (`company`) and only those who

                        have been invited to the folder (`collaborators`).


                        If not set, this field defaults to the access level specified

                        by the enterprise admin. To create a shared link with this

                        default setting pass the `shared_link` object with

                        no `access` field, for example `{ "shared_link": {} }`.


                        The `company` access level is only available to paid

                        accounts.'
                      enum:
                      - open
                      - company
                      - collaborators
                      example: open
                    password:
                      type: string
                      description: 'The password required to access the shared link. Set the

                        password to `null` to remove it.

                        Passwords must now be at least eight characters

                        long and include a number, upper case letter, or

                        a non-numeric or non-alphabetic character.

                        A password can only be set when `access` is set to `open`.'
                      example: do-not-use-this-password
                    vanity_name:
                      type: string
                      description: 'Defines a custom vanity name to use in the shared link URL,

                        for example `https://app.box.com/v/my-shared-link`.


                        Custom URLs should not be used when sharing sensitive content

                        as vanity URLs are a lot easier to guess than regular shared

                        links.'
                      minLength: 12
                      example: my-shared-link
                    unshared_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'The timestamp at which this shared link will

                        expire. This field can only be set by

                        users with paid accounts. The value must be greater than the

                        current date and time.'
      responses:
        '200':
          description: Returns the updated web link object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_web_links_id
      summary: Box Remove web link
      tags:
      - Web Links
      x-box-tag: web_links
      description: Deletes a web link.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'An empty response will be returned when the web link

            was successfully deleted.'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_web_links_id
      summary: Box Restore web link
      tags:
      - 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:
      - 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:
      - 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'
  /web_links/{web_link_id}#get_shared_link:
    get:
      operationId: get_web_links_id#get_shared_link
      summary: Box Get shared link for web link
      tags:
      - Web Links
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Gets the information for a shared link on a web link.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns the base representation of a web link with the

            additional shared link information.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
              examples:
                default:
                  value:
                    id: '12345'
                    type: web_link
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: false
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

            is not recognized or not provided.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the file is not found, or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          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}#add_shared_link:
    put:
      operationId: put_web_links_id#add_shared_link
      summary: Box Add shared link to web link
      tags:
      - Web Links
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Adds a shared link to a web link.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: 'The settings for the shared link to create on the web link.


                    Use an empty object (`{}`) to use the default settings for shared

                    links.'
                  type: object
                  properties:
                    access:
                      type: string
                      description: 'The level of access for the shared link. This can be

                        restricted to anyone with the link (`open`), only people

                        within the company (`company`) and only those who

                        have been invited to the file (`collaborators`).


                        If not set, this field defaults to the access level specified

                        by the enterprise admin. To create a shared link with this

                        default setting pass the `shared_link` object with

                        no `access` field, for example `{ "shared_link": {} }`.


                        The `company` access level is only available to paid

                        accounts.'
                      enum:
                      - open
                      - company
                      - collaborators
                      example: open
                    password:
                      type: string
                      description: 'The password required to access the shared link. Set the

                        password to `null` to remove it.

                        Passwords must now be at least eight characters

                        long and include a number, upper case letter, or

                        a non-numeric or non-alphabetic character.

                        A password can only be set when `access` is set to `open`.'
                      example: do-n8t-use-this-Password
                    vanity_name:
                      type: string
                      description: 'Defines a custom vanity name to use in the shared link URL,

                        for example `https://app.box.com/v/my-shared-link`.


                        Custom URLs should not be used when sharing sensitive content

                        as vanity URLs are a lot easier to guess than regular shared

                        links.'
                      minLength: 12
                      example: my-shared-link
                    unshared_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'The timestamp at which this shared link will

                        expire. This field can only be set by

                        users with paid accounts. The value must be greater than the

                        current date and time.'
                    permissions:
                      type: object
                      properties:
                        can_download:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for downloading of files.

                            This can only be set when `access` is set to

                            `open` or `company`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

                            This value is always `true`. For shared links on folders

                            this also applies to any items in the folder.'
                        can_edit:
                          type: boolean
                          example: false
                          description: This value can only be `true` is `type` is `file`.
      responses:
        '200':
          description: 'Returns the base representation of a web link with a new shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
              examples:
                default:
                  value:
                    id: '12345'
                    type: web_link
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: false
        '400':
          description: Returned when there is an incorrect permission combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

            is not recognized or not provided.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returned if the user does not have all the permissions to complete the

            update.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returned if the file is not found, or the user does not

            have access to the file.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '405':
          description: Returned if the `file_id` is not in a recognized format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '412':
          description: 'Returns an error when the `If-Match` header does not match

            the current `etag` value of the file. This indicates that the file

            has changed since it was last requested.'
          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}#update_shared_link:
    put:
      operationId: put_web_links_id#update_shared_link
      summary: Box Update shared link on web link
      tags:
      - Web Links
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Updates a shared link on a web link.
      parameters:
      - name: web_link_id
        description: The ID of the web link.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'Explicitly request the `shared_link` fields

          to be returned for this item.'
        example: shared_link
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shared_link:
                  description: The settings for the shared link to update.
                  type: object
                  properties:
                    access:
                      type: string
                      description: 'The level of access for the shared link. This can be

                        restricted to anyone with the link (`open`), only people

                        within the company (`company`) and only those who

                        have been invited to the folder (`collaborators`).


                        If not set, this field defaults to the access level specified

                        by the enterprise admin. To create a shared link with this

                        default setting pass the `shared_link` object with

                        no `access` field, for example `{ "shared_link": {} }`.


                        The `company` access level is only available to paid

                        accounts.'
                      enum:
                      - open
                      - company
                      - collaborators
                      example: open
                    password:
                      type: string
                      description: 'The password required to access the shared link. Set the

                        password to `null` to remove it.

                        Passwords must now be at least eight characters

                        long and include a number, upper case letter, or

                        a non-numeric or non-alphabetic character.

                        A password can only be set when `access` is set to `open`.'
                      example: do-n8t-use-this-Password
                    vanity_name:
                      type: string
                      description: 'Defines a custom vanity name to use in the shared link URL,

                        for example `https://app.box.com/v/my-shared-link`.


                        Custom URLs should not be used when sharing sensitive content

                        as vanity URLs are a lot easier to guess than regular shared

                        links.'
                      minLength: 12
                      example: my-shared-link
                    unshared_at:
                      type: string
                      format: date-time
                      example: '2012-12-12T10:53:43-08:00'
                      description: 'The timestamp at which this shared link will

                        expire. This field can only be set by

                        users with paid accounts. The value must be greater than the

                        current date and time.'
                    permissions:
                      type: object
                      properties:
                        can_download:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for downloading of files.

                            This can only be set when `access` is set to

                            `open` or `company`.'
                        can_preview:
                          type: boolean
                          example: true
                          description: 'If the shared link allows for previewing of files.

                            This value is always `true`. For shared links on folders

                            this also applies to any items in the folder.'
                        can_edit:
                          type: boolean
                          example: true
                          description: This value can only be `true` is `type` is `file`.
      responses:
        '200':
          description: 'Returns a basic representation of the web link, with the updated shared

            link attached.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
              examples:
                default:
                  value:
                    id: '12345'
                    type: web_link
                    etag: '1'
                    shared_link:
                      url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
                      download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
                      vanity_url: null
                      vanity_name: null
                      effective_access: open
                      effective_permission: can_download
                      is_password_enabled: false
                      unshared_at: '2020-09-21T10:34:41-07:00'
                      download_count: 0
                      preview_count: 0
                      access: open
                      permissions:
                        can_preview: true
                        can_download: true
                        can_edit: false
        '400':
          description: Returned when there is an incorrect permission combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: 'Returned when the access token provided in the `Authorization` header

            is not recognized or not provided.'
          content:
            application/json:
              schema:
                $ref: '#/components/sc

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