Object Storage — API Reference

The Storage primitive (dodil.data.storage.v1, service StorageService) has two surfaces:

Admin & metadata — available in both gRPC and HTTP on api.data.dodil.io. Bucket lifecycle, S3-style policy, CORS, and the admin object surface (list, info, delete, presigned URL).
Object byte plane — full S3 protocol: PUT / GET / HEAD / DELETE on /:bucket/:key, served by the object gateway at https://object.uk-lon-1.dodil.io and by the S3 proxy that backs api.data.dodil.io as a router fallback. 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 / HEAD via S3 protocol) + admin (ListObjects · GetObjectInfo · DeleteObject · GetObjectUrl)

Object destinations are not part of Storage — they moved to the pipeline surface in the pillar split (POST /:bucket/pipelines/object, listed via GET /:bucket/pipelines?facet=object). See Pipelines → API Reference.

Wire conventions

	HTTP request body	HTTP query / path	gRPC
Field names	camelCase (pbjson)	mostly snake_case (`max_keys`, `expires_in_seconds`, `continuation_token`)	as in `.proto`
Enums	wire-name strings (`"BUCKET_STATUS_ACTIVE"`)	—	enum
`int64`	JSON strings	strings	`int64`
All fields	always emitted (no defaults dropped)	—	—

One query-string exception. GET /admin/buckets deserializes its query with camelCase keys — pageSize, pageToken, search (http/api/storage.rs, ListBucketsQuery). The object routes are snake_case. A snake_case page_size on /admin/buckets is silently ignored, not rejected.

S3-tool compatibility

The byte plane is real S3, so reach for the client you already use rather than curl.

aws-cli


export AWS_ENDPOINT_URL=https://object.uk-lon-1.dodil.io   # aws-cli v2.15+
 
aws s3 ls s3://kb-prod/
aws s3 cp ./file.pdf s3://kb-prod/docs/file.pdf

boto3 (Python)


import boto3
from botocore.config import Config
 
s3 = boto3.client(
    "s3",
    endpoint_url="https://object.uk-lon-1.dodil.io",
    aws_access_key_id="<access_key_id>",
    aws_secret_access_key="<secret_access_key>",
    region_name="us-east-1",
    config=Config(s3={"addressing_style": "path"}),
)
 
s3.list_objects_v2(Bucket="kb-prod", Prefix="docs/")
s3.upload_file("./file.pdf", "kb-prod", "docs/file.pdf")

@aws-sdk/client-s3 (Node)


import { S3Client, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({
  endpoint: "https://object.uk-lon-1.dodil.io",
  region: "us-east-1",
  forcePathStyle: true,
  credentials: { accessKeyId: "<access_key_id>", secretAccessKey: "<secret_access_key>" },
});
 
await s3.send(new ListObjectsV2Command({ Bucket: "kb-prod", Prefix: "docs/" }));

rclone


rclone config create dodil s3 \
  provider=Other \
  endpoint=https://object.uk-lon-1.dodil.io \
  region=us-east-1 \
  force_path_style=true \
  access_key_id=<access_key_id> \
  secret_access_key=<secret_access_key>
 
rclone ls dodil:kb-prod
rclone copy ./file.pdf dodil:kb-prod/docs/

Path-style addressing only — virtual-host style (<bucket>.object.uk-lon-1.dodil.io) is not routed. Full support matrix in S3 Compatibility.

Other protocols

The byte plane is full S3 — any S3 client works against https://object.uk-lon-1.dodil.io with SigV4 (aws s3, boto3, rclone, mc); see S3 Compatibility. The same bucket’s structured/vector/graph data lives behind its own wires — Connect & wire adapters.