CloudStorageBucket

env.<BINDING> (a CloudStorageBucket) is the in-function handle to a Cloud Storage bucket, declared with a [storage.cloudstorage.<name>] block. It’s a pre-authenticated wrapper over the bucket — the runtime injects the credential, so your code holds no S3 access key or secret key.

This reference tracks @telnyx/edge-runtime ≥ 0.5.0. Ranged and conditional reads, batch delete, hierarchical listing, SSE-C, and the version / writeHttpMetadata object fields need ≥ 0.4.0; multipart uploads need ≥ 0.5.0.

interface CloudStorageBucket {
  get(key: string, options?: CloudStorageGetOptions): Promise<CloudStorageObjectBody | CloudStorageObject | null>;
  put(key: string, body: CloudStoragePutBody, options?: CloudStoragePutOptions): Promise<CloudStorageObject | null>;
  head(key: string, options?: CloudStorageOnlyIf): Promise<CloudStorageObject | null>;
  delete(key: string | string[]): Promise<void>;
  list(options?: CloudStorageListOptions): Promise<CloudStorageListResult>;
  createMultipartUpload(key: string, options?: CloudStoragePutOptions): Promise<CloudStorageMultipartUpload>;
  resumeMultipartUpload(key: string, uploadId: string, options?: CloudStoragePutOptions): CloudStorageMultipartUpload;
}

Key behaviors:

Missing keys read as null — get and head resolve to null for a key that doesn’t exist, not an error.
A failed conditional read returns a body-less object — when a get onlyIf precondition isn’t met, get resolves to a plain CloudStorageObject (metadata only, no body and no readers) so you can reuse your cached copy. Check for a body before reading it.
delete is idempotent — deleting a missing key (single or in a batch) succeeds and resolves to void.
put returns partial metadata — the resolved object carries key, etag, httpEtag, version, and any metadata you set, but not size or uploaded. Use head to read those after a write.
Custom metadata keys are lower-cased on read — x-amz-meta-* header names are stored lower-cased, so customMetadata keys come back lower-cased (uploadedBy → uploadedby).
SSE-C applies to US and APAC (ap-southeast-1) region buckets — ssecKey is honored for buckets in US regions.

`get(key, options?)`

Read an object and its body. Returns null if the key does not exist.

const obj = await env.MY_BUCKET.get("uploads/logo.png");
if (obj === null) {
  // not found
} else {
  const bytes = await obj.arrayBuffer();   // consume the body once
  // obj.key, obj.size, obj.etag, obj.httpMetadata, obj.customMetadata, …
}

A successful read returns a CloudStorageObjectBody — a CloudStorageObject plus the body stream and one-shot readers arrayBuffer(), text(), json(), and blob().

type CloudStorageGetOptions = CloudStorageOnlyIf & {
  range?: CloudStorageRange;
  ssecKey?: ArrayBuffer | string;
};

Ranged reads

Pass range to fetch part of an object instead of the whole thing — byte-range streaming, reading a header, or resuming a download. The resolved object echoes the requested range.

interface CloudStorageRange {
  offset?: number;   // start byte
  length?: number;   // number of bytes from offset
  suffix?: number;   // final N bytes (mutually exclusive with offset/length)
}

const head = await env.MY_BUCKET.get("videos/clip.mp4", { range: { offset: 0, length: 1024 } });
const tail = await env.MY_BUCKET.get("videos/clip.mp4", { range: { suffix: 512 } });

Conditional reads

Pass onlyIf to read only when a precondition holds — cache revalidation and “only fetch if changed.” A CloudStorageConditional maps to If-Match / If-None-Match / If-Unmodified-Since / If-Modified-Since; you can also pass a Headers object directly.

interface CloudStorageConditional {
  etagMatches?: string;        // read only if the current etag matches      (If-Match)
  etagDoesNotMatch?: string;   // read only if the current etag differs       (If-None-Match)
  uploadedBefore?: Date;       // read only if unchanged since this time      (If-Unmodified-Since)
  uploadedAfter?: Date;        // read only if changed since this time        (If-Modified-Since)
}

interface CloudStorageOnlyIf {
  onlyIf?: CloudStorageConditional | Headers;
}

// Revalidate a cached copy: fetch the body only if the object changed.
const obj = await env.MY_BUCKET.get("data.json", { onlyIf: { etagDoesNotMatch: cachedEtag } });
if (obj !== null && !("body" in obj)) {
  // precondition failed → not modified; keep using the cached copy
} else if (obj) {
  const fresh = await obj.json();
}

Conditional writes are not supported — onlyIf applies to get/head only.

`put(key, body, options?)`

Write an object. Resolves to a CloudStorageObject describing the write.

type CloudStoragePutBody = ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string;

