List buckets

Lists the caller org's own buckets.

GET /v1/s3/buckets

S3 → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/s3/buckets`
Method	`GET`
Operation	`get_s3_buckets`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Lists the caller org's own buckets.

Only the caller's: every bucket is physically named under a per-org prefix and the listing strips that prefix, so a tenant sees friendly names and another tenant's buckets are not in the answer at all. Another org's bucket is not refused but INVISIBLE, so this cannot be used to learn that a name is taken elsewhere.

Billed per call: the balance is checked BEFORE anything is touched, so an unfunded org is refused with nothing done, and the debit lands only once the work has succeeded.

Request

GET /v1/s3/buckets takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	s3.bucketList	ok
`default`	problem-details	refused

200 body — 4 fields.

Field	In	Type	Always	Description
`buckets`	body	s3.bucketItem[]	—	Buckets are the caller org's buckets, friendly names, oldest first as the store returns them.
`buckets[].createdAt`	body	integer (int64)	—	unix seconds
`buckets[].name`	body	string	—	friendly name
`total`	body	integer (int64)	—	Total is how many buckets this org has.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo s3 buckets list

.ts

.py

.go

.rs

.java

import { Configuration, S3Api } from 'hanzoai';

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

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).get_s3_buckets()

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

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

use hanzo_client::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::get_s3_buckets(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

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

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

MCP reaches s3 through the s3 tool, which names its 6 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

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

Was this page useful?

PreviousGet uploads NextList health