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 a plain Response whose body streams the object's content, or null if the key does not exist.

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

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

return new Response(res.body, {
  headers: {
    "content-type": res.headers.get("content-type") ?? "application/octet-stream",
  },
});

The return value is a standard Response: read the content via res.body (a ReadableStream) or the usual res.text() / res.arrayBuffer() / res.json() helpers, and read metadata from the response headers:

head

Check if an object exists and retrieve its metadata, without downloading the body. Returns a flat { contentType, size, etag } object, or null if the key does not exist.

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

put

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

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

// From a request body
await env.BUCKET.put(
  "uploads/" + filename,
  request.body,
  { 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), just like G7Bucket.get() — but without the routing rules that fetch() applies.

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(), {
    contentType: file.type,
  });
  return Response.json({ ok: true, key: file.name });
}

Proxy with caching headers

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

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

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