Box Shared Links (Web Links) API

openapi: 3.2.0
info:
  title: Box Platform Shared Links (Web Links) 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: Shared Links (Web Links)
  description: 'Web links for files are URLs that are generated

    for web links in Box,

    which provide direct, read-only access to the resource.'
  x-box-tag: shared_links_web_links
paths:
  /shared_items#web_links:
    get:
      operationId: get_shared_items#web_links
      summary: Box Find web link for shared link
      tags:
      - Shared Links (Web Links)
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      description: 'Returns the web link represented by a shared link.


        A shared web link can be represented by a shared link,

        which can originate within the current enterprise or within another.


        This endpoint allows an application to retrieve information about a

        shared web link when only given a shared link.'
      parameters:
      - name: if-none-match
        description: 'Ensures an item is only returned if it has changed.


          Pass in the item''s last observed `etag` value

          into this header and the endpoint will fail

          with a `304 Not Modified` if the item has not

          changed since.'
        in: header
        required: false
        example: '1'
        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
      - name: boxapi
        description: 'A header containing the shared link and optional password for the

          shared link.


          The format for this header is as follows.


          `shared_link=[link]&shared_link_password=[password]`'
        example: shared_link=[link]&shared_link_password=[password]
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Returns a full file resource if the shared link is valid and

            the user has access to it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
        '304':
          description: 'Returns an empty response when the `If-None-Match` header matches

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

            has not changed since it was last requested.'
        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:
      - Shared Links (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:
      - Shared Links (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:
      - Shared Links (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/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}#remove_shared_link:
    put:
      operationId: put_web_links_id#remove_shared_link
      summary: Box Remove shared link from web link
      tags:
      - Shared Links (Web Links)
      x-box-tag: shared_links_web_links
      x-box-enable-explorer: true
      x-box-sanitized: true
      description: Removes a shared link from 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: 'By setting this value to `null`, the shared link

                    is removed from the web link.'
                  type:
                  - object
                  - 'null'
                  example: null
      responses:
        '200':
          description: 'Returns a basic representation of a web link, with the

            shared link removed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebLink'
              examples:
                default:
                  value:
                    id: '12345'
                    type: web_link
                    etag: '1'
                    shared_link: null
        '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'
components:
  schemas:
    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
    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
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
    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
              - '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:
            type: string
            description: The name of the folder.
            example: Contracts
    WebLink--Base:
      title: Web link (Base)
      type: object
      x-box-resource-id: web_link--base
      x-box-tag: web_links
      x-box-variants:
      - base
      - mini
      - standard
      x-box-variant: base
      description: 'Web links are objects that point to URLs. These objects

        are also known as bookmarks within the Box web application.


        Web link objects are treated similarly to file objects,

        they will also support most actions that apply to regular files.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier for this web link
          example: '11446498'
        type:
          type: string
          description: '`web_link`'
          example: web_link
          enum:
          - web_link
        etag:
          type: string
          example: '1'
          description: 'The entity tag of this web link. Used with `If-Match`

            headers.'
    WebLink--Mini:
      title: Web link (Mini)
      type: object
      x-box-resource-id: web_link--mini
      x-box-variant: mini
      description: 'Web links are objects that point to URLs. These objects

        are also known as bookmarks within the Box web application.


        Web link objects are treated similarly to file objects,

        they will also support most actions that apply to regular files.'
      allOf:
      - $ref: '#/components/schemas/WebLink--Base'
      - properties:
          url:
            type: string
            example: https://www.example.com/example/1234
            description: The URL this web link points to
          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:
            type: string
            description: The name of the web link
            example: My Bookmark
    WebLink:
      title: Web link
      type: object
      x-box-resource-id: web_link
      x-box-variant: standard
      description: 'Web links are objects that point to URLs. These objects

        are also known as bookmarks within the Box web application.


        Web link objects are treated similarly to file objects,

        they will also support

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