Folder: rename

Renames a folder within a bucket with hierarchical namespace enabled. For details about how the rename operation works, see Rename folders.

Required permissions

The authenticated user must have the following IAM permissions to use this method:

  • storage.folders.rename
    • This permission is needed to rename the source folder.
  • storage.folders.create
    • This permission is needed to create the destination folder.

Request

HTTP request

POST https://storage.googleapis.com/storage/v1/b/bucket/folders/sourcePath/renameTo/folders/destinationPath

In addition tostandard query parameters, the following parameters apply to this method.

To see an example of how to include query parameters in a request, see theJSON API Overview page.

Parameters

Parameter nameValueDescription
Path parameters
bucketstring The parent bucket of the folder.
sourcePathstring The URL-encoded name of the source folder, expressed as a path. For example,src-folder/, URL-encoded assrc-folder%2F.
destinationPathstring The URL-encoded name of the destination folder, expressed as a path. For example,dest-folder/, URL-encoded asdest-folder%2F.
Optional query parameters
ifMetagenerationMatchlong If set, only rename the folder if the source folder's metageneration matches this value.
ifMetagenerationNotMatchlong If set, only rename the folder if the source folder's metageneration doesn't match this value.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns an instance of thelong-running operation in the response body:

{  "name": "string",  "metadata": {object},  "done":boolean,  // Result can include either an error or response:  "error": {object(Status)},  "response": {object(Folder)}}
Property nameValueDescription
namestringThe server-assigned name of the operation.
metadataobject

An object of typegoogle.storage.control.v2.RenameFolderMetadata:

  {    "sourceFolderId": "string",    "destinationFolderId": "string",    "commonMetadata":      {        "createTime": "datetime",        "endTime": "datetime",        "updateTime": "datetime",        "type": "string",        "requestedCancellation":boolean,        "progressPercent":integer,      }  }

Where:

donebooleanIffalse, indicates that the operation is still in progress, and neithererror norresponse is set. Iftrue, it indicates that the operation is completed and eithererror orresponse is set.
errorobjectIf the operation fails, this field is returned in the response body and contains the error details. The rename operation fails if any of the child folders exceed either the maximum folder name length limit or maximum folder depth limit. For information about folder name length and folder depth limits, seeConsiderations.
If a failure occurs, the folders are reverted to their original state prior to the rename attempt. For information about status and error codes returned by this API, see thereference page.
responseobjectIf the operation succeeds, an object of typegoogle.storage.control.v2.Folder is returned.

{  "name": "string",  "metageneration":integer,  "createTime": "datetime"",  "updateTime": "datetime",}

Where:

  • name is the name of the folder resource.
  • metageneration is the metageneration of the folder.
  • createTime is the time when the folder was created.
  • updateTime is the time when the folder was last updated.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.