Quickstart

Five minutes from here you’ll have a bucket, an object in it, and a shareable URL to download that object.

This page uses the dodil data CLI for the shortest path to a working object. The same operations are available over raw HTTP (bearer token + JSON) and any S3-compatible SDK (aws s3, boto3, @aws-sdk/client-s3, …).

Prerequisites

You need three things:

The dodil CLI installed locally — see CLI Basics.
A credential — interactive login (below) is the shortest path; for CI / headless runs, issue a Dodil API key instead (dodil auth apikey issue --name ci --role k3.editor — the dk_… secret is shown once; see CLI Basics → API keys) or use service-account credentials.
Network access to three K3 doors: https://api.data.dodil.io (HTTP admin + the anonymous/public S3 route) · rpc.data.dodil.io:443 (gRPC admin) · https://object.uk-lon-1.dodil.io (the S3 byte plane — where object bytes actually go). The CLI resolves the last one as object.<region>.dodil.io; override it with data.object_endpoint in your config, or --local for http://localhost:8092.

Sign in once — this writes ~/.config/dodil/config.yaml so every subsequent dodil data command resolves endpoint, token, and org automatically:


dodil auth login

Opens a browser; for non-interactive / CI, set DODIL_SERVICE_ACCOUNT_ID + DODIL_SERVICE_ACCOUNT_SECRET and run the same command.

1. Verify the connection


dodil data bucket list

Empty result is fine — it confirms auth, org context, and gateway reachability. If this fails, fix it before continuing (most failures are token-expired or wrong org).

2. Create a bucket


dodil data bucket create kb-quickstart -d "My first K3 bucket"

A bucket name is unique within your org. Defaults: access_mode = PRIVATE, no quota. bucket create has no --access-mode flag — flip it afterwards with dodil data bucket update <name> --access-mode public|custom. See Buckets — API Reference for the full shape.

3. Upload your first object

object create uploads via a plain HTTP PUT to the S3 byte plane — the gRPC service has no byte plane, so this is the same wire any S3 client uses. Pick whichever client you already have:

dodil data


echo "hello, k3" > hello.txt
dodil data object create ./hello.txt -b kb-quickstart -k greetings/hello.txt
 
# A whole directory tree — --key becomes the key prefix
dodil data object create ./site --recursive -b kb-quickstart -k site

Note it sends no Content-Type; aws s3 infers one from the file extension.

aws-cli


echo "hello, k3" > hello.txt
aws s3 cp ./hello.txt s3://kb-quickstart/greetings/hello.txt \
  --endpoint-url https://object.uk-lon-1.dodil.io \
  --profile dodil-k3

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.upload_file("hello.txt", "kb-quickstart", "greetings/hello.txt")

Objects uploaded either way are the same first-class K3 objects — see S3 Compatibility for credential setup and Objects — byte plane for the contract.

4. List and inspect


# What's in the bucket
dodil data object list -b kb-quickstart
 
# Metadata for a specific key (size, etag, content-type, per-pipeline index status)
dodil data object show greetings/hello.txt -b kb-quickstart -o json

ObjectInfo returned here is the same type documented in Core Concepts → Object.


URL=$(dodil data object url greetings/hello.txt -b kb-quickstart --expires 3600)
echo "$URL"
curl -s "$URL"

The URL is signed with a K3 token good for 1 hour (default; capped at 24 h — ask for more and you get 24 h). It points at the object endpoint and carries X-K3-Token, X-K3-Expires and X-K3-Org; the HMAC covers org, bucket, key and expiry together, so it grants a GET on exactly that one object and nothing else. Anyone with the link can download it — no auth headers needed. Mirror of GetObjectUrl.

What you just did

Step	Operation	Surface
2	`CreateBucket`	gRPC + HTTP admin
3	S3 `PUT /:bucket/:key`	HTTP byte plane
4	`ListObjects` + `GetObjectInfo`	gRPC + HTTP admin
5	`GetObjectUrl` → signed `GET`	gRPC + HTTP admin + HTTP byte plane

Every successful upload also enters K3’s pipeline plane — if your bucket has matching ingest rules, the object is automatically discovered and routed to a vector index or warehouse. See Pipelines when you’re ready to wire that up.

Cleanup


dodil data object remove greetings/hello.txt -b kb-quickstart
dodil data bucket delete kb-quickstart

DeleteBucket cascades — it does not refuse a non-empty bucket. It purges every object, drops the bucket’s tables/vector/graph data on the plane, releases any reservation, and deletes its rules, ingest jobs and sources before removing the bucket row. There is no confirmation and no undo. The object remove above is tidiness, not a precondition.

Next steps

S3 Compatibility — use aws s3, boto3, or @aws-sdk/client-s3 against the K3 gateway.
Recipes — direct-from-browser upload, multipart for large files, static-site hosting.
Core Concepts — Bucket, ObjectInfo, BucketPolicy, BucketCorsConfiguration, PresignedURL.
API Reference — full gRPC + HTTP contracts per resource.
CLI Guide — every dodil data ... command in detail.