Sample - Box Platform API
PUT/folders/{folder_id}

Update a folder

Updates a folder, including its name, description, parent, shared link, collaboration settings, and collection membership. Supply only the properties you want to change, and use if-match with the folder's latest etag when you need optimistic concurrency control. Large moves can continue asynchronously after the response is returned.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

3 parameters · 11 body fields
folder_idstringrequired
The unique identifier of the folder to update.
fieldsarray<string>optional
A comma-separated list of attributes to include in the response; when provided, standard fields are not returned unless you request them explicitly.
if-matchstringoptional
The folder's last observed `etag` value for optimistic concurrency control; the update fails if the folder has changed since that value was retrieved.

Optional folder properties to update. Provide only the properties you want to change, except that large moves can require separate requests.

namestringoptional
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`.
descriptionstringoptional
The optional description of this folder.
sync_statestringoptional
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.
Allowed:syncednot_syncedpartially_synced
can_non_owners_invitebooleanoptional
Specifies if users who are not the owner of the folder can invite new collaborators to the folder.
parentobjectoptional
The parent folder to use when moving the folder or restoring it from the trash.
shared_linkobjectoptional
Shared-link settings for the folder; set this value to `null` to remove the shared link.
folder_upload_emailobjectoptional
Settings that enable the folder upload email address; set this value to `null` to disable the address.
tagsarray<string>optional
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_enterprisebooleanoptional
Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.
collectionsarray<Reference>optional
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
can_non_owners_view_collaboratorsbooleanoptional
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.

8 status codes
200Returns the updated folder object. If a large move is still running, the response can be returned while the operation continues asynchronously.
idstringrequired
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`.
etagstringoptional
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.
typestringrequired
The value will always be `folder`.
Allowed:folder
sequence_idobjectoptional
namestringoptional
The name of the folder.
created_atstringoptional
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_atstringoptional
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.
descriptionobjectoptional
sizeintegeroptional
The folder size in bytes. Be careful parsing this integer as its value can get very large.
path_collectionobjectoptional
created_byobjectoptional
modified_byobjectoptional
trashed_atstringoptional
The time at which this folder was put in the trash.
purged_atstringoptional
The time at which this folder is expected to be purged from the trash.
content_created_atstringoptional
The date and time at which this folder was originally created.
content_modified_atstringoptional
The date and time at which this folder was last updated.
owned_byobjectoptional
shared_linkobjectoptional
folder_upload_emailobjectoptional
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`.
parentobjectoptional
item_statusstringoptional
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.
Allowed:activetrasheddeleted
item_collectionobjectoptional
sync_stateobjectoptional
has_collaborationsbooleanoptional
Specifies if this folder has any other collaborators.
permissionsobjectoptional
tagsobjectoptional
can_non_owners_inviteobjectoptional
is_externally_ownedbooleanoptional
Specifies if this folder is owned by a user outside of the authenticated enterprise.
metadataobjectoptional
is_collaboration_restricted_to_enterpriseobjectoptional
allowed_shared_link_access_levelsarray<SharedLinkAccessLevel>optional
The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder. The list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level.
allowed_invitee_rolesarray<string>optional
A list of the types of roles that user can be invited at when sharing this folder.
watermark_infoobjectoptional
is_accessible_via_shared_linkbooleanoptional
Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.
can_non_owners_view_collaboratorsbooleanoptional
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.
classificationobjectoptional
is_associated_with_app_itembooleanoptional
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.
collectionsarray<Collection>optional
The collections that this folder belongs to. For more information, see the [collections guide](https://developer.box.com/guides/collections).
400Returned when parameters are missing or invalid, the folder name violates naming rules, the description exceeds 256 characters, a folder lock prevents a move, or a shared-link password is set with `open` access.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returned when you do not have the required access or application scope, a policy prevents the action, or the request contains too many actions.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
404Returned when the folder or parent folder cannot be found, or you do not have access to it.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
409Returned when a source or destination folder is temporarily locked, or a folder with the same name already exists in the parent folder.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
412Returned when the `if-match` value does not match the folder's current `etag`.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
503Returned when the operation takes longer than 600 seconds; the operation continues after the response is returned.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned when parameters are invalid, the folder name violates naming rules, the description exceeds 256 characters, or a shared-link password is used with open access. A 403, 404, or 409 is returned when access, policy, existence, naming, or temporary-lock conditions prevent the update. A 412 indicates that if-match does not match the current etag, while a 503 indicates that the operation has continued beyond 600 seconds.