04 · api reference

S3 API reference

nabz/s3 speaks AWS Signature Version 4 over https://cloud-s3.nabzclan.vip. Path-style addressing, region us-nyc-a1-main. Drop in any S3 SDK — the surface below is exactly what's wired.

connection
sigv4
bash
endpoint  https://cloud-s3.nabzclan.vip
region    us-nyc-a1-main
signature aws4-hmac-sha256  (Authorization header OR query presign)
style     path
operations
10 · wired
methodpath · descriptionname
GET
/
List buckets the key can see. Banner text when unsigned.
ListBuckets
GET
/{bucket}
List object keys. Supports prefix, max-keys, start-after.
ListObjectsV2
PUT
/{bucket}
Create a bucket in the workspace default region. Idempotent.
CreateBucket
HEAD
/{bucket}
Existence + region header (dispatched via GET in Hono).
HeadBucket
DELETE
/{bucket}
Delete an empty bucket. 409 if it still has objects.
DeleteBucket
GET
/{bucket}/{key}
Download. Honors bandwidth quota, SSE header, website index/error.
GetObject
PUT
/{bucket}/{key}
Upload. Inherits bucket SSE mode; recomputes bucket totals.
PutObject
HEAD
/{bucket}/{key}
Metadata only — content-type, length, etag, last-modified.
HeadObject
DELETE
/{bucket}/{key}
Soft-delete (versioning-aware) + bucket aggregate refresh.
DeleteObject
OPTIONS
/{bucket}[/{key}]
Answered without SigV4; matched against the bucket CORS rules.
CORS preflight
error codes you'll see
  • 403 AccessDenied — missing/invalid signature, or key not scoped to the bucket.
  • 403 SignatureDoesNotMatch — secret or canonical request mismatch (incl. expired/forged presign).
  • 404 NoSuchBucket / NoSuchKey — not found within the caller's org.
  • 409 BucketNotEmpty — DeleteBucket on a non-empty bucket.
  • 503 SlowDown — workspace or per-key bandwidth quota exhausted; carries Retry-After.
  • 501 NotImplemented — STREAMING-AWS4 signed payload (use UNSIGNED-PAYLOAD or normal signing).
signing a request

Most SDKs do this for you. Manual signing follows the AWS SigV4 spec verbatim — header form below; query-string presign uses the same canonical request with UNSIGNED-PAYLOAD.

bash
# canonical request (header form)
PUT
/my-bucket/hello.txt

host:cloud-s3.nabzclan.vip
x-amz-content-sha256:<sha256 of body>
x-amz-date:20260516T120000Z

host;x-amz-content-sha256;x-amz-date
<sha256 of body>
roadmap
not yet wired

Multipart upload (CreateMultipartUpload / UploadPart / CompleteMultipartUpload) and virtual-host–style addressing are planned but not implemented yet. For large objects today, a single PutObjectstreams up to the 5 GB nginx body limit. We'd rather list nothing than list a 501.