Object Storage — API Reference
The Storage primitive (dodil.k3.storage.v1) has two surfaces:
- Admin & metadata — available in both gRPC and HTTP. Bucket lifecycle, S3-style policy, CORS, and the admin object surface (list, info, delete, presigned URL).
- Object byte plane — full S3 protocol via the K3 HTTP gateway:
PUT/GET/HEAD/DELETEdirectly on/:bucket/:key. There is no gRPC equivalent — object bytes don’t flow through the gRPC StorageService.
For the typed domain model (Bucket, ObjectInfo, BucketPolicy, …) see Core Concepts. For headers and the error envelope see Conventions.
Sections
- Buckets —
CreateBucket·GetBucket·ListBuckets·UpdateBucket·DeleteBucket - Policy —
SetBucketPolicy·GetBucketPolicy·DeleteBucketPolicy - CORS —
PutBucketCors·GetBucketCors·DeleteBucketCors - Objects — Byte plane (
PUT/GET/HEADvia S3 protocol) + admin (ListObjects·GetObjectInfo·DeleteObject·GetObjectUrl)
Wire conventions
| HTTP request body | HTTP query / path | gRPC | |
|---|---|---|---|
| Field names | camelCase (pbjson) | snake_case (max_keys, expires_in_seconds) | as in .proto |
| Enums | wire-name strings ("BUCKET_STATUS_ACTIVE") | — | enum |
int64 | JSON strings | strings | int64 |
| All fields | always emitted (no defaults dropped) | — | — |
S3-tool compatibility
The K3 HTTP gateway speaks S3, so standard tooling works:
aws s3 ls s3://kb-prod/ --endpoint-url https://k3.dev.dodil.io
aws s3 cp ./file.pdf s3://kb-prod/docs/file.pdf --endpoint-url https://k3.dev.dodil.ioSee also
- Object Storage — overview
- Core Concepts — the typed entities the API reads/writes
- CLI Guide
- Conventions — auth, headers, error envelope