Create a bucket
To create a bucket, you make aPUT request that includes anx-goog-project-id header, and you include bucket settings such as the bucket'slocation and default storage class in the request body. Note that certainsettings, such as a bucket's location, can only be set at creation time.Additionally, the XML API does not support all settings at bucket creation time,such as a bucket's Object Lifecycle Management configuration. Such settings canonly be specified in ametadata update request after bucket creation.
Your bucket name must be unique across the global Cloud Storagenamespace. If your bucket name is in use, you get a409 Conflict error, andthe bucket creation request fails. Similarly, requests that attempt to create abucket with an invalid name fail. For more information, seebucket naming guidelines.
You can only create a bucket in projects for which you havepermission todo so. For example, if you have theStorage Admin role on a project, youhave the required permission (storage.buckets.create) to create buckets.
Query string parameters
This request does not typically include query string parameters.
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
In addition tocommon request headers, the following can be used.
| Header | Description | Required |
|---|---|---|
x-goog-acl | The predefined access control list (ACL) that you want to apply to the bucket. Do not use if you are using theacl query string parameter to apply ACLs. | No |
x-goog-bucket-object-lock-enabled | The boolean determining ifobject retention is enabled for the bucket. | No |
x-goog-bucket-retention-period | The time, in seconds, that objects in the bucket must be retained before they can be replaced or deleted. | No |
x-goog-project-id | The project ID of a project. Required unless you have set the default project for interoperable access. | No |
Request body elements
The following request body elements are applicable when creating a bucket. Ifyou don't specify a request body, Cloud Storage creates a bucket in theUSlocation with a default storage class ofSTANDARD.
| Element | Description |
|---|---|
CreateBucketConfiguration | Container for create body request. |
LocationConstraint | Alocation for the bucket. Can be the name of a single region, predefined dual-region, or multi-region. |
CustomPlacementConfig | Container for thedataLocations element. If present in the request, theLocationConstraint element must use avalid location code. |
DataLocations | Container for specifying the locations to use if the request creates a bucket in aconfigurable dual-region. |
DataLocation | One of theregions to use for the configurable dual-region. If used, exactly twodataLocation elements are required in the request. |
StorageClass | The defaultstorage class for objects added to the bucket, such asSTANDARD,NEARLINE,COLDLINE, orARCHIVE. |
EncryptionConfiguration | The container forDefaultKmsKeyName. |
DefaultKmsKeyName | The name of theCloud Key Management Service key resource to use by for objects added to the bucket. |
Request syntax
PUT / HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHAuthorization:AUTHENTICATION_STRINGx-goog-project-id:PROJECT_IDx-goog-acl:PREDEFINED_ACLx-goog-bucket-object-lock-enabled:BOOLEANx-goog-bucket-retention-period:TIME_IN_SECONDS<CreateBucketConfiguration> <LocationConstraint>LOCATION</LocationConstraint> <CustomPlacementConfig> <DataLocations> <DataLocation>REGION_1</DataLocation> <DataLocation>REGION_2</DataLocation> </DataLocations> </CustomPlacementConfig> <StorageClass>STORAGE_CLASS</StorageClass> <EncryptionConfiguration> <DefaultKmsKeyName>KEY_RESOURCE</DefaultKmsKeyName> <EncryptionConfiguration></CreateBucketConfiguration>
Response headers
The request can return a variety of response headers depending on the requestheaders you use.
Response body elements
The response does not include an XML document in the response body.
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 2026-02-19 UTC.