Box Developer Documentation
Log in
Latest version

Update folder

put
https://api.box.com/2.0
/folders/:folder_id

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more.

Related Guides

Request

bearer [ACCESS_TOKEN]
application/json

Request Headers

stringin headeroptional
1

Ensures this item hasn't recently changed before making changes.

Pass in the item's last observed etag value into this header and the endpoint will fail with a 412 Precondition Failed if it has changed since.

Path Parameters

stringin pathrequired
12345

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folder/123 the folder_id is 123.

The root folder of a Box account is always represented by the ID 0.

Query Parameters

string arrayin queryoptional
id,type,name

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.

Request Body

booleanin bodyoptional
true

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

booleanin bodyoptional
true

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.

object arrayin bodyoptional

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 endpoint.

Passing an empty array [] or null will remove the folder from all collections.

stringin bodyoptional
"11446498"

The unique identifier for this object

stringin bodyoptional
"file"

The type for this object

stringin bodyoptional
"Legal contracts for the new ACME deal"
256

The optional description of this folder

objectin body

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.

stringin bodyoptional
"open"

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.

Value is one of open,collaborators

booleanin bodyoptional
true

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

stringin bodyoptional
"New Folder"

The optional new name for this folder.

objectin body

The parent folder for this folder. Use this to move the folder or to restore it out of the trash.

stringin bodyoptional
"123"

The ID of parent item

stringin bodyoptional
"12346930"

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.

objectin body

Enables the creation of a shared link for a folder.

stringin bodyoptional
"open"

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.

Value is one of open,company,collaborators

stringin bodyoptional
"do-n8t-use-this-Password"

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.

objectin body
booleanin bodyoptional
true

If the shared link allows for downloading of files. This can only be set when access is set to open or company.

string (date-time)in bodyoptional
"2012-12-12T10:53:43-08:00"

The timestamp at which this shared link will expire. This field can only be set by users with paid accounts.

stringin bodyoptional
"my-shared-link"

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.

stringin bodyoptional
"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.

Value is one of synced,not_synced,partially_synced

string arrayin bodyoptional
["approved"]

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.

Response

application/jsonFolder (Full)

Returns a folder object for the updated folder

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.

This call will return synchronously. This holds true even when moving folders with a large a large number of items in all of its descendants. For very large folders, this means the call could take minutes or hours to return.

application/jsonClient error

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.
application/jsonClient error

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.
application/jsonClient error

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.
application/jsonClient error

  • 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.

application/jsonClient error

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.

application/jsonClient error

Returns an error when the operation takes longer than 60 seconds. The operation will continue after this response has been returned.

application/jsonClient error

An unexpected client error.

put
Update folder
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "name": "New folder name"
     }'
TypeScript Gen
await client.folders.updateFolderById(folderToUpdate.id, {
  requestBody: {
    name: updatedName,
    description: 'Updated description',
  } satisfies UpdateFolderByIdRequestBody,
} satisfies UpdateFolderByIdOptionalsInput);
Python Gen
client.folders.update_folder_by_id(
    folder_to_update.id, name=updated_name, description="Updated description"
)
.NET Gen
await client.Folders.UpdateFolderByIdAsync(folderId: folderToUpdate.Id, requestBody: new UpdateFolderByIdRequestBody() { Name = updatedName, Description = "Updated description" });
Swift Gen (Beta)
try await client.folders.updateFolderById(folderId: folderToUpdate.id, requestBody: UpdateFolderByIdRequestBody(name: updatedName, description: "Updated description"))
Java
BoxFolder folder = new BoxFolder(api, "id");
BoxFolder.Info info = folder.new Info();
info.setName("New Name");
folder.updateInfo(info);
Python
updated_folder = client.folder(folder_id='22222').update_info(data={
    'name': '[ARCHIVED] Planning documents',
    'description': 'Old planning documents',
})
print('Folder updated!')
.NET
var requestParams = new BoxFolderRequest()
{
    Id = "11111",
    Name = "My Documents (2017)"
};
BoxFolder updatedFolder = await client.FoldersManager.UpdateInformationAsync(requestParams);
Node
client.folders.update('11111', {name: 'Pictures from 2017'})
    .then(updatedFolder => {
        /* updatedFolder -> {
            type: 'folder',
            id: '11111',
            sequence_id: '1',
            etag: '1',
            name: 'Pictures from 2017',
            created_at: '2012-12-12T10:53:43-08:00',
            modified_at: '2012-12-12T11:15:04-08:00',
            description: 'Some pictures I took',
            size: 629644,
            path_collection: 
            { total_count: 1,
                entries: 
                [ { type: 'folder',
                    id: '0',
                    sequence_id: null,
                    etag: null,
                    name: 'All Files' } ] },
            created_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User'
                login: 'user@example.com' },
            modified_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            owned_by: 
            { type: 'user',
                id: '22222',
                name: 'Example User',
                login: 'user@example.com' },
            shared_link: null,
            parent: 
            { type: 'folder',
                id: '0',
                sequence_id: null,
                etag: null,
                name: 'All Files' },
            item_status: 'active',
            item_collection: 
            { total_count: 1,
                entries: 
                [ { type: 'file',
                    id: '33333',
                    sequence_id: '3',
                    etag: '3',
                    sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
                    name: 'tigers.jpeg' } ],
                offset: 0,
                limit: 100 } }
        */
    });