interface CloudStoragePutOptions {
  httpMetadata?: CloudStorageHTTPMetadata;    // Content-Type, Cache-Control, …
  customMetadata?: Record<string, string>;    // x-amz-meta-* — keys lower-cased on read
  ssecKey?: ArrayBuffer | string;             // SSE-C key (US and APAC region buckets)
}

await env.MY_BUCKET.put("uploads/logo.png", bytes, {
  httpMetadata: { contentType: "image/png", cacheControl: "max-age=3600" },
  customMetadata: { uploadedby: "alice" },
});

// Strings, ArrayBuffers, typed arrays, Blobs, and streams all work
await env.MY_BUCKET.put("notes/today.txt", "hello world");

The resolved object carries key, etag (unquoted MD5 for a single-part write), httpEtag (the quoted, header-ready form), version (when bucket versioning is enabled), and the metadata you set. size and uploaded are not populated on the put result — read them back with head if you need them.

`head(key, options?)`

Read an object’s metadata without its body. Returns null if the key does not exist. Accepts the same onlyIf preconditions as get.

const meta = await env.MY_BUCKET.head("uploads/logo.png");
// meta?.size, meta?.uploaded (Date), meta?.version, meta?.httpMetadata, meta?.customMetadata

Unlike put, head returns the full CloudStorageObject including size and uploaded.

`delete(key | keys)`

Remove one object, or many in a single call. Idempotent — deleting a missing key resolves normally.

// Single key
await env.MY_BUCKET.delete("uploads/logo.png");

// Batch — up to 1000 keys per call
await env.MY_BUCKET.delete(["uploads/a.png", "uploads/b.png", "uploads/c.png"]);

Passing an array maps to a single S3 batch delete. Deleting more than 1000 keys splits into 1000-key batches automatically.

`list(options?)`

Enumerate objects (metadata only — list does not return bodies).

interface CloudStorageListOptions {
  prefix?: string;
  limit?: number;
  cursor?: string;    // from a previous result's `cursor`
  delimiter?: string; // roll up keys sharing a prefix into `delimitedPrefixes`
  include?: Array<"httpMetadata" | "customMetadata">; // opt into per-entry metadata
}

interface CloudStorageListResult {
  objects: CloudStorageObject[];
  delimitedPrefixes: string[];   // "folders" — present when `delimiter` is set
  truncated: boolean;
  cursor?: string;               // present when truncated is true
}

let cursor: string | undefined;
do {
  const page = await env.MY_BUCKET.list({ prefix: "uploads/", limit: 100, cursor });
  for (const obj of page.objects) {
    // obj.key, obj.size, obj.etag, …
  }
  cursor = page.truncated ? page.cursor : undefined;
} while (cursor);

When truncated is true, pass the returned cursor back in list({ cursor }) to fetch the next page. By default a list entry carries only key, size, etag, and uploaded. Pass include to also populate httpMetadata and/or customMetadata on each returned object — a heavier listing, so ask for it only when you need it.

const page = await env.MY_BUCKET.list({ prefix: "uploads/", include: ["httpMetadata", "customMetadata"] });
page.objects[0].httpMetadata?.contentType;   // populated because "httpMetadata" was included

Hierarchical (“folder”) listing

Set delimiter to / to browse one level of a key hierarchy: keys below the current level collapse into delimitedPrefixes, and only keys directly at the level appear in objects.

const page = await env.MY_BUCKET.list({ prefix: "uploads/", delimiter: "/" });
page.delimitedPrefixes;  // e.g. ["uploads/2026/", "uploads/logos/"] — the "subfolders"
page.objects;            // keys that live directly under "uploads/"

Multipart upload

Upload a large object in parts from inside a function — for objects past the Edge Compute request/response size cap, or for parallel/resumable uploads. Available on US and APAC (ap-southeast-1) region buckets.

interface CloudStorageMultipartUpload {
  key: string;
  uploadId: string;
  uploadPart(partNumber: number, body: CloudStoragePutBody, options?: CloudStoragePutOptions): Promise<CloudStorageUploadedPart>;
  complete(parts: CloudStorageUploadedPart[]): Promise<CloudStorageObject>;
  abort(): Promise<void>;
}

interface CloudStorageUploadedPart {
  partNumber: number;
  etag: string;
}

const upload = await env.MY_BUCKET.createMultipartUpload("videos/large.mp4", {
  httpMetadata: { contentType: "video/mp4" },
});

const parts: CloudStorageUploadedPart[] = [];
parts.push(await upload.uploadPart(1, firstChunk));   // every part except the last must be ≥ 5 MiB
parts.push(await upload.uploadPart(2, lastChunk));

const object = await upload.complete(parts);          // returns the assembled CloudStorageObject
// object.etag is the multipart form "<md5>-<partCount>", e.g. "…8a0-2"

