Create a Bucket

When creating a bucket, you can specify the geographic location for your bucket as well as the 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 are the Editor, Owner, or Storage Admin of a project, you have the required permission (storage.objects.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 will get a 409 Conflict status code and the bucket creation request will fail. The body of the error response will contain BucketAlreadyExists in the Code element if the bucket already exists in the namespace or it will contain a BucketAlreadyOwnedByYou in the Code element if the bucket is owned by you. For more information about bucket and object naming, see Bucket and Object Naming Guidelines.

Query string parameters

This request does not include query string parameters.

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 overwritten 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 storage class equivalent to MULTI_REGIONAL.

Element	Description
CreateBucketConfiguration	Container for create body request.
LocationConstraint	A regional or multi-regional location.
StorageClass	The storage class of the bucket, such as MULTI_REGIONAL, REGIONAL, NEARLINE, or COLDLINE.

Request syntax

PUT / HTTP/1.1
Host: <bucket>.storage.googleapis.com
Date: <date>
Content-Length: <request body length>
Authorization: <authentication string>
x-goog-project-id: <project id>
x-goog-acl: <predefined ACL>
x-goog-bucket-retention-period: <time in seconds>

<CreateBucketConfiguration>
  <LocationConstraint><location></LocationConstraint>
  <StorageClass><storage class></StorageClass>
</CreateBucketConfiguration>

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.

Example

The following sample creates a Multi-Regional Storage bucket named acme-pets in the US location and in the specified project (no request body specified).

Request

PUT / HTTP/1.1
Host: acme-pets.storage.googleapis.com
Date: Mon, 15 Feb  2008 21:30:39 GMT
Content-Length: 0
x-goog-project-id: 123456789123
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
 
<CreateBucketConfiguration>
  <StorageClass>MULTI_REGIONAL</StorageClass>
</CreateBucketConfiguration>

Response

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