Response Example

{
  "id": "12345",
  "type": "folder",
  "allowed_invitee_roles": [
    "editor"
  ],
  "allowed_shared_link_access_levels": [
    "open"
  ],
  "can_non_owners_invite": true,
  "can_non_owners_view_collaborators": true,
  "classification": {
    "color": "#FF0000",
    "definition": "Content that should not be shared outside the company.",
    "name": "Top Secret"
  },
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "created_at": "2012-12-12T10:53:43-08:00",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "description": "Legal contracts for the new ACME deal",
  "etag": "1",
  "folder_upload_email": {
    "access": "open",
    "email": "upload.Contracts.asd7asd@u.box.com"
  },
  "has_collaborations": true,
  "is_accessible_via_shared_link": true,
  "is_associated_with_app_item": true,
  "is_collaboration_restricted_to_enterprise": true,
  "is_externally_owned": true,
  "item_collection": {
    "entries": [
      {
        "etag": "1",
        "id": "12345",
        "type": "file",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "name": "Contract.pdf",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "description": "Contract for Q1 renewal",
        "item_status": "active",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "parent": {
          "etag": "1",
          "id": "12345",
          "type": "folder",
          "name": "Contracts",
          "sequence_id": "3"
        },
        "path_collection": {
          "entries": [
            {
              "etag": "1",
              "id": "12345",
              "type": "folder",
              "name": "Contracts",
              "sequence_id": "3"
            }
          ],
          "total_count": 1
        },
        "purged_at": "2012-12-12T10:53:43-08:00",
        "shared_link": {
          "access": "open",
          "download_count": 3,
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "effective_access": "company",
          "effective_permission": "can_download",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_edit": false,
            "can_preview": true
          },
          "preview_count": 3,
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "vanity_name": "my_url",
          "vanity_url": "https://acme.app.box.com/v/my_url/"
        },
        "size": 629644,
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "allowed_invitee_roles": [
          "editor"
        ],
        "classification": {
          "color": "#FF0000",
          "definition": "Content that should not be shared outside the company.",
          "name": "Top Secret"
        },
        "comment_count": 10,
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "expires_at": "2012-12-12T10:53:43-08:00",
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "restricted_to": [
            {
              "object": {
                "etag": "1",
                "id": "12345",
                "type": "folder",
                "name": "Contracts",
                "sequence_id": "3"
              },
              "scope": "item_download"
            }
          ],
          "token_type": "bearer",
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "extension": "pdf",
        "has_collaborations": true,
        "is_accessible_via_shared_link": true,
        "is_associated_with_app_item": true,
        "is_externally_owned": true,
        "is_package": true,
        "lock": {
          "app_type": "office_wopiplus",
          "created_at": "2012-12-12T10:53:43-08:00",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "login": "ceo@example.com",
            "name": "Aaron Levie"
          },
          "expired_at": "2012-12-12T10:53:43-08:00",
          "id": "11446498",
          "is_download_prevented": true,
          "type": "lock"
        },
        "metadata": {
          "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
            }
          }
        },
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true
        },
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "shared_link_permission_options": [
          "can_preview"
        ],
        "tags": [
          "approved"
        ],
        "uploader_display_name": "Ellis Wiggins",
        "version_number": "1",
        "watermark_info": {
          "is_watermarked": true
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000
  },
  "item_status": "active",
  "metadata": {
    "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
      }
    }
  },
  "modified_at": "2012-12-12T10:53:43-08:00",
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "name": "Contracts",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "login": "ceo@example.com",
    "name": "Aaron Levie"
  },
  "parent": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "path_collection": {
    "entries": [
      {
        "etag": "1",
        "id": "12345",
        "type": "folder",
        "name": "Contracts",
        "sequence_id": "3"
      }
    ],
    "total_count": 1
  },
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true
  },
  "purged_at": "2012-12-12T10:53:43-08:00",
  "sequence_id": "3",
  "shared_link": {
    "access": "open",
    "download_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_edit": false,
      "can_preview": true
    },
    "preview_count": 3,
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "vanity_name": "my_url",
    "vanity_url": "https://acme.app.box.com/v/my_url/"
  },
  "size": 629644,
  "sync_state": "synced",
  "tags": [
    "approved"
  ],
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "watermark_info": {
    "is_watermarked": true
  }
}