Create bucket

POST/v1/bucketsbuckets:writeSDK: buckets.create

Provisions a new bucket and queues DNS, certificate, and CloudFront setup in the background. The bucket starts in pending status and transitions to active once provisioning completes — usually within a few minutes.

The response only includes the new bucket's id — call Get bucket to read the full state once you need it.

Body parameters

Name	Type	Default	Description
namerequired	string	—	Display name for the bucket. 1–100 characters.
isManagedDomain	boolean	false	When true, Buckt allocates a managed subdomain. Mutually exclusive with customDomain.
customDomain	string	—	Custom domain to serve the bucket from (e.g. files.example.com). Required when isManagedDomain is false.
region	string	"us-east-1"	AWS region where the underlying S3 bucket is provisioned.
cachePreset	"no-cache" \| "short" \| "standard" \| "aggressive" \| "immutable"	"standard"	CDN cache strategy applied to all objects.
corsOrigins	string[]	[]	Allow-listed origins for browser uploads. Up to 10 entries.
lifecycleTtlDays	number \| null	null	Auto-delete objects this many days after upload. Range 1–3650. null disables expiry.
maxFileSizeBytes	number \| null	null	Reject uploads larger than this size. null applies the default limit for your plan.
allowedMimeTypes	string[] \| null	null	Allow-listed MIME patterns (e.g. "image/png", "image/*"). Up to 50 entries. null allows any type.
optimizationMode	"none" \| "light" \| "balanced" \| "maximum"	"none"	Image optimization aggressiveness. Anything other than none requires a paid plan.
domainConnectProvider	string	—	Provider hint for one-click DNS automation. Ignored when isManagedDomain is true.
awsAccountId	string	—	Bring-your-own-account: provision the bucket in a connected AWS account. Requires a paid plan and a custom domain.

Example request

import { Buckt } from "@buckt/sdk";

const client = new Buckt({ apiKey: process.env.BUCKT_API_KEY });

const { id } = await client.buckets.create({
  name: "Marketing assets",
  customDomain: "files.example.com",
  region: "us-east-1",
  cachePreset: "standard",
});

// Fetch the full bucket once provisioning completes
const bucket = await client.buckets.get(id);

Responses

{
  "data": {
    "object": "bucket",
    "id": "bkt_01H8XYZABCDEFGHJKMNPQRSTVW"
  },
  "error": null,
  "meta": null
}