Create a bucket

Stay organized with collections Save and categorize content based on your preferences.

When creating a bucket, you can specify the geographic location for your bucket as well as the default storage class of the bucket.

If you try to create a bucket with an invalid name you will get a 400 Bad Request status code and the body of the error response will have InvalidBucketName in the Code element.

You can only create a bucket in projects for which you have permission to do so. For example, if you have the Storage Admin role on a project, you have the required permission (storage.buckets.create) to create buckets.

Also, because the bucket namespace is global, your bucket name must be unique across the entire Cloud Storage namespace. If your bucket name is in use, you get a 409 Conflict status code and the bucket creation request fails. The body of the error response contains BucketAlreadyExists in the Code element if the bucket already exists in the namespace or it contains a BucketAlreadyOwnedByYou in the Code element if the bucket is owned by you. For more information, see the bucket naming guidelines.

Query string parameters

This request does not typically include query string parameters.

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

In addition to common 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 the acl query string parameter to apply ACLs. 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. If you do not specify a request body, Cloud Storage creates a bucket in the US location with a default storage class of STANDARD.

Element Description
CreateBucketConfiguration Container for create body request.
LocationConstraint A location for the bucket. Can be the name of a single region, predefined dual-region, or multi-region.
customPlacementConfig An object with the location specifications for the bucket. Required for configurable dual-regions.
dataLocations A list of regions that comprise the bucket. Required for configurable dual-regions.
dataLocation One of the regions that comprise the bucket. Required for configurable dual-regions.
StorageClass The default storage class for objects added to the bucket, such as STANDARD, NEARLINE, COLDLINE, or ARCHIVE.
EncryptionConfiguration The container for DefaultKmsKeyName.
DefaultKmsKeyName The name of the Cloud Key Management Service key resource to use by for objects added to the bucket.

Request syntax

PUT / HTTP/1.1
Date: DATE
x-goog-project-id: PROJECT_ID
x-goog-acl: PREDEFINED_ACL
x-goog-bucket-retention-period: TIME_IN_SECONDS


Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The response does not include an XML document in the response body.


The following sample creates a bucket named acme-pets in the specified project. Since no request body is specified, the bucket is created in the US location with a default storage class of STANDARD.


PUT / HTTP/1.1
Date: Mon, 15 Feb  2008 21:30:39 GMT
Content-Length: 0
x-goog-project-id: 123456789123
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg


HTTP/1.1 200 OK
Date: Mon, 15 Feb 2010 12:30:40 GMT
Content-Length: 0