Box Web Links API
The Box Web Links API manages web link (bookmark) objects in Box, allowing applications to create, retrieve, update, and delete URL bookmarks stored alongside files and folders.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Web Links API
description: Needs a description.
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'
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'
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'
/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:
vanity_name:
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:
vanity_name:
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:
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/web-links-openapi-original.yml