---
title: CreateBucket · S3 API
description: Creates a bucket in the workspace of the key.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# CreateBucket

`PUT /{bucket}`

Creates a bucket in the workspace of the key.

Storage creates the bucket in the location that you send. It answers when the bucket is ready. Names are case-sensitive and unique within the workspace. Another workspace can use the same name.

- Role: Editor or higher.
- Support: supported.
- Auth: AWS Signature Version 4 with your API key. See [S3 API](/api/s3.md).
- Send LocationConstraint as provider:location, for example gcp:us-central1. A new bucket is private and standard class.
- `aws s3 mb` and a CreateBucket call without CreateBucketConfiguration send no location. They return `400 InvalidLocationConstraint`.
- Storage ignores ACL headers such as `x-amz-acl`. To make a bucket public-read, change its permission with [Update a bucket](/api/buckets/update-bucket).

## Example request

```http
PUT /support-tickets HTTP/1.1
Host: wspq7ws2np5l8z4.storage.beta.graphon.sh
x-amz-date: 20261007T093000Z
x-amz-content-sha256: c699442ed9fb88cc061b96390dccb2f021280f0c829147a4557290fc736de2f3
Authorization: AWS4-HMAC-SHA256 Credential=<ACCESS_KEY_ID>/20261007/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=<SIGNATURE>
Content-Length: 163

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LocationConstraint>gcp:us-central1</LocationConstraint>
</CreateBucketConfiguration>
```

## Path parameters

- `bucket` (string, required): The bucket name.

## Headers

- `x-amz-bucket-object-lock-enabled` (boolean, optional): Send `true` to turn on object lock. Object lock also turns on versioning.

## Request body

- `CreateBucketConfiguration` (object, required): The root element.
  - `LocationConstraint` (string, required): Where storage keeps the bytes, as `provider:location`. Values: `gcp:US`, `gcp:NAM4`, `gcp:us-central1`, `gcp:us-east1`, `gcp:us-east4`, `gcp:us-east5`, `gcp:us-south1`, `gcp:us-west1`, `gcp:us-west2`, `gcp:us-west3`, `gcp:us-west4`, `r2:enam`, `r2:wnam`.

## Responses

### 200 · OK

The bucket is ready.

Response headers:

- `Location` (string, optional): The path of the bucket, `/{bucket}`.
- `x-amz-bucket-region` (string, optional): The signing region, `us-east-1`.

```http
HTTP/1.1 200 OK
Location: /support-tickets
x-amz-bucket-region: us-east-1
x-amz-request-id: 4F8A2C7D1E6B4093A5C2D8E1F7B3A960
```

## Errors

Any request can also get the common errors on [S3 API](/api/s3.md).

### 400 · `InvalidBucketName`

The bucket name in the path breaks the naming rules.

Use 1 to 255 ASCII letters, digits, periods, underscores, or hyphens. A name cannot be `.` or `..`.

### 400 · `InvalidLocationConstraint`

The body has no LocationConstraint, or its value is not an accepted location.

Send one of the accepted `provider:location` values in CreateBucketConfiguration.

### 409 · `BucketAlreadyExists`

A bucket in the workspace holds this name but is not active. It is being created, failed to provision, or is being deleted.

Check the bucket with HeadBucket. If provisioning failed, call [Retry bucket provisioning](/api/buckets/retry-bucket-provisioning). Otherwise choose another name.

### 409 · `BucketAlreadyOwnedByYou`

Your workspace already has a bucket with this name.

Use the bucket that exists, or choose another name.

### 403 · `AccessDenied`

The key does not have the role for this operation, or the bucket is in another workspace.

Use a key of the workspace that owns the bucket, with the role above.

### 503 · `ServiceUnavailable`

Storage could not finish creating the bucket in time. The bucket can still become active later.

Check the bucket with HeadBucket. If it is not active, call [Retry bucket provisioning](/api/buckets/retry-bucket-provisioning) or run `graphon buckets retry <name>`. Sending CreateBucket again returns `409 BucketAlreadyExists`.

## Other request languages

### aws CLI

```bash
# The graphon profile from the S3 API overview.
export AWS_PROFILE=graphon

aws s3api create-bucket \
  --bucket support-tickets \
  --create-bucket-configuration LocationConstraint=gcp:us-central1
```

### Python (boto3)

```python
# Replace wspq7ws2np5l8z4 with your workspace ID.
import os

import boto3
from botocore.config import Config

api_key = os.environ["GRAPHON_API_KEY"]
access_key_id = api_key.split("_", 1)[1].split(".")[0]

s3 = boto3.client(
    "s3",
    endpoint_url="https://wspq7ws2np5l8z4.storage.beta.graphon.sh",
    region_name="us-east-1",
    aws_access_key_id=access_key_id,
    aws_secret_access_key=api_key,
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

response = s3.create_bucket(
    Bucket="support-tickets",
    CreateBucketConfiguration={
        "LocationConstraint": "gcp:us-central1",
    },
)
print(response["Location"])
```

### JavaScript (AWS SDK)

```javascript
// Replace wspq7ws2np5l8z4 with your workspace ID.
import { S3Client, CreateBucketCommand } from '@aws-sdk/client-s3';

const apiKey = process.env.GRAPHON_API_KEY;
if (!apiKey) throw new Error('Set GRAPHON_API_KEY.');
const accessKeyId = apiKey.split('_')[1].split('.')[0];

const s3 = new S3Client({
  endpoint: 'https://wspq7ws2np5l8z4.storage.beta.graphon.sh',
  region: 'us-east-1',
  forcePathStyle: true,
  credentials: { accessKeyId, secretAccessKey: apiKey },
});

const response = await s3.send(new CreateBucketCommand({
  Bucket: 'support-tickets',
  CreateBucketConfiguration: {
    LocationConstraint: 'gcp:us-central1',
  },
}));
console.log(response.Location);
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.