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. 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

import noclick

bucket = noclick.Bucket.from_name("uploads", create_if_missing=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:

assets = noclick.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.

region= places its files in a region, 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:

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"})

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 past 5 GB.

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")

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:

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

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.

for entry in bucket.objects(prefix="invoices/", delimiter="/"):
    print(entry.key, "folder" if entry.is_folder else 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, 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:

{"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:

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

Over the HTTP API 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 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.

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:

link = bucket.signed_url("invoices/0042.pdf", expires_in=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:

upload = bucket.signed_url("avatars/u42.png", method="PUT", expires_in=600, content_type="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:

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"))

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:

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)

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, 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 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 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:

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()

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:

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"))

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 instead.

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"])

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; 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.

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.

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

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")

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 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:

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}}/")],
)

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 as bucket.objects, bucket.head, bucket.put, bucket.signed_url and bucket.remove (bucket.*). See Fix arguments the model mustn't choose for what a binding may name. A bucket in a toolkit or a hosted MCP server is in invite-only beta.

Export and delete

export is an operation that gives an export bundle: 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 aren't files, so they aren't in it.

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

delete moves the bucket to the trash. 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.

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

Limits and billing

LimitValue
One put100 MB
One file put or read inside the call (JSON)5 MB
One PUT link upload5 GB
An upload in parts10,000 parts of 5 MiB to 5 GiB, every part but the last the same size; dropped after 7 days unfinished
Signed link lifetime60 seconds to 7 days
Metadata per file2 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

ErrorWhen
NotFoundno 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
NotAvailableurl on a private bucket
Conflictthe name is taken; delete on a bucket with files (pass force=True) or one in an agent's tools
InvalidRequesta 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: put, objects, signed_url, start_upload, s3_credentials and the rest.