The option and record types the rest of these docs refer to, and the upload phases named in error messages.
Size#
A byte count, never a bit count. A bare number is bytes. String units ignore case, so MB and mb both mean megabytes.
| Units | Base | Example |
|---|---|---|
B, KB, MB, GB, TB | Decimal, powers of 1,000 | "32MB" = 32,000,000 bytes |
KiB, MiB, GiB, TiB | Binary, powers of 1,024 | "32MiB" = 33,554,432 bytes |
For a 32 MiB file limit, use "32MiB" or 33554432. A "32MB" limit is smaller and rejects that file. Existing decimal units keep their values. Bit units such as mbit and Mbps are not supported.
An unparseable size throws where the option is written, not per request. In Go a size is an int64 of bytes written with the unit constants, and blob.ParseSize reads the string form from configuration.
A limit you write by hand takes a size: the max size, the multipart threshold. A measurement you forward is a plain number of bytes: the size option on put, and every size the SDK returns.
formatBytes, exported from every TypeScript entrypoint, always displays decimal byte units, including values supplied as MiB: formatBytes(2_400_000) is 2.4 MB.
Duration#
A span of time. A bare number is seconds; a string takes a unit: ms, s, m, h, d, or a long form (sec, seconds, min, minutes, hr, hours, day, days). A string with no unit is seconds. An unparseable duration throws an error naming the option. In Go a lifetime or window is a time.Duration; only Cache takes the string form.
CacheOption#
One of three words, a duration, or a raw Cache-Control header. The header each one stores is on Caching.
How each SDK types these three: TypeScript, Python, Go.
Records#
Four record shapes come back from the SDK. They nest.
| Record | Fields | Returned by |
|---|---|---|
| Object | path, URL, versioned URL, size, etag, uploaded at | list, copy, move, the JSON update |
| Completed object | an object plus content type | put, the completion callback, a finished browser upload |
| Info | an object plus content type and metadata | info |
| Download | info plus the body | get |
Object fields:
| Field | Description |
|---|---|
| Path | The object’s key. |
| URL | The public object URL. Not set on a private bucket. |
| Versioned URL | The URL with ?v=<etag>, etag percent-encoded. Not set when the URL is not. |
| Size | Bytes. |
| Etag | Storage’s etag, quoted: "9f3c...". |
| Uploaded at | Last modified. |
Across the SDK, blob names a record, never the bytes. Bytes go in and come out as body (content on Python’s get).
The type names and field types in each SDK: TypeScript, Python, Go.
Upload phases#
A direct browser upload makes up to four kinds of request to your upload route. The names appear in error messages and across these docs.
| Phase | When | What your route does |
|---|---|---|
begin | First request, once | Checks constraints, runs the before-upload callback, signs the first URL(s). Never retried. |
parts | Multipart only, as needed | Signs the next batch of part URLs. |
end | Once the bytes landed | Completes the upload, runs the completion callback. Retried by the browser on failure. |
cancel | On cancel() | Aborts the multipart upload, or deletes the single-PUT object. |
Every request and every successful answer carries protocol, the version of this exchange, in the JSON body. It is separate from the package version, so a browser bundle and a server on different SDK releases, or a server written with another server SDK, still understand each other. A missing value means 1, changes are only ever additive, and neither side refuses the other’s version.
The PUTs that carry the bytes go to storage, never to your route. How signing works has the full handshake.