Browse one level of a bucket

GET /v1/s3/buckets/{bucket}/objects

Lists one folder level of a bucket: each entry's key, whether it is a folder, its size, last-modified time and ETag. prefix scopes the read to a sub-folder.

Keys come back RELATIVE to the requested prefix, not absolute, which is what lets a client render a breadcrumb without re-deriving it. The default is the folder view — sub-prefixes are returned as directory entries — and recursive=true flattens it to every key beneath the prefix instead.

The listing is bounded at 1000 entries so a large bucket cannot exhaust memory; treat a full page as "there may be more" rather than as the whole bucket.

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

1 field.

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 objects list <bucket>

import { Configuration, S3Api } from 'hanzoai';

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

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_by_bucket_objects(bucket='bucket')

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

resp, _, err := client.S3API.GetS3BucketsByBucketObjects(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::get_s3_buckets_by_bucket_objects(&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).getS3BucketsByBucketObjects();

curl https://api.hanzo.ai/v1/s3/buckets/<bucket>/objects \
  -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