# Storage

> Buckets of files by key, private by default, with signed links a page can use, uploads of any size in parts, public URLs and S3-compatible access.

A **bucket** holds files by key: uploads, generated reports, images, anything that isn't rows in a [database](https://www.noclick.com/docs/guide/databases.md). A bucket is private by default. Your code reads and writes it with your key, hands a file to someone with a signed link that expires, or makes the whole bucket public for assets a site serves. An agent can keep its files in one, as its tools.

## Create a bucket

```python
import noclick

bucket = noclick.Bucket.from_name("uploads", create_if_missing=True)
```

```ts
import { Bucket } from "noclick";

const bucket = Bucket.fromName("uploads", { createIfMissing: true });
```

`from_name` with `create_if_missing=True` creates the bucket on first use and finds it after that; one that already exists is used as it is. `create` makes one outright and raises `noclick.Conflict` if the name is taken. A name is 1 to 64 letters, digits and `. _ -`. Pass `public=True` for a bucket whose files anyone can read:

```python
assets = noclick.Bucket.create("public-assets", public=True)
```

```ts
import { Bucket } from "noclick";

const assets = await Bucket.create("public-assets", { public: true });
```

A name is unique for each user, and for your account. Created inside `as_user`, a bucket belongs to that user and bills to it, and a call acting for that user reaches it (a call for the account reaches the account's). See [Users](https://www.noclick.com/docs/guide/users.md).

`region=` places its files in a [region](https://www.noclick.com/docs/guide/regions.md), for good (your account's default, else `us-east`): `region="eu"` for files kept in Europe. Object storage takes the region as a location hint, making the bucket there when it has room there, so it's where your files are kept rather than a legal promise of residency.

## Store and read files

A key is a path-like name, such as `invoices/0042.pdf`. `put` stores bytes, text or an open binary file at a key, replacing what was there:

```python
import noclick

bucket = noclick.Bucket.from_name("uploads", create_if_missing=True)
stored = bucket.put("invoices/0042.pdf", b"%PDF-1.7 ...", content_type="application/pdf")
print(stored.size, stored.etag)

with open("report.csv", "rb") as f:
    bucket.put("reports/2026-09.csv", f, metadata={"user": "acme", "source": "nightly"})
```

```ts
import { readFile } from "node:fs/promises";
import { Bucket } from "noclick";

const bucket = Bucket.fromName("uploads", { createIfMissing: true });
const stored = await bucket.put("invoices/0042.pdf", new TextEncoder().encode("%PDF-1.7 ..."), { contentType: "application/pdf" });
console.log(stored.size, stored.etag);

await bucket.put("reports/2026-09.csv", await readFile("report.csv"), { metadata: { user: "acme", source: "nightly" } });
```

`content_type` is guessed from the key's extension when you leave it out. `metadata` is up to 2 KB of your own ASCII string pairs, kept with the file (their names come back lowercased). One `put` carries up to 100 MB; send bigger files straight from where they are with a signed upload link (below), or [in parts](https://www.noclick.com/docs/guide/storage.md#upload-a-big-file-in-parts) past 5 GB.

```python
pdf = bucket.read("invoices/0042.pdf")       # bytes
info = bucket.head("invoices/0042.pdf")      # size, content_type, etag, metadata, updated_at
bucket.remove("invoices/0042.pdf")
```

```ts
const pdf = await bucket.read("invoices/0042.pdf");       // a Uint8Array
const info = await bucket.head("invoices/0042.pdf");      // size, contentType, etag, metadata, updatedAt
await bucket.remove("invoices/0042.pdf");
```

`read` and `head` raise `noclick.NotFound` for a key that isn't there. `remove` on a missing key does nothing, so it's safe to repeat.

## List files

`objects` lists the files whose keys start with a prefix, in key order:

```python
for obj in bucket.objects(prefix="invoices/"):
    print(obj.key, obj.size, obj.updated_at)
```

```ts
for (const obj of await bucket.objects({ prefix: "invoices/" })) {
  console.log(obj.key, obj.size, obj.updatedAt);
}
```

A `/` in a key is only part of its name, but you can walk a bucket like folders: with `delimiter="/"`, everything below the next `/` is rolled up into one entry whose `is_folder` is true.

```python
for entry in bucket.objects(prefix="invoices/", delimiter="/"):
    print(entry.key, "folder" if entry.is_folder else entry.size)
```

```ts
for (const entry of await bucket.objects({ prefix: "invoices/", delimiter: "/" })) {
  console.log(entry.key, entry.isFolder ? "folder" : entry.size);
}
```

`objects` fetches every page for you (pass `limit` to stop early). `objects_page` gives one page at a time, with a `next_cursor` to pass back as `cursor`.

## Put and read files from an MCP client

A client that can only make tool calls, such as Claude Desktop or ChatGPT on the [MCP server](https://www.noclick.com/docs/guide/mcp.md), can't send a file's bytes or read them back over HTTP. It puts a file of up to 5 MB inside the call instead, as JSON: `content` holds its text, or its bytes in base64 with `"encoding": "base64"`, beside the `key`, `content_type` and `metadata` a `put` takes. These are `api_call`'s arguments, where `bucket:notes` names the bucket:

```json
{"operation": "buckets_objects_replace", "arguments": {"bucket_id": "bucket:notes", "key": "todo.txt", "content": "Buy milk", "content_type": "text/plain"}}
```

`view: "content"` reads a file back the same way: its size, type, etag and metadata, with `content` and `encoding`, its text when the file is UTF-8 and base64 otherwise, which `buckets_objects_replace` takes back as they are:

```json
{"operation": "buckets_objects_list", "arguments": {"bucket_id": "bucket:notes", "key": "todo.txt", "view": "content"}}
```

Over the [HTTP API](https://www.noclick.com/docs/guide/http-api.md#volumes-and-buckets) it's the same JSON, as an `application/json` body of `PUT /v1/buckets/{id}/objects?key=` and the answer to `GET /v1/buckets/{id}/objects?key=&view=content` (a JSON file's own bytes go as `application/octet-stream`). A file over 5 MB is refused in the call, saying so: a `PUT` [signed link](https://www.noclick.com/docs/guide/storage.md#hand-out-a-link) uploads it from wherever it is, and a `GET` link reads it. The SDKs move a file's bytes directly, so your code needs none of this.

## Hand out a link

A private file is reached with a **signed link**: a URL that works without a NoClick key until it expires. Give one to a user to download a file:

```python
link = bucket.signed_url("invoices/0042.pdf", expires_in=3600)
```

```ts
const link = await bucket.signedUrl("invoices/0042.pdf", { expiresIn: 3600 });
```

A `PUT` link lets a browser upload straight into the bucket, so the file never passes through your server. With `content_type`, the upload must send that type:

```python
upload = bucket.signed_url("avatars/u42.png", method="PUT", expires_in=600, content_type="image/png")
```

```ts
const upload = await bucket.signedUrl("avatars/u42.png", { method: "PUT", expiresIn: 600, contentType: "image/png" });
```

```
await fetch(upload, { method: "PUT", body: file, headers: { "Content-Type": "image/png" } });
```

A page on any site can use a bucket's links straight from the browser: every bucket lets a page `GET`, `HEAD` and `PUT` through its links, with any headers, and read the `ETag` and range headers they answer with. The link is what lets it in, so there's nothing to set up. A new bucket takes a few seconds before a browser's first request through its links goes through.

A link lasts from 60 seconds to a week, and anyone who has it can use it until then, so hand it only to whoever needs it. A `PUT` link takes up to 5 GB, so it's also how your own code stores a file bigger than one `put` carries, such as a two-hour recording to [transcribe](https://www.noclick.com/docs/guide/ai.md#transcription):

```python
import httpx

import noclick

recordings = noclick.Bucket.from_name("recordings", create_if_missing=True)
upload = recordings.signed_url("calls/2026-09-30.mp3", method="PUT", expires_in=3600, content_type="audio/mpeg")
with open("call.mp3", "rb") as f:
    httpx.put(upload, content=f, headers={"Content-Type": "audio/mpeg"}).raise_for_status()
words = noclick.AI.transcribe(recordings.signed_url("calls/2026-09-30.mp3"))
```

```ts
import { readFile } from "node:fs/promises";
import { AI, Bucket } from "noclick";

const recordings = Bucket.fromName("recordings", { createIfMissing: true });
const upload = await recordings.signedUrl("calls/2026-09-30.mp3", { method: "PUT", expiresIn: 3600, contentType: "audio/mpeg" });
const sent = await fetch(upload, { method: "PUT", body: await readFile("call.mp3"), headers: { "Content-Type": "audio/mpeg" } });
if (!sent.ok) throw new Error(`Upload failed: ${sent.status}`);
const words = await AI.transcribe(await recordings.signedUrl("calls/2026-09-30.mp3"));
```

## Upload a big file in parts

A file bigger than a `PUT` link carries (5 GB), or one a page sends a piece at a time so that a dropped connection costs one piece rather than the whole file, goes up in parts. Your code starts the upload and signs a `PUT` link for each part. Whoever has the file sends each part to its link, which answers with the part's `ETag` header. Your code then joins the parts by those ETags:

```python
import os

import httpx

import noclick

part = 64 * 1024 * 1024
recordings = noclick.Bucket.from_name("recordings", create_if_missing=True)
upload = recordings.start_upload("calls/all-hands.mp4", content_type="video/mp4")
count = -(-os.path.getsize("all-hands.mp4") // part)
links = recordings.upload_part_urls("calls/all-hands.mp4", upload.upload_id, range(1, count + 1))
etags = {}
with open("all-hands.mp4", "rb") as f:
    for number in range(1, count + 1):
        sent = httpx.put(links[number], content=f.read(part))
        sent.raise_for_status()
        etags[number] = sent.headers["ETag"]
stored = recordings.complete_upload("calls/all-hands.mp4", upload.upload_id, etags)
print(stored.size)
```

```ts
import { Bucket } from "noclick";

// Your server: start the upload and sign a link for each part the page will send.
const manuals = Bucket.fromName("manuals", { createIfMissing: true });
const upload = await manuals.startUpload("b737/fcom.pdf", { contentType: "application/pdf" });
const links = await manuals.uploadPartUrls("b737/fcom.pdf", upload.uploadId, [1, 2, 3, 4], { expiresIn: 3600 });
// ...the page sends each part and returns the ETags it got back...
const stored = await manuals.completeUpload("b737/fcom.pdf", upload.uploadId, etags);
```

The page sends each 16 MiB slice of the file to its link, straight to the bucket, and keeps the `ETag` each answer carries:

```
const size = 16 * 1024 * 1024;
const etags = {};
for (const [number, url] of Object.entries(links)) {
  const start = (Number(number) - 1) * size;
  const sent = await fetch(url, { method: "PUT", body: file.slice(start, start + size) });
  if (!sent.ok) throw new Error(`Part ${number} failed: ${sent.status}`);
  etags[number] = sent.headers.get("ETag");
}
```

Each part is 5 MiB to 5 GiB, every part but the last the same size, and an upload takes up to 10,000 parts. A part sent again replaces the one before, so a part that fails is sent again; sign more links if they expire. Nothing is at the key until `complete_upload`, which replaces what was there and keeps it as an [earlier version](https://www.noclick.com/docs/guide/undo.md), as `put` does. Parts that can't be joined raise `noclick.InvalidRequest` saying why: a wrong ETag, a part but the last under 5 MiB, or parts but the last of different sizes. `abort_upload` drops an upload and its parts, and one left unfinished is dropped after 7 days.

This is how an app's own code moves big files: [S3 credentials](https://www.noclick.com/docs/guide/storage.md#use-s3-tools) are a person's, and an app's deployment is refused them.

## Tell a queue about new files

`notify` puts a message on a [queue](https://www.noclick.com/docs/guide/queues.md) for every file stored under a prefix, however it arrived: `put`, a `PUT` link, an upload in parts or S3 tools. A worker, or an agent with an `OnQueue` trigger, then picks each upload up:

```python
import noclick

recordings = noclick.Bucket.from_name("recordings", create_if_missing=True)
new_calls = noclick.Queue.from_name("new-recordings", create_if_missing=True)
recordings.notify(new_calls, prefix="calls/")

for msg in new_calls.iterate():
    link = recordings.signed_url(msg.body["key"])
    print(noclick.AI.transcribe(link).text)
    msg.ack()
```

```ts
import { AI, Bucket, Queue } from "noclick";

const recordings = Bucket.fromName("recordings", { createIfMissing: true });
const newCalls = Queue.fromName("new-recordings", { createIfMissing: true });
await recordings.notify(newCalls, { prefix: "calls/" });

for await (const msg of newCalls.iterate()) {
  const { key } = msg.body as { key: string };
  const link = await recordings.signedUrl(key);
  console.log((await AI.transcribe(link)).text);
  await msg.ack();
}
```

Each message is `{"event": "put", "bucket", "key", "size", "content_type", "etag", "at"}`. The queue is a `Queue` or its name, in the bucket's own user. Asking again for the same queue and prefix changes nothing, `notify(queue, prefix=..., enabled=False)` stops it, and the bucket's `notifications` lists where it tells, up to 10 queues. A file stored twice at one key is two messages; a removed file is none.

## Serve files publicly

In a public bucket, every file has a plain URL that never expires, under the bucket's `public_base_url`. It's NoClick's address, which sends the browser on to the file with a short-lived signed link:

```python
import noclick

assets = noclick.Bucket.from_name("public-assets", create_if_missing=True, public=True)
with open("logo.png", "rb") as f:
    assets.put("logo.png", f)
print(assets.url("logo.png"))
```

```ts
import { readFile } from "node:fs/promises";
import { Bucket } from "noclick";

const assets = Bucket.fromName("public-assets", { createIfMissing: true, public: true });
await assets.put("logo.png", await readFile("logo.png"));
console.log(await assets.url("logo.png"));
```

`url` on a private bucket raises `noclick.NotAvailable`. `update(public=True)` opens a bucket; `update(public=False)` closes it, and every public URL stops working at once (signed links, and the short-lived links a public URL already sent a browser to, keep working until they expire).

## Use S3 tools

For rclone, the AWS CLI, or an S3 library, `s3_credentials` mints keys for the bucket's S3-compatible endpoint. They reach this bucket only, `read_only=True` keeps them from changing anything, and they stop working after `ttl_s` seconds. They're for you and your own code with your key: an app's deployed code is refused them, and moves big files [in parts](https://www.noclick.com/docs/guide/storage.md#upload-a-big-file-in-parts) instead.

```python
import boto3

import noclick

bucket = noclick.Bucket.from_name("uploads")
creds = bucket.s3_credentials(read_only=True, ttl_s=3600)
s3 = boto3.client(
    "s3",
    endpoint_url=creds.endpoint,
    region_name=creds.region,
    aws_access_key_id=creds.access_key_id,
    aws_secret_access_key=creds.secret_access_key,
    aws_session_token=creds.session_token,
)
print(s3.list_objects_v2(Bucket=creds.bucket, Prefix="invoices/")["KeyCount"])
```

```ts
import { ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
import { Bucket } from "noclick";

const bucket = Bucket.fromName("uploads");
const creds = await bucket.s3Credentials({ readOnly: true, ttlS: 3600 });
const s3 = new S3Client({
  endpoint: creds.endpoint,
  region: creds.region,
  credentials: {
    accessKeyId: creds.accessKeyId,
    secretAccessKey: creds.secretAccessKey,
    sessionToken: creds.sessionToken ?? undefined,
  },
});
console.log((await s3.send(new ListObjectsV2Command({ Bucket: creds.bucket, Prefix: "invoices/" }))).KeyCount);
```

Use `creds.bucket`, the bucket's name on the S3 endpoint, rather than its NoClick name. The secret is shown once; mint new credentials when these expire (`ttl_s` is 900 seconds to 12 hours). S3 tools upload a big file in parts themselves. They also see the bucket's `.noclick/` folder, where NoClick keeps files' [earlier versions](https://www.noclick.com/docs/guide/undo.md); a file they write keeps none.

## Use it from an app or an agent

An app reaches its bucket through a binding: `app.bind("FILES", bucket)` makes it available to the deployed code as `FILES`, and the bucket's `used_by` lists the apps that bind it; the app's code can also find or make it by name with `from_name`. See [Apps](https://www.noclick.com/docs/guide/apps.md).

A preview's code reads production's files and keeps what it writes: at its first write the branch gets an overlay bucket of its own, holding what it puts and remembering what it deletes, and every other key reads through to production's, links and public URLs included. Production's files never change. See [A preview's own data](https://www.noclick.com/docs/guide/apps.md#a-preview-s-own-data).

An agent can keep the files it makes, one bucket per user, by creating it inside `as_user`:

```python
import noclick

with noclick.as_user("user_42"):
    files = noclick.Bucket.from_name("assistant-files", create_if_missing=True)
    files.put("receipts/2026-09-12.txt", "Coffee, $4.50")
```

```ts
import { Bucket, asUser } from "noclick";

await asUser("user_42", async () => {
  const files = Bucket.fromName("assistant-files", { createIfMissing: true });
  await files.put("receipts/2026-09-12.txt", "Coffee, $4.50");
});
```

Put the bucket in an agent's `tools` (a bucket of the agent's own user, or your account's) and the model gets five tools named after it: `uploads__objects` (list keys under a prefix), `uploads__head` (a file's size, type and metadata), `uploads__put` (store a file), `uploads__signed_url` (a link that reads a file, to hand a person) and `uploads__remove`. `put` takes the file from a `url` or as `text`, with a `content_type` and `metadata`, so no bytes pass through the model: a file the agent's [browser](https://www.noclick.com/docs/guide/browser.md) downloads comes back to it as a signed link, which `put` stores from `url`. `only(...)` gives it some of them, and `bind(prefix=...)` keeps every key it reads or writes under one folder, with keys given and returned relative to it:

```python
import noclick

uploads = noclick.Bucket.from_name("uploads")
assistant = noclick.Agent.from_name(
    "assistant",
    create_if_missing=True,
    instructions="You file what the user sends you and share links to it.",
    tools=[uploads.only("objects", "put", "signed_url").bind(prefix="users/{{user.id}}/")],
)
```

```ts
import { Agent, Bucket } from "noclick";

const uploads = Bucket.fromName("uploads");
const assistant = Agent.fromName("assistant", {
  createIfMissing: true,
  instructions: "You file what the user sends you and share links to it.",
  tools: [uploads.only("objects", "put", "signed_url").bind({ prefix: "users/{{user.id}}/" })],
});
```

One bucket then holds a folder per user, and no user's agent reaches another's: a turn for someone who isn't one of your users (the account itself, a stranger's email) can't fill `{{user.id}}`, so it isn't offered those tools at all. Its calls follow your [approval rules](https://www.noclick.com/docs/guide/policy.md) as `bucket.objects`, `bucket.head`, `bucket.put`, `bucket.signed_url` and `bucket.remove` (`bucket.*`). See [Fix arguments the model mustn't choose](https://www.noclick.com/docs/guide/connections.md#fix-arguments-the-model-mustn-t-choose) for what a binding may name. A bucket in a [toolkit](https://www.noclick.com/docs/guide/toolkits.md) or a [hosted MCP server](https://www.noclick.com/docs/guide/mcp-servers.md) is in invite-only beta.

## Export and delete

`export` is an [operation](https://www.noclick.com/docs/guide/operations.md) that gives an [export bundle](https://www.noclick.com/docs/guide/export.md): a zip, at a link valid 7 days, holding every file at its key under `buckets/<name>/files/`, and `index.jsonl` listing each key with its content type and metadata. A key that can't be a path in a zip (an empty, `.` or `..` part, a backslash) is kept under `renamed/`, and the index says which key it is. Files' [earlier versions](https://www.noclick.com/docs/guide/undo.md) aren't files, so they aren't in it.

```python
bundle = bucket.export().wait()
print(bundle.url, bundle.size_bytes)
```

```ts
const bundle = await (await bucket.export()).wait();
console.log(bundle.url, bundle.sizeBytes);
```

`delete` moves the bucket to the [trash](https://www.noclick.com/docs/guide/undo.md). It must hold no files, or pass `force=True` to take its files with it; a bucket that still holds files raises `noclick.Conflict`, as does one in an agent's tools (its `used_by` lists them). Files' earlier versions don't count: a bucket whose files you've all removed deletes without `force`, its versions go to the trash with it, and they come back if you restore it.

```python
noclick.Bucket.from_name("scratch").delete(force=True)
```

```ts
import { Bucket } from "noclick";

await Bucket.fromName("scratch").delete({ force: true });
```

## Limits and billing

| Limit | Value |
| --- | --- |
| One `put` | 100 MB |
| One file put or read inside the call (JSON) | 5 MB |
| One `PUT` link upload | 5 GB |
| An upload in parts | 10,000 parts of 5 MiB to 5 GiB, every part but the last the same size; dropped after 7 days unfinished |
| Signed link lifetime | 60 seconds to 7 days |
| Metadata per file | 2 KB |

A bucket is billed for what it stores, $0.015 per GB-month, charged by the hour. NoClick measures it within a minute or so of a change your code or an agent makes, and at least every hour (so a file uploaded with a signed link is counted within the hour); `size_bytes` and `object_count` are that measurement. Its requests cost what R2 charges for them, however they came (your code, an agent, a signed link, an upload's parts, a public URL, S3 tools): $4.50 per million writes and lists (Class A) and $0.36 per million reads (Class B), with deletes free, charged by the hour about an hour after they're made. Downloads cost nothing extra. Spend counts toward the cap of the user the bucket belongs to.

## Errors

| Error | When |
| --- | --- |
| `NotFound` | no file at that key, no bucket by that name or id for the user the call acts for, or an upload in parts already completed, aborted or over 7 days old |
| `NotAvailable` | `url` on a private bucket |
| `Conflict` | the name is taken; `delete` on a bucket with files (pass `force=True`) or one in an agent's tools |
| `InvalidRequest` | a file over 100 MB (over 5 MB inside the call), metadata over 2 KB or not ASCII, a name that isn't allowed, a link lifetime out of range, or parts an upload can't join |

Every method is in the [Bucket reference](https://www.noclick.com/docs/reference/python/Bucket.md): [`put`](https://www.noclick.com/docs/reference/python/Bucket.md#Bucket.put), [`objects`](https://www.noclick.com/docs/reference/python/Bucket.md#Bucket.objects), [`signed_url`](https://www.noclick.com/docs/reference/python/Bucket.md#Bucket.signed_url), [`start_upload`](https://www.noclick.com/docs/reference/python/Bucket.md#Bucket.start_upload), [`s3_credentials`](https://www.noclick.com/docs/reference/python/Bucket.md#Bucket.s3_credentials) and the rest.