createMultipartUpload(key, options?) starts the upload and returns a handle. options takes the same httpMetadata / customMetadata / ssecKey as put.
uploadPart(partNumber, body, options?) uploads one part and returns its { partNumber, etag }. Parts are numbered from 1; every part except the last must be at least 5 MiB.
complete(parts) assembles the object. You may pass the parts in any order — they’re sorted by partNumber.
abort() discards an in-progress upload and its parts.
resumeMultipartUpload(key, uploadId, options?) rebuilds a handle for an existing uploadId (no server round-trip) so you can upload more parts or complete()/abort() from a later invocation.

// Resume an upload started elsewhere, then finish it
const resumed = env.MY_BUCKET.resumeMultipartUpload("videos/large.mp4", uploadId);
parts.push(await resumed.uploadPart(3, moreBytes));
await resumed.complete(parts);

Server-side encryption (SSE-C)

Pass ssecKey on get, put, and multipart calls to encrypt with a customer-provided key. The key is a 256-bit (32-byte) AES key, given as an ArrayBuffer or a 64-character hex string. Supply the same key on read that you used on write; the object exposes ssecKeyMd5 (hex) so you can identify which key encrypted it. SSE-C applies to US and APAC (ap-southeast-1) region buckets.

const key = crypto.getRandomValues(new Uint8Array(32)).buffer;   // keep this safe — it's not stored for you

await env.MY_BUCKET.put("secret.bin", bytes, { ssecKey: key });
const obj = await env.MY_BUCKET.get("secret.bin", { ssecKey: key });
// obj?.ssecKeyMd5 identifies the key; reading without the matching key fails

Object types

interface CloudStorageObject {
  key: string;
  size?: number;
  etag?: string;                              // unquoted (e.g. "5eb63bbbe0…")
  httpEtag?: string;                          // quoted, header-ready (e.g. "\"5eb63bbbe0…\"")
  uploaded?: Date;
  version?: string;                           // object version id (when bucket versioning is enabled)
  httpMetadata?: CloudStorageHTTPMetadata;
  customMetadata?: Record<string, string>;    // keys lower-cased on read
  ssecKeyMd5?: string;                        // hex MD5 of the SSE-C key, when the object is SSE-C encrypted
  range?: CloudStorageRange;                  // the requested range, echoed on a ranged get
  writeHttpMetadata(headers: Headers): void;  // copy the stored Content-Type / Cache-Control / … onto a Headers
}

interface CloudStorageObjectBody extends CloudStorageObject {
  body: ReadableStream;
  bodyUsed: boolean;                          // true once the body has been consumed
  arrayBuffer(): Promise<ArrayBuffer>;
  text(): Promise<string>;
  json(): Promise<unknown>;
  blob(): Promise<Blob>;
}

interface CloudStorageHTTPMetadata {
  contentType?: string;
  cacheControl?: string;
  contentLanguage?: string;
  contentDisposition?: string;
  contentEncoding?: string;
  cacheExpiry?: Date;
}

head and each list entry populate size and uploaded; put’s result does not. The body readers on CloudStorageObjectBody consume the stream once — call a single one per get, and bodyUsed flips to true once you do. writeHttpMetadata is handy for serving an object straight back out of a function with its stored headers:

const obj = await env.MY_BUCKET.get("uploads/logo.png");
if (obj && "body" in obj) {
  const headers = new Headers();
  obj.writeHttpMetadata(headers);            // sets Content-Type, Cache-Control, …
  return new Response(obj.body, { headers });
}

Use a bucket from an Edge Function — declare the binding and get started
Bindings overview — bindings across Telnyx API, Secrets, KV, and Cloud Storage
S3-compatible API reference — the same buckets over HTTP

Overview

Get Started

Concepts

Access via S3 API

Access from Edge Compute

Features

Compatibility & Migration

Platform

API Reference (S3-Compatible)

API Reference (JSON Companion)

For AI Agents

CloudStorageBucket

`get(key, options?)`

Ranged reads

Conditional reads

`put(key, body, options?)`

`head(key, options?)`

`delete(key | keys)`

`list(options?)`

Hierarchical (“folder”) listing

Multipart upload

Server-side encryption (SSE-C)

Object types

​get(key, options?)

​Ranged reads

​Conditional reads

​put(key, body, options?)

​head(key, options?)

​delete(key | keys)

​list(options?)

​Hierarchical (“folder”) listing

​Multipart upload

​Server-side encryption (SSE-C)

​Object types

​Related

`get(key, options?)`

Ranged reads

Conditional reads

`put(key, body, options?)`

`head(key, options?)`

`delete(key | keys)`

`list(options?)`

Hierarchical (“folder”) listing

Multipart upload

Server-side encryption (SSE-C)

Object types

Related