Upload Files
The simplest case: one file, one project, one folder.
The SDK does five things behind the scenes:
- Hashes the file (SHA-256, 16 hex chars) — used as the S3 staging key.
- Detects
kind="video"andContent-Type: video/mp4from the.mp4extension. - Streams the bytes to S3 in 10 MB multipart chunks via presigned URLs. Bytes never traverse the BSS server.
- Registers a
Filerecord in BSS. - Creates a
kind="video"Node in the tree at/session-042/camera/front/video.mp4, auto-creating thecamera/frontfolders along the way.
Multiple uploads share the context
The Prefix context manager scopes every call inside the block — project, episode (= last segment of prefix), and base path. Three uploads, three different sub-folders, one episode:
Resulting tree:
Auto-detected kinds
| Extension | Detected kind |
|---|---|
.mp4 .mkv .mov .webm | video |
.wav .mp3 .aac .opus .flac | audio |
.jpg .png .webp .gif .bmp .tiff | image |
.vtt .srt | text-track |
.jsonl | label-track |
.parquet | parquet |
.csv | csv |
.npy .npz | npy |
.json | json |
.txt .md .log | text |
| anything else | file |
The kind string is free-form. Pass type="my-kind" to override detection or label something the SDK doesn't know about:
Without a Prefix context
Pass project and prefix directly. Useful for one-off scripts.
The episode is taken from the Prefix context (or, equivalently, the last segment of the prefix= arg above). Without a Prefix context the file lands directly under the project — prefix= only sets the folder path, not an episode wrapper. For the episode + sub-folder pattern, use Prefix:
What you can do next
- Upload an Episode — bulk-upload a directory of mixed files
- Bindrs — curate files across folders into named collections
- Download Files — pull files, folders, or whole episodes back