---
title: "Create web link"
method: POST
path: "/web_links"
tags: ["Web links"]
---

# Create web link

`POST /web_links`

Creates a web link object within a folder.

## Request body

- object
  - `url` string, required — The URL that this web link links to. Must start with `"http://"` or `"https://"`.
  - `parent` object, required — The parent folder to create the web link within.
    - `id` string, required — The ID of parent folder.
  - `name` string — Name of the web link. Defaults to the URL if not set.
  - `description` string — Description of the web link.

## Response `200`

Returns the newly created 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)