Integration

SDK, code snippets, and documentation for integrating with Bucket.

TypeScript SDK

A fully-typed TypeScript SDK for the Bucket S3-compatible API. Uses the Web Fetch API with AWS Signature Version 4 authentication — works in browsers, Cloudflare Workers, Deno, and Bun.

Download SDK (bucket-sdk.ts)

Quick Start

Install the SDK into your project and start using it with your API key.

import { createBucketClient } from "./bucket-sdk";

const bucket = createBucketClient({

  endpoint: "https://s3.your-domain.com",

  accessKey: "YOUR_ACCESS_KEY",

  secretKey: "YOUR_SECRET_KEY",

  region: "auto",

});

// Upload a file

const etag = await bucket.putObject(

  "my-bucket",

  "photos/vacation.jpg",

  imageBuffer,

  { contentType: "image/jpeg" }

);

// List objects

const { objects } = await bucket.listObjects("my-bucket", {

  prefix: "photos/",

});

console.log(objects.map(o => o.key));

// Download a file

const { body, contentType } = await bucket.getObject(

  "my-bucket",

  "photos/vacation.jpg"

);

// Delete an object

await bucket.deleteObject("my-bucket", "temp/old-file.txt");

Your API Keys

Use these access keys to authenticate your SDK. Generate keys from theAPI Keys page.

No API keys found. Create one first.

API Reference

Complete API documentation in a format optimized for LLM agents. Copy with one click and paste into your AI assistant.

# Bucket S3-Compatible API Reference

## Authentication

All requests use AWS Signature Version 4 (SigV4) authentication.

Header: Authorization: AWS4-HMAC-SHA256 Credential=ACCESS_KEY/...

## Base URL

https://s3.your-domain.com

## Endpoints

### List Objects

GET /{bucket}

GET /{bucket}?prefix=photos/&max-keys=100&marker=next-token

Response: XML ListBucketResult with Contents (Key, Size, LastModified, ETag)

Path params: bucket - The bucket name

Query params: prefix - Filter by prefix | max-keys - Max results (default 1000) | marker - Pagination token | delimiter - Group by delimiter (e.g. "/")

### Get Object

GET /{bucket}/{key}

Response: Binary content with Content-Type, Content-Length, ETag headers

Path params: bucket - The bucket name | key - The object key (path to the file)

Headers: Range (optional) - Byte range for partial downloads | If-None-Match (optional) - Conditional request by ETag

### Put Object

PUT /{bucket}/{key}

Body: Raw binary content

Headers: Content-Type (recommended) - MIME type | x-amz-meta-* (optional) - Custom metadata | x-amz-server-side-encryption (optional) - e.g. "AES256"

Response: 200 OK with ETag header

### Delete Object

DELETE /{bucket}/{key}

Response: 204 No Content

### List Buckets

GET /

Response: XML ListAllMyBucketsResult with Buckets (Name, CreationDate)

### Head Object

HEAD /{bucket}/{key}

Response: Headers only (Content-Type, Content-Length, ETag, Last-Modified) - no body

## Error Responses

All errors return XML ErrorResponse with Code, Message, Resource, RequestId

Common codes: AccessDenied (403) | NoSuchKey (404) | NoSuchBucket (404) | InternalError (500)

## SigV4 Signing Example (pseudo)

1. Create canonical request from method, path, headers, payload hash

2. Create string to sign from algorithm, date, credential scope, canonical hash

3. Derive signing key: HMAC(HMAC(HMAC(HMAC("AWS4"+secret, date), region), service), "aws4_request")

4. Sign the string to sign with the derived key

5. Add Authorization header: AWS4-HMAC-SHA256 Credential=AK/date/region/s3/aws4_request, SignedHeaders=host, Signature=...

## Compatibility

Compatible with: AWS CLI (--endpoint-url), rclone (s3 type), boto3, minio client, s3cmd

## Rate Limits

Learn more about rate limits and quotas in the settings page.

S3-Compatible Tools

Bucket works with standard S3-compatible tools. Use your access key and secret key with any of these:

aws configure --profile bucket set aws_access_key_id YOUR_ACCESS_KEY

aws configure --profile bucket set aws_secret_access_key YOUR_SECRET_KEY

aws s3 ls --endpoint-url https://s3.your-domain.com --profile bucket

aws s3 cp file.txt s3://my-bucket/path/file.txt --endpoint-url https://s3.your-domain.com --profile bucket

rclone config

# Choose: n (new remote)

# name: bucket

# type: s3

# provider: Other

# endpoint: https://s3.your-domain.com

# access_key_id: YOUR_ACCESS_KEY

# secret_access_key: YOUR_SECRET_KEY

# Then use:

rclone ls bucket:my-bucket

rclone copy ./local bucket:my-bucket/path/

import boto3

s3 = boto3.client(

    "s3",

    endpoint_url="https://s3.your-domain.com",

    aws_access_key_id="YOUR_ACCESS_KEY",

    aws_secret_access_key="YOUR_SECRET_KEY",

    region_name="auto",

# Upload

s3.upload_file("local.txt", "my-bucket", "path/file.txt")

# List

for obj in s3.list_objects(Bucket="my-bucket", Prefix="path/")["Contents"]:

    print(obj["Key"])