Create a bucket

To create a bucket, you make a PUT request that includes an x-goog-project-id header, and you optionally include bucket settings such as the bucket's location and default storage class. Note that certain settings, 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 can only be specified in a metadata update request after bucket creation.

Your bucket name must be unique across the global Cloud Storage namespace. If your bucket name is in use, you get a 409 Conflict error, and the bucket creation request fails. Similarly, requests that attempt to create a bucket with an invalid name fail. For more information, see bucket naming guidelines.

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.

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-object-lock-enabled`	The boolean determining if object 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. If you don't 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`	Container for the `dataLocations` element. If present in the request, the `LocationConstraint` element must use a valid multi-region code.
`DataLocations`	Container for specifying the locations to use if the request creates a bucket in a configurable dual-region.
`DataLocation`	One of the regions to use for the configurable dual-region. If used, exactly two `dataLocation` elements are required in the request.
`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
Host: BUCKET_NAME.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-object-lock-enabled: BOOLEAN
x-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 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 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.

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

Response

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