--- title: "Remove shared link from file" method: PUT path: "/files/{file_id}#remove_shared_link" tags: ["Shared links (Files)"] --- # Remove shared link from file `PUT /files/{file_id}#remove_shared_link` Removes a shared link from a file. ## Path parameters - `file_id` string, required ## Query parameters - `fields` string, required ## Request body - object - `shared_link` object, nullable — By setting this value to `null`, the shared link is removed from the file. ## Response `200` Returns a basic representation of a file, with the shared link removed. - FileFull, nullable — The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter. - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. - `type` 'file', required — The value will always be `file`. - `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 file. - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. - `file_version` object — The information about the current version of the file. - `id` string, required — The unique identifier that represent a file version. - `type` 'file_version', required — The value will always be `file_version`. - `sha1` string — The SHA1 hash of this version of the file. - `description` string — The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored. - `size` integer — The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. - `path_collection` object — The tree of folders that this file 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 — The date and time when the file was created on Box. - `modified_at` string, date-time — The date and time when the file was last updated on Box. - `trashed_at` string, date-time, nullable — The time at which this file was put in the trash. - `purged_at` string, date-time, nullable — The time at which this file is expected to be purged from the trash. - `content_created_at` string, date-time, nullable — The date and time at which this file was originally created, which might be before it was uploaded to Box. - `content_modified_at` string, date-time, nullable — The date and time at which this file was last updated, which might be before it was uploaded to Box. - `created_by` object — The user who created this file. - `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 file. - `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 file. - `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 for this file. This value will be `null` if no shared link has been created for this file. - `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. - `parent` object, nullable — The folder that this file is located within. This value may be `null` for some folders such as the root folder or the trash folder. - `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. - `item_status` 'active' | 'trashed' | 'deleted' — Defines if this item has been deleted or not. * `active` when the item has is not in the trash * `trashed` when the item has been moved to the trash but not deleted * `deleted` when the item has been permanently deleted. - `version_number` string — The version number of this file. - `comment_count` integer — The number of comments on this file. - `permissions` object — Describes the permissions that the current user has for this file. - `can_delete` boolean, required — Specifies if the current user can delete this item. - `can_download` boolean, required — Specifies if the current user can download this item. - `can_invite_collaborator` boolean, required — 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. - `can_rename` boolean, required — Specifies if the user can rename this item. - `can_set_share_access` boolean, required — Specifies if the user can change the access level of an existing shared link on this item. - `can_share` boolean, required — Specifies if the user can create a shared link for this item. - `can_annotate` boolean, required — Specifies if the user can place annotations on this file. - `can_comment` boolean, required — Specifies if the user can place comments on this file. - `can_preview` boolean, required — Specifies if the user can preview this file. - `can_upload` boolean, required — Specifies if the user can upload a new version of this file. - `can_view_annotations_all` boolean, required — Specifies if the user view all annotations placed on this file. - `can_view_annotations_self` boolean, required — Specifies if the user view annotations placed by themselves on this file. - `can_apply_watermark` boolean — Specifies if the user can apply a watermark to this file. - `tags` string[] — 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. - `lock` object, nullable — The lock held on this file. If there is no lock, this can either be `null` or have a timestamp in the past. - `id` string — The unique identifier for this lock. - `type` 'lock' — The value will always be `lock`. - `created_by` object — The user who created the lock. - `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. - `created_at` string, date-time — The time this lock was created at. - `expired_at` string, date-time — The time this lock is to expire at, which might be in the past. - `is_download_prevented` boolean — Whether or not the file can be downloaded while locked. - `app_type` 'gsuite' | 'office_wopi' | 'office_wopiplus' | 'other', nullable — 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. - `extension` string — Indicates the (optional) file extension for this file. By default, this is set to an empty string. - `is_package` boolean — Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files. - `expiring_embed_link` object — 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. - `access_token` string, token — The requested access token. - `expires_in` integer — The time in seconds by which this token will expire. - `token_type` 'bearer' — The type of access token returned. - `restricted_to` ResourceScope[] — The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources. - `scope` 'annotation_edit' | 'annotation_view_all' | 'annotation_view_self' | 'base_explorer' | 'base_picker' | 'base_preview' | 'base_upload' | 'item_delete' | 'item_download' | 'item_preview' | 'item_rename' | 'item_share' | 'item_upload' | 'item_read' — The scopes for the resource access. - `object` union — The file or folder resource. - object — The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter. - `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. - object, nullable — The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter. - `id` string, required — The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. - `etag` string, nullable — The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. - `type` 'file', required — The value will always be `file`. - `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 file. - `sha1` string, digest — The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. - `file_version` object — The information about the current version of the file. - `id` string, required — The unique identifier that represent a file version. - `type` 'file_version', required — The value will always be `file_version`. - `sha1` string — The SHA1 hash of this version of the file. - `url` string, url — The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object. - `watermark_info` object — Details about the watermark applied to this file. - `is_watermarked` boolean — Specifies if this item has a watermark applied. - `is_watermark_inherited` boolean — Specifies if the watermark is inherited from any parent folder in the hierarchy. - `is_watermarked_by_access_policy` boolean — Specifies if the watermark is enforced by an access policy. - `is_accessible_via_shared_link` boolean — Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder. - `allowed_invitee_roles` string[] — A list of the types of roles that user can be invited at when sharing this file. - `is_externally_owned` boolean — Specifies if this file is owned by a user outside of the authenticated enterprise. - `has_collaborations` boolean — Specifies if this file has any other collaborators. - `metadata` object — 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` string, date-time, nullable — When the file will automatically be deleted. - `representations` object — A list of representations for a file that can be used to display a placeholder of the file in your application. By default this returns all representations and we recommend using the `x-rep-hints` header to further customize the desired representations. - `entries` object[] — A list of files. - `content` object — An object containing the URL that can be used to actually fetch the representation. - `url_template` string — 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` object — An object containing the URL that can be used to fetch more info on this representation. - `url` string — 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` object — An object containing the size and type of this presentation. - `dimensions` string, x — The width by height size of this representation in pixels. - `paged` string — Indicates if the representation is build up out of multiple pages. - `thumb` string — Indicates if the representation can be used as a thumbnail of the file. - `representation` string — Indicates the file type of the returned representation. - `status` object — An object containing the status of this representation. - `state` 'success' | 'viewable' | 'pending' | 'none' — The status of the representation. * `success` defines the representation as ready to be viewed. * `viewable` defines a video to be ready for viewing. * `pending` defines the representation as to be generated. Retry this endpoint to re-check the status. * `none` defines that the representation will be created when requested. Request the URL defined in the `info` object to trigger this generation. - `classification` object, nullable — Details about the classification applied to this file. - `name` string — The name of the classification. - `definition` string — An explanation of the meaning of this classification. - `color` string — The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app. - `uploader_display_name` string — The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload. If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of `File Request`. In all other anonymous cases where no email was provided this field will default to a value of `Someone`. - `disposition_at` string, date-time, nullable — The retention expiration timestamp for the given file. - `shared_link_permission_options` string[], nullable — A list of the types of roles that user can be invited at when sharing this file. - `is_associated_with_app_item` boolean — This field will return true if the file or any ancestor of the file is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the file. ## Other responses - `401` — Returned when the access token provided in the `Authorization` header is not recognized or not provided. - `403` — Returned if the user does not have all the permissions to complete the update. - `404` — Returned if the file is not found, or the user does not have access to the file. - `405` — Returned if the `file_id` is not in a recognized format. - `412` — 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. - `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/versions/ba8f087e1a4d/schema)