---
title: "Update web link"
method: PUT
path: "/web_links/{web_link_id}"
tags: ["Web links"]
---

# Update web link

`PUT /web_links/{web_link_id}`

Updates a web link object.

## Path parameters

- `web_link_id` string, required

## Request body

- object
  - `url` string — The new URL that the web link links to. Must start with `"http://"` or `"https://"`.
  - `parent` object — The new parent folder to put the web link in. Use this to move the web link to a different folder.
    - `id` string — The ID of parent item.
    - `user_id` string — The input for `user_id` is optional. Moving to non-root folder is not allowed when `user_id` is present. Parent folder id should be zero when `user_id` is provided.
  - `name` string — A new name for the web link. Defaults to the URL if not set.
  - `description` string — A new description of the web link.
  - `shared_link` object — The settings for the shared link to update.
    - `access` 'open' | 'company' | 'collaborators' — 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.
    - `password` string, nullable — 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`.
    - `vanity_name` string — 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.
    - `unshared_at` string, date-time — 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.

## Response `200`

Returns the updated web link object.

- WebLink — 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.
  - `id` string, required — The unique identifier for this web link.
  - `type` 'web_link', required — The value will always be `web_link`.
  - `etag` string — The entity tag of this web link. Used with `If-Match` headers.
  - `url` string — The URL this web link points to.
  - `sequence_id` string — 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` string — The name of the web link.
  - `parent` object — The parent object the web link belongs to.
    - `id` string, required — 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`.
    - `etag` string, nullable — 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` 'folder', required — The value will always be `folder`.
    - `sequence_id` string — 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` string — The name of the folder.
  - `description` string — The description accompanying the web link. This is visible within the Box web application.
  - `path_collection` object — The tree of folders that this web link is contained in, starting at the root.
    - `total_count` integer, required — The number of folders in this list.
    - `entries` FolderMini[], required — The parent folders for this item.
      - `id` string, required — 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`.
      - `etag` string, nullable — 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` 'folder', required — The value will always be `folder`.
      - `sequence_id` string — 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` string — The name of the folder.
  - `created_at` string, date-time — When this file was created on Box’s servers.
  - `modified_at` string, date-time — When this file was last updated on the Box servers.
  - `trashed_at` string, date-time, nullable — When this file was moved to the trash.
  - `purged_at` string, date-time, nullable — When this file will be permanently deleted.
  - `created_by` object — The user who created this web link.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `modified_by` object — The user who last modified this web link.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `owned_by` object — The user who owns this web link.
    - `id` string, required — The unique identifier for this user.
    - `type` 'user', required — The value will always be `user`.
    - `name` string — The display name of this user.
    - `login` string, email — The primary email address of this user.
  - `shared_link` object, nullable — The shared link object for this item. Will be `null` if no shared link has been created.
    - `url` string, url, required — The URL that can be used to access the item on Box. This URL will display the item in Box's preview UI where the file can be downloaded if allowed. This URL will continue to work even when a custom `vanity_url` has been set for this shared link.
    - `download_url` string, url, nullable — A URL that can be used to download the file. This URL can be used in a browser to download the file. This URL includes the file extension so that the file will be saved with the right file type. This property will be `null` for folders.
    - `vanity_url` string, url, nullable — The "Custom URL" that can also be used to preview the item on Box. Custom URLs can only be created or modified in the Box Web application.
    - `vanity_name` string, nullable — The custom name of a shared link, as used in the `vanity_url` field.
    - `access` 'open' | 'company' | 'collaborators' — The access level for this shared link. * `open` - provides access to this item to anyone with this link * `company` - only provides access to this item to people the same company * `collaborators` - only provides access to this item to people who are collaborators on this item If this field is omitted when creating the shared link, the access level will be set to the default access level specified by the enterprise admin.
    - `effective_access` 'open' | 'company' | 'collaborators', required — The effective access level for the shared link. This can be a more restrictive access level than the value in the `access` field when the enterprise settings restrict the allowed access levels.
    - `effective_permission` 'can_edit' | 'can_download' | 'can_preview' | 'no_access', required — The effective permissions for this shared link. These result in the more restrictive combination of the share link permissions and the item permissions set by the administrator, the owner, and any ancestor item such as a folder.
    - `unshared_at` string, date-time, nullable — The date and time when this link will be unshared. This field can only be set by users with paid accounts.
    - `is_password_enabled` boolean, required — Defines if the shared link requires a password to access the item.
    - `permissions` object — Defines if this link allows a user to preview, edit, and download an item. These permissions refer to the shared link only and do not supersede permissions applied to the item itself.
      - `can_download` boolean, required — Defines if the shared link allows for the item to be downloaded. For shared links on folders, this also applies to any items in the folder. This value can be set to `true` when the effective access level is set to `open` or `company`, not `collaborators`.
      - `can_preview` boolean, required — Defines if the shared link allows for the item to be previewed. This value is always `true`. For shared links on folders this also applies to any items in the folder.
      - `can_edit` boolean, required — Defines if the shared link allows for the item to be edited. This value can only be `true` if `can_download` is also `true` and if the item has a type of `file`.
    - `download_count` integer, required — The number of times this item has been downloaded.
    - `preview_count` integer, required — The number of times this item has been previewed.
  - `item_status` 'active' | 'trashed' | 'deleted' — 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.

## Other responses

- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)