Storage
tc.storage stores files in the project's buckets. The API is shaped like Supabase storage-js: in JavaScript every call returns { data, error } and never throws; in Python, methods return data and raise TcError.
Buckets and visibility
Buckets belong to a project. Declare them in tc.json (created on deploy), create them in the console, with tc storage buckets create or with the MCP tool create_bucket.
{
"storage": {
"buckets": {
"receipts": { "visibility": "private", "readRoles": ["approver"] },
"exports": "app-public"
}
}
}
| Visibility | Who reads |
|---|---|
private (default) | Each person reads the files they uploaded. App roles in readRoles read every file. Anyone else needs a signed URL. |
app-public | Everyone who can open the app reads every file. getPublicUrl works. |
There is no internet-public option: every link, signed or public, stays behind company sign-in. Bucket naming rules, the console's Storage page and the full permission table are in Storage.
Writes: anyone with access to the app can upload. Only the uploader can replace (upsert) or delete a file; the app roles editor and admin manage every file. Jobs act as the app and manage every file.
Limits: 5 GB per project by default (IT can raise it) and 50 MB per file. Types are checked from the bytes: images, PDF, text/CSV/JSON, Office files and zip are allowed; HTML, SVG and scripts are refused, because files are served from your app's origin. See Quotas and limits.
Store the file's path in your table (for example receipt_path text), not a URL. Links expire; sign one when you show the file.
tc.storage.from(bucket, options)
Returns the bucket API.
tc.storage.from(bucket: string, opts?: { request?: RequestLike; as?: 'user' | 'project' }): StorageBucketApi
| Parameter | Type | Description |
|---|---|---|
bucket | string | Bucket name |
opts.request | RequestLike | Server: act as this request's user for every call on the bucket |
opts.as | 'user' | 'project' | Server: 'project' forces the app identity (jobs) |
Every method below also accepts request and as in its own options.
upload(path, body, options)
upload(path: string, body: UploadBody, opts?: { contentType?: string; upsert?: boolean }): Promise<StorageResult<UploadResult>>
| Parameter | Type | Description |
|---|---|---|
path | string | Path inside the bucket, e.g. u123/lunch.pdf. A leading slash is dropped. |
body | Blob | File | ArrayBuffer | ArrayBufferView | string | ReadableStream | NodeJS.ReadableStream | The contents. Node streams are streamed, not buffered. |
opts.contentType | string | Default: the File/Blob type |
opts.upsert | boolean | Replace an existing file. Default false. |
Returns data: { path, fullPath, id, size, contentType, replaced }.
Errors: STORAGE_EXISTS (pass upsert: true), STORAGE_NOT_OWNER, STORAGE_QUOTA_EXCEEDED, STORAGE_FILE_TOO_LARGE, STORAGE_TYPE_NOT_ALLOWED, STORAGE_BUCKET_NOT_FOUND, STORAGE_NO_BODY, PROJECT_ARCHIVED.
- JavaScript
- Python
const me = await tc.auth.user()
const path = `${me.id}/${crypto.randomUUID()}-${file.name}` // keep people's files under their id
const { data, error } = await tc.storage.from('receipts').upload(path, file)
if (error) alert(`${error.message}`) // error.code e.g. STORAGE_QUOTA_EXCEEDED; error.fix says what to do
tc.storage.from_("receipts").upload(
f"{user.id}/lunch.pdf", data, content_type="application/pdf", request=request
)
update(path, body, options)
Replaces an existing file. Same as upload with upsert: true.
update(path: string, body: UploadBody, opts?: { contentType?: string }): Promise<StorageResult<UploadResult>>
download(path)
download(path: string): Promise<StorageResult<Blob>>
Errors: STORAGE_NOT_FOUND, STORAGE_FORBIDDEN (someone else's file in a private bucket).
const { data: blob, error } = await tc.storage.from('receipts').download(path)
list(folder, options)
Files and folders directly under folder. Folders come first with id: null. In private buckets you only see what you can read.
list(folder?: string, opts?: { search?: string; limit?: number }): Promise<StorageResult<FileObject[]>>
| Parameter | Type | Description |
|---|---|---|
folder | string | Prefix, default the bucket root |
opts.search | string | Filter by name |
opts.limit | number | Maximum entries |
Returns FileObject[]:
| Field | Description |
|---|---|
name, path | Name and full path in the bucket |
id | ETag, or null for folders |
owner, owner_name, mine | Uploader's id and name; whether it's yours |
created_at, updated_at | Timestamps |
metadata | { size, mimetype, eTag, lastModified, contentLength }, null for folders |
remove(paths)
Deletes files you own (or any file with the editor/admin app role).
remove(paths: string[]): Promise<StorageResult<{ name; path; bucket_id; metadata: { size } }[]>>
If some paths fail, error is the first failure (for example STORAGE_NOT_OWNER) and its message says how many were removed.
createSignedUrl(path, expiresIn, options)
A short-lived link on your app's own origin, still behind company sign-in. Use it for <img src> or download links.
createSignedUrl(path: string, expiresIn: number, opts?: { download?: boolean }): Promise<StorageResult<{ signedUrl: string; path: string; expiresAt: string }>>
| Parameter | Type | Description |
|---|---|---|
expiresIn | number | Seconds, up to 7 days. Default 3600. |
opts.download | boolean | Serve as an attachment |
const { data: link } = await tc.storage.from('receipts').createSignedUrl(path, 300)
return <img src={link.signedUrl} alt="Receipt" />
createSignedUrls(paths, expiresIn, options)
JavaScript only. Signs several paths at once.
createSignedUrls(paths: string[], expiresIn: number, opts?: { download?: boolean }): Promise<StorageResult<{ path: string; signedUrl: string | null; error: string | null }[]>>
getPublicUrl(path, options)
app-public buckets only. Synchronous; it doesn't check the file exists. Opening the URL for a private bucket answers STORAGE_NOT_PUBLIC.
getPublicUrl(path: string, opts?: { download?: boolean }): { data: { publicUrl: string } }
tc.storage.from('exports').getPublicUrl('q3/report.pdf').data.publicUrl
tc.storage.listBuckets()
listBuckets(): Promise<StorageResult<{ id; name; visibility: 'private' | 'app-public'; public: boolean; readRoles: string[] }[]>>
tc.storage.getUsage()
JavaScript only.
getUsage(): Promise<StorageResult<{ usedBytes: number; quotaBytes: number; maxFileBytes: number; objects: number }>>
Error codes
| Code | Meaning | Fix |
|---|---|---|
STORAGE_QUOTA_EXCEEDED | The project is full | Delete files or ask IT to raise the quota |
STORAGE_FILE_TOO_LARGE | Over the per-file limit | |
STORAGE_TYPE_NOT_ALLOWED | HTML, SVG, scripts or an unknown type | |
STORAGE_EXISTS | A file already exists at that path | Pass upsert: true |
STORAGE_NOT_OWNER | Only the uploader, editor or admin may change it | |
STORAGE_FORBIDDEN | Someone else's file in a private bucket | Ask for a signed link |
STORAGE_NOT_FOUND, STORAGE_BUCKET_NOT_FOUND | No such file or bucket | |
STORAGE_NOT_PUBLIC | getPublicUrl on a private bucket | Use createSignedUrl |
STORAGE_SIGNATURE_EXPIRED | The signed URL expired | Sign a new one |
STORAGE_SIGNATURE_INVALID | The signed URL was altered or signed for another file | Sign a new one |
STORAGE_BAD_PATH | The path is empty, badly encoded or otherwise invalid | Use a relative path such as u123/lunch.pdf |
PROJECT_ARCHIVED | The project is archived | Restore it |
UNAUTHENTICATED, NO_ACCESS | Not signed in, or no access to the app | |
STORAGE_ERROR | Anything else |
Server usage
On the server, pass the request (or use tc.middleware()) so calls act as that user. Bodies can be a Buffer, string, Blob or Node stream. Cron and worker services act as the app.
app.get('/api/receipts/:id', async (req, res) => {
const { data: blob, error } = await tc.storage.from('receipts', { request: req }).download(req.params.id)
if (error) return res.status(error.status ?? 500).json({ code: error.code, fix: error.fix })
res.type(blob.type).send(Buffer.from(await blob.arrayBuffer()))
})