Box Shared Items API
The Box Shared Items API allows retrieval of file information for items accessed through shared links, enabling applications to resolve shared link URLs to their underlying file objects.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Shared Items API
description: Needs a description.
paths:
/shared_items:
get:
operationId: get_shared_items
summary: Box Find file for shared link
tags:
- Shared Items
x-box-tag: shared_links_files
x-box-enable-explorer: true
description: |-
Returns the file represented by a shared link.
A shared file 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 file when only given a shared link.
The `shared_link_permission_options` array field can be returned
by requesting it in the `fields` query parameter.
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/File--Full'
'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'
/shared_items#folders:
get:
operationId: get_shared_items#folders
summary: Box Find folder for shared link
tags:
- Shared Items#folders
x-box-tag: shared_links_folders
x-box-enable-explorer: true
description: |-
Return the folder represented by a shared link.
A shared folder 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 folder 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 folder resource if the shared link is valid and
the user has access to it.
content:
application/json:
schema:
$ref: '#/components/schemas/Folder--Full'
'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'
/shared_items#web_links:
get:
operationId: get_shared_items#web_links
summary: Box Find web link for shared link
tags:
- Shared Items#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'
components:
schemas:
File--Full:
title: File (Full)
type: object
x-box-resource-id: file--full
x-box-variant: full
description: |-
A full representation of a file, as can be returned from any
file API endpoints by default
allOf:
- $ref: '#/components/schemas/File'
- properties:
version_number:
type: string
example: '1'
description: The version number of this file
comment_count:
type: integer
example: 10
description: The number of comments on this file
permissions:
allOf:
- type: object
description: The permissions that the authenticated user has for a file.
required:
- can_annotate
- can_comment
- can_preview
- can_upload
- can_view_annotations_all
- can_view_annotations_self
allOf:
- type: object
description: >-
The permissions that the authenticated user has for an
item.
required:
- can_delete
- can_download
- can_invite_collaborator
- can_rename
- can_set_share_access
- can_share
properties:
can_delete:
type: boolean
description: Specifies if the current user can delete this item.
example: true
nullable: false
can_download:
type: boolean
description: >-
Specifies if the current user can download this
item.
example: true
nullable: false
can_invite_collaborator:
type: boolean
description: >-
Specifies if the current user can invite new
users to collaborate on this item, and if the user
can
update the role of a user already collaborated on
this
item.
example: true
nullable: false
can_rename:
type: boolean
description: Specifies if the user can rename this item.
example: true
nullable: false
can_set_share_access:
type: boolean
description: >-
Specifies if the user can change the access level of
an
existing shared link on this item.
example: true
nullable: false
can_share:
type: boolean
description: >-
Specifies if the user can create a shared link for
this item.
example: true
nullable: false
- properties:
can_annotate:
type: boolean
description: >-
Specifies if the user can place annotations on this
file.
example: true
nullable: false
can_comment:
type: boolean
description: >-
Specifies if the user can place comments on this
file.
example: true
nullable: false
can_preview:
type: boolean
description: Specifies if the user can preview this file.
example: true
nullable: false
can_upload:
type: boolean
description: >-
Specifies if the user can upload a new version of
this file.
example: true
nullable: false
can_view_annotations_all:
type: boolean
description: >-
Specifies if the user view all annotations placed on
this file
example: true
nullable: false
can_view_annotations_self:
type: boolean
description: >-
Specifies if the user view annotations placed by
themselves
on this file
example: true
nullable: false
- description: |-
Describes the permissions that the current user has
for this file.
- nullable: false
tags:
allOf:
- type: array
example:
- approved
items:
type: string
minItems: 1
maxItems: 100
description: |-
The tags for this item. These tags are shown in
the Box web app and mobile apps next to an item.
To add or remove a tag, retrieve the item's current tags,
modify them, and then update this field.
There is a limit of 100 tags per item, and 10,000
unique tags per enterprise.
- nullable: false
lock:
allOf:
- title: Lock
type: object
description: >-
The lock held on a file. A lock prevents a file from being
moved,
renamed, or otherwise changed by anyone else than the user
who created the
lock.
properties:
id:
type: string
description: The unique identifier for this lock
example: '11446498'
type:
type: string
description: '`lock`'
example: lock
enum:
- lock
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created the lock.
created_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: The time this lock was created at.
expired_at:
type: string
format: date-time
example: '2012-12-12T10:53:43-08:00'
description: >-
The time this lock is to expire at, which might be in
the past.
is_download_prevented:
type: boolean
example: true
description: Whether or not the file can be downloaded while locked.
app_type:
type: string
description: >-
If the lock is managed by an application rather than a
user, this
field identifies the type of the application that holds
the lock.
This is an open enum and may be extended with additional
values in
the future.
enum:
- gsuite
- office_wopi
- office_wopiplus
- other
example: office_wopiplus
nullable: true
- description: >-
The lock held on this file. If there is no lock, this can
either
be `null` or have a timestamp in the past.
nullable: true
extension:
type: string
example: pdf
description: >-
Indicates the (optional) file extension for this file. By
default,
this is set to an empty string.
is_package:
type: boolean
example: true
description: |-
Indicates if the file is a package. Packages are commonly used
by Mac Applications and can include iWork files.
expiring_embed_link:
allOf:
- title: Expiring embed link
type: object
description: An expiring Box Embed Link.
allOf:
- type: object
description: The basics of an access token
properties:
access_token:
type: string
format: token
example: >-
c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
description: The requested access token.
expires_in:
type: integer
format: int64
example: 3600
description: The time in seconds by which this token will expire.
token_type:
type: string
enum:
- bearer
example: bearer
description: The type of access token returned.
restricted_to:
type: array
description: >-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those
resources.
items:
$ref: '#/components/schemas/FileOrFolderScope'
- properties:
url:
type: string
format: url
example: https://cloud.app.box.com/preview/expiring_embed/...
description: >-
The actual expiring embed URL for this file,
constructed
from the file ID and access tokens specified in this
object.
- description: >-
Requesting this field creates an expiring Box Embed URL for
an
embedded preview session in an `iframe`.
This URL will expire after 60 seconds and the session will
expire after 60 minutes.
Not all file types are supported for these embed URLs. Box
Embed
is not optimized for mobile browsers and should not be used
in web
experiences designed for mobile devices. Many UI elements,
like
the **download** and **print** options might not show in
mobile
browsers.
watermark_info:
allOf:
- type: object
description: Details about the watermark applied to this item
properties:
is_watermarked:
type: boolean
description: Specifies if this item has a watermark applied.
example: true
nullable: false
- description: Details about the watermark applied to this file
is_accessible_via_shared_link:
type: boolean
description: |-
Specifies if the file can be accessed
via the direct shared link or a shared link
to a parent folder.
example: true
enum:
- true
- false
allowed_invitee_roles:
type: array
example:
- editor
nullable: false
description: |-
A list of the types of roles that user can be invited at
when sharing this file.
items:
type: string
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
is_externally_owned:
type: boolean
example: true
nullable: false
description: |-
Specifies if this file is owned by a user outside of the
authenticated enterprise.
has_collaborations:
type: boolean
example: true
nullable: false
description: Specifies if this file has any other collaborators.
metadata:
allOf:
- title: Item metadata instances
type: object
description: >-
A list of metadata instances, nested within key-value pairs
of their `scope`
and `templateKey`.
To access the metadata for a file or folder, first use the
metadata endpoints to determine the metadata templates
available to your
enterprise.
Then use the `GET /files/:id` or `GET /folder/:id`
endpoint with the `fields` query parameter to get
the metadata by ID.
To request a metadata instance for a particular `scope` and
`templateKey`
use the following format for the `fields` parameter:
`metadata.<scope>.<templateKey>`
For example,
`?fields=metadata.enterprise_27335.marketingCollateral`.
example:
enterprise_27335:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
additionalProperties:
type: object
description: >-
A list of metadata instances, nested within key-value
pairs of their `scope`
and `templateKey`.
example:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
additionalProperties:
$ref: '#/components/schemas/Metadata'
- description: >-
An object containing the metadata instances that have been
attached to this file.
Each metadata instance is uniquely identified by its `scope`
and
`templateKey`. There can only be one instance of any
metadata
template attached to each file. Each metadata instance is
nested
within an object with the `templateKey` as the key, which
again
itself is nested in an object with the `scope` as the key.
expires_at:
type: string
format: date-time
nullable: true
description: When the file will automatically be deleted
example: '2012-12-12T10:53:43-08:00'
representations:
allOf:
- title: Representations
description: A list of file representations
type: object
properties:
entries:
type: array
description: A list of files
items:
type: object
description: A file representation
properties:
content:
type: object
description: >-
An object containing the URL that can be used to
actually fetch
the representation.
properties:
url_template:
type: string
example: >-
https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567
description: >-
The download URL that can be used to fetch the
representation.
Make sure to make an authenticated API call to
this endpoint.
This URL is a template and will require the
`{+asset_path}` to
be replaced by a path. In general, for unpaged
representations
it can be replaced by an empty string.
For paged representations, replace the
`{+asset_path}` with the
page to request plus the extension for the
file, for example
`1.pdf`.
When requesting the download URL the following
additional
query params can be passed along.
* `set_content_disposition_type` - Sets the
`Content-Disposition` header in the API
response with the
specified disposition type of either `inline`
or `attachment`.
If not supplied, the `Content-Disposition`
header is not
included in the response.
* `set_content_disposition_filename` - Allows
the application to
define the representation's file name used in the
`Content-Disposition` header. If not defined, the filename
is derived from the source file name in Box combined with the
extension of the representation.
info:
type: object
description: >-
An object containing the URL that can be used to
fetch more info
on this representation.
properties:
url:
type: string
example: >-
https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
description: >-
The API URL that can be used to get more info
on this file
representation. Make sure to make an
authenticated API call
to this endpoint.
properties:
type: object
description: >-
An object containing the size and type of this
presentation.
properties:
dimensions:
type: string
format: <width>x<height>
example: 2048x2048
description: >-
The width by height size of this
representation in pixels.
paged:
type: boolean
example: true
description: >-
Indicates if the representation is build up
out of multiple
pages.
thumb:
type: boolean
example: true
description: >-
Indicates if the representation can be used as
a thumbnail of
the file.
representation:
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/shared-items-openapi-original.yml