Quickstart
Buckt gives your users branded S3 buckets on demand. This guide walks you from zero to a bucket with a file in it in under five minutes.
Prerequisites
Install the SDK
pnpm add @buckt/sdknpm install @buckt/sdkyarn add @buckt/sdkAuthenticate
Every request needs an API key. Pass it as a Bearer token (HTTP) or as the constructor option (SDK).
curl https://api.buckt.dev/v1/buckets \
-H "Authorization: Bearer $BUCKT_API_KEY"import { Buckt } from "@buckt/sdk";
const client = new Buckt({ apiKey: process.env.BUCKT_API_KEY });Create a bucket
Buckets are the top-level container for your files. Each bucket gets a unique ID you'll reference in every file operation.
curl https://api.buckt.dev/v1/buckets \
-X POST \
-H "Authorization: Bearer $BUCKT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "my-bucket", "region": "us-east-1" }'const bucket = await client.buckets.create({
name: "my-bucket",
region: "us-east-1",
});Response 201
{
"id": "bkt_01H8XYZABCDEFGHJKMNPQRSTVW",
"name": "my-bucket",
"region": "us-east-1",
"status": "provisioning",
"createdAt": "2026-04-24T19:00:00Z"
}Upload a file
Use the bucket ID from the previous step. The path after /files/ becomes the
object key.
curl https://api.buckt.dev/v1/buckets/bkt_01H8XYZ.../files/images/logo.png \
-X PUT \
-H "Authorization: Bearer $BUCKT_API_KEY" \
-H "Content-Type: image/png" \
--data-binary @logo.pngimport { readFile } from "node:fs/promises";
const buffer = await readFile("logo.png");
await client.files.upload(bucket.id, "images/logo.png", buffer, "image/png");Response 201
{
"key": "images/logo.png",
"size": 24531,
"contentType": "image/png",
"uploadedAt": "2026-04-24T19:01:00Z"
}List files
curl https://api.buckt.dev/v1/buckets/bkt_01H8XYZ.../files \
-H "Authorization: Bearer $BUCKT_API_KEY"const files = await client.files.list(bucket.id);Response 200
{
"data": [
{
"key": "images/logo.png",
"size": 24531,
"contentType": "image/png",
"uploadedAt": "2026-04-24T19:01:00Z"
}
],
"hasMore": false
}