Create a bucket in your org

POST /v1/s3/buckets

Creates a new bucket in the caller's own namespace and answers 201 with its friendly name and creation time.

The name is validated exactly as sent and never quietly normalised: it must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$, so a mixed-case name is a clean 400 rather than a bucket created as photos that the caller keeps asking for as Photos. A name already in use in the caller's own namespace is 409.

A validated principal is required, and every bucket and key is resolved inside the caller's own org: physical bucket names are derived from the org, so a tenant cannot name another's storage. The operation is billed per call — the balance is checked BEFORE anything is touched, so an unfunded org is refused with nothing done, and the debit happens only after the work succeeds. Object storage that is not configured answers 503 under this subsystem's own name rather than falling through to another.

Request

The document declares no body for POST /v1/s3/buckets. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask the MCP door's describe for post_s3_buckets, which answers from the running route.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

hanzo s3 buckets create

import { Configuration, S3Api } from 'hanzoai';

const api = new S3Api(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postS3Buckets();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import S3Api

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = S3Api(client).post_s3_buckets()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.S3API.PostS3Buckets(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, s3_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = s3_api::post_s3_buckets(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.S3Api;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new S3Api(client).postS3Buckets();

curl -X POST https://api.hanzo.ai/v1/s3/buckets \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_s3_buckets"
         }
       }
     }'

S3 API · All Hanzo APIs · Interactive reference