--- title: "Update folder" method: PUT path: "/folders/{folder_id}" tags: ["Folders"] --- # Update folder `PUT /folders/{folder_id}` Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. ## Path parameters - `folder_id` string, required ## Query parameters - `fields` string[] ## Headers - `if-match` string ## Request body - object - `name` string — The optional new name for this folder. The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`. - `description` string — The optional description of this folder. - `sync_state` 'synced' | 'not_synced' | 'partially_synced' — Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. - `can_non_owners_invite` boolean — Specifies if users who are not the owner of the folder can invite new collaborators to the folder. - `parent` object — The parent folder for this folder. Use this to move the folder or to restore it out of the trash. - `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. - `shared_link` object — Enables the creation of a shared link for a folder. - `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. - `permissions` object - `can_download` boolean — If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. - `folder_upload_email` object, nullable — Setting this object enables the upload email address. This email address can be used by users to directly upload files directly to the folder via email. Setting the value to `null` will disable the email address. - `access` 'open' | 'collaborators' — When this parameter has been set, users can email files to the email address that has been automatically created for this folder. To create an email address, set this property either when creating or updating the folder. When set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered. When set to `open` it will accept emails from any email address. - `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. - `is_collaboration_restricted_to_enterprise` boolean — Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. - `collections` object[], nullable — An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: https://developer.box.com/reference/get-collections - `id` string — The unique identifier for this object. - `type` string — The type for this object. - `can_non_owners_view_collaborators` boolean — Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set. ## Response `200` Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. - FolderFull — 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. - `created_at` string, date-time, nullable — The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. - `modified_at` string, date-time, nullable — The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder. - `description` string — The optional description of this folder. - `size` integer — The folder size in bytes. Be careful parsing this integer as its value can get very large. - `path_collection` object — The tree of folders that this folder 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_by` object — The user who created this folder. - `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 folder. - `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. - `trashed_at` string, date-time, nullable — The time at which this folder was put in the trash. - `purged_at` string, date-time, nullable — The time at which this folder is expected to be purged from the trash. - `content_created_at` string, date-time, nullable — The date and time at which this folder was originally created. - `content_modified_at` string, date-time, nullable — The date and time at which this folder was last updated. - `owned_by` object — The user who owns this folder. - `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 folder. This will be `null` if no shared link has been created for this folder. - `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. - `folder_upload_email` object, nullable — The `folder_upload_email` parameter is not `null` if one of the following options is **true**: * The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted. * The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked). If the conditions are not met, the parameter will have the following value: `folder_upload_email: null`. - `access` 'open' | 'collaborators' — When this parameter has been set, users can email files to the email address that has been automatically created for this folder. To create an email address, set this property either when creating or updating the folder. When set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered. When set to `open` it will accept emails from any email address. - `email` string, email — The optional upload email address for this folder. - `parent` object, nullable — The optional folder that this folder 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. - `item_collection` object — A page of the items that are in the folder. This field can only be requested when querying a folder's information, not when querying a folder's items. - `limit` integer — The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. - `next_marker` string, nullable — The marker for the start of the next page of results. - `prev_marker` string, nullable — The marker for the start of the previous page of results. - `total_count` integer — One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. - `offset` integer — The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. - `order` object[] — The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. - `by` string — The field to order by. - `direction` 'ASC' | 'DESC' — The direction to order by, either ascending or descending. - `entries` Item[] — The items in this collection. - union — An item represents a file, folder, or web link. - 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. - `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. - … - `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. - … - `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. - … - `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. - … - `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. - … - `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. - 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 — 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. - … - `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. - … - `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. - `sync_state` 'synced' | 'not_synced' | 'partially_synced' — Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. - `has_collaborations` boolean — Specifies if this folder has any other collaborators. - `permissions` object — Describes the permissions that the current user has for this folder. - `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_upload` boolean, required — Specifies if the user can upload into this folder. - `can_apply_watermark` boolean — Specifies if the user can apply a watermark to this folder and its contents. - `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. - `can_non_owners_invite` boolean — Specifies if users who are not the owner of the folder can invite new collaborators to the folder. - `is_externally_owned` boolean — Specifies if this folder is owned by a user outside of the authenticated enterprise. - `metadata` object — An object containing the metadata instances that have been attached to this folder. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each folder. 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. - `is_collaboration_restricted_to_enterprise` boolean — Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. - `allowed_shared_link_access_levels` string[] — A list of access levels that are available for this folder. For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level. - `allowed_invitee_roles` string[] — A list of the types of roles that user can be invited at when sharing this folder. - `watermark_info` object — Details about the watermark applied to this folder. - `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 folder can be accessed with the direct shared link or a shared link to a parent folder. - `can_non_owners_view_collaborators` boolean — Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. - `classification` object, nullable — Details about the classification applied to this folder. - `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. - `is_associated_with_app_item` boolean — This field will return true if the folder or any ancestor of the folder 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 folder. ## Other responses - `400` — Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation. * `bad_request` when a parameter is missing or incorrect. This error also happens when a password is set for a shared link with an access type of `open`. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. - `403` — Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder or parent folder, or if the folder is being moved and a folder lock has been applied to prevent such operations. * `insufficient_scope`: Returned an error if the application does not have the right scope to update folders. Make sure your application has been configured to read and write all files and folders stored in Box. * `forbidden`: Returned when the user is not allowed to perform this action for other users. This can include trying to create a Shared Link with a `company` access level on a free account. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. Returns an error if there are too many actions in the request body. * `operation_limit_exceeded`: Returned when the user passes any parameters in addition to the `parent.id` in the request body. The calls to this endpoint have to be split up. The first call needs to include only the `parent.id`, the next call can include other parameters. - `404` — Returns an error if the folder or parent folder could not be found, or the authenticated user does not have access to either folder. * `not_found` when the authenticated user does not have access to the folder or parent folder. - `409` — `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. - `412` — Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. - `503` — Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned. - `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)