g7 API Reference

A g7 binding (env.<BINDING>) exposes methods for reading and writing objects in a bucket. There are two binding types: G7Bucket (declared with type = "g7") and FilesBucket (declared with type = "files").

G7Bucket

Bound from a type = "g7" entry in ribo.toml. Use this for arbitrary object storage: uploads, generated assets, cached data, or any binary content.

get

Retrieve an object by key. Returns an object with a body stream and metadata, or null if the key does not exist.

const obj = await env.BUCKET.get("images/avatar.png");

if (obj === null) {
  return new Response("Not found", { status: 404 });
}

return new Response(obj.body, {
  headers: {
    "content-type": obj.httpMetadata?.contentType ?? "application/octet-stream",
    "content-length": String(obj.size),
  },
});

Returned object properties:

head

Check if an object exists and retrieve its metadata, without downloading the body. Returns the same object shape as get() (with body being an empty stream), or null.

const meta = await env.BUCKET.head("reports/2026-05.pdf");
if (meta) {
  console.log(meta.size, meta.uploaded);
}

put

Upload an object. The body can be a string, ArrayBuffer, ReadableStream, or Blob.

await env.BUCKET.put("reports/2026-05.pdf", pdfBuffer, {
  httpMetadata: { contentType: "application/pdf" },
});

// From a request body
await env.BUCKET.put(
  "uploads/" + filename,
  request.body,
  { httpMetadata: { contentType: request.headers.get("content-type") } }
);

Options:

delete

Remove an object by key. Deleting a non-existent key is not an error.

await env.BUCKET.delete("uploads/old-file.png");

list

List objects in the bucket. Returns an object with a objects array.

const { objects } = await env.BUCKET.list();

for (const obj of objects) {
  console.log(obj.key, obj.size);
}

With a prefix filter:

const { objects } = await env.BUCKET.list({ prefix: "uploads/2026/" });

Options:

Returned object shape:

FilesBucket

Bound from a type = "files" entry in ribo.toml (or generated automatically by the static shorthand). Wraps a g7 bucket and adds path-based serving with index and 404 fallback logic.

fetch

Serve a request from the file tree. Applies static site routing rules.

return env.ASSETS.fetch(request);

Routing rules:

get

Retrieve an object by key, returning the raw response (or null if not found). Unlike G7Bucket.get(), this returns a Response object directly.

const res = await env.ASSETS.get("css/style.css");
if (res) {
  return res;
}

Common patterns

Upload from a form

if (request.method === "POST" && url.pathname === "/upload") {
  const form = await request.formData();
  const file = form.get("file"); // File object
  await env.UPLOADS.put(file.name, file.stream(), {
    httpMetadata: { contentType: file.type },
  });
  return Response.json({ ok: true, key: file.name });
}

Proxy with caching headers

const obj = await env.ASSETS.get("data.json");
if (!obj) return new Response("Not found", { status: 404 });

return new Response(obj.body, {
  headers: {
    "content-type": "application/json",
    "cache-control": "public, max-age=3600",
    "etag": obj.etag,
  },
});

Delete all objects with a prefix

const { objects } = await env.BUCKET.list({ prefix: "temp/" });
for (const obj of objects) {
  await env.BUCKET.delete(obj.key);
}

See also

• g7 Overview
• Managing Buckets
• Static Sites
• g7 Limitations