StorageService API

Package: dodil.k3.storage.v1

StorageService owns bucket control-plane and object metadata/admin operations.

What It Is For

Provision and manage K3 buckets.
Control bucket access policy and CORS.
List object metadata, inspect single objects, delete objects, and issue object URLs.
Provide an AWS S3-compatible storage surface for bucket/object workflows.

AWS S3 Compatibility

StorageService is designed for AWS S3-compatible behavior for core storage operations.

Compatibility highlights:

Bucket/object model follows standard S3 semantics.
Policy actions use S3-style action names (for example s3:GetObject).
Object APIs support familiar patterns: prefix listing, key-based object access, and temporary URL generation.

Practical notes:

K3 keeps compatibility at the storage surface while adding K3-specific domain APIs (source, pipeline, ingest, vector, table).
Route shapes are K3 service routes (not raw S3 REST endpoint parity), so treat K3 API docs as canonical for request paths.

Endpoint Map

Buckets

gRPC method	HTTP route
`CreateBucket`	`POST /admin/buckets`
`ListBuckets`	`GET /admin/buckets`
`GetBucket`	`GET /admin/buckets/:name`
`UpdateBucket`	`PATCH /admin/buckets/:name`
`DeleteBucket`	`DELETE /admin/buckets/:name`

Bucket Policy

gRPC method	HTTP route
`SetBucketPolicy`	`PUT /admin/buckets/:name/policy`
`GetBucketPolicy`	`GET /admin/buckets/:name/policy`
`DeleteBucketPolicy`	`DELETE /admin/buckets/:name/policy`

Bucket CORS

gRPC method	HTTP route
`PutBucketCors`	`PUT /admin/buckets/:name/cors`
`GetBucketCors`	`GET /admin/buckets/:name/cors`
`DeleteBucketCors`	`DELETE /admin/buckets/:name/cors`

Objects

gRPC method	HTTP route
`ListObjects`	`GET /:bucket/objects`
`GetObjectInfo`	`GET /:bucket/objects/:key/info`
`DeleteObject`	`DELETE /:bucket/objects/:key`
`GetObjectUrl`	`GET /:bucket/objects/:key/url`

Key Arguments

Create/Update bucket

Field	Type	Required	Purpose
`name`	string	yes (create)	Bucket identifier, unique per tenant
`description`	string	no	Human-readable bucket summary
`storage_quota_bytes`	int64	no	Quota limit, `0` means unlimited
`access_mode`	enum	no	`PRIVATE`, `PUBLIC`, or `CUSTOM`

List buckets

Field	Type	Required	Purpose
`pagination.page_size`	int32	no	Cursor page size
`pagination.page_token`	string	no	Cursor for next page
`search`	string	no	Case-insensitive name/description match

List objects

Field	Type	Required	Purpose
`bucket`	string	yes	Target bucket
`prefix`	string	no	Prefix filter (`docs/`, `2026/05/`)
`delimiter`	string	no	Folder-like grouping, usually `/`
`max_keys`	int32	no	Max objects to return
`continuation_token`	string	no	Cursor token for next page

Bucket policy statement

Field	Type	Required	Purpose
`sid`	string	no	Statement ID label
`effect`	enum	yes	`ALLOW` or `DENY`
`principal.aws`	string[]	yes	Principals or `*`
`actions`	string[]	yes	S3-style action list
`resources`	string[]	yes	Resource patterns

Get object URL

Field	Type	Required	Purpose
path `:bucket`	string	yes	Target bucket
path `:key`	string	yes	Object key (URL-encoded)
`expires_in_seconds`	int64	no	URL TTL, defaults to `3600`

Examples

Create a bucket


curl -sS -X POST "https://k3.dev.dodil.io/admin/buckets" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "kb-prod",
    "description": "Production knowledge base",
    "access_mode": "BUCKET_ACCESS_MODE_PRIVATE",
    "storage_quota_bytes": 0
  }'

Set bucket policy


curl -sS -X PUT "https://k3.dev.dodil.io/admin/buckets/kb-prod/policy" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "version": "2024-01-01",
      "statements": [
        {
          "sid": "allow-read",
          "effect": "POLICY_EFFECT_ALLOW",
          "principal": {"aws": ["*"]},
          "actions": ["s3:GetObject"],
          "resources": ["arn:aws:s3:::kb-prod/public/*"]
        }
      ]
    }
  }'

List objects by prefix


curl -sS "https://k3.dev.dodil.io/kb-prod/objects?prefix=docs/&max_keys=100" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG"

Get a temporary object URL


curl -sS "https://k3.dev.dodil.io/kb-prod/objects/docs%2Fcontract.pdf/url?expires_in_seconds=900" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG"

Common Use Cases

Create tenant or environment buckets (dev, stage, prod).
Apply explicit policy/CORS before exposing browser downloads.
Build housekeeping jobs using object metadata and delete operations.
Generate short-lived URLs for controlled sharing.

Next: SourceService