Skip to main content

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.

tc.json
{
"storage": {
"buckets": {
"receipts": { "visibility": "private", "readRoles": ["approver"] },
"exports": "app-public"
}
}
}
VisibilityWho reads
private (default)Each person reads the files they uploaded. App roles in readRoles read every file. Anyone else needs a signed URL.
app-publicEveryone 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.

tip

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
ParameterTypeDescription
bucketstringBucket name
opts.requestRequestLikeServer: 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>>
ParameterTypeDescription
pathstringPath inside the bucket, e.g. u123/lunch.pdf. A leading slash is dropped.
bodyBlob | File | ArrayBuffer | ArrayBufferView | string | ReadableStream | NodeJS.ReadableStreamThe contents. Node streams are streamed, not buffered.
opts.contentTypestringDefault: the File/Blob type
opts.upsertbooleanReplace 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.

src/upload.js
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

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[]>>
ParameterTypeDescription
folderstringPrefix, default the bucket root
opts.searchstringFilter by name
opts.limitnumberMaximum entries

Returns FileObject[]:

FieldDescription
name, pathName and full path in the bucket
idETag, or null for folders
owner, owner_name, mineUploader's id and name; whether it's yours
created_at, updated_atTimestamps
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 }>>
ParameterTypeDescription
expiresInnumberSeconds, up to 7 days. Default 3600.
opts.downloadbooleanServe 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​

CodeMeaningFix
STORAGE_QUOTA_EXCEEDEDThe project is fullDelete files or ask IT to raise the quota
STORAGE_FILE_TOO_LARGEOver the per-file limit
STORAGE_TYPE_NOT_ALLOWEDHTML, SVG, scripts or an unknown type
STORAGE_EXISTSA file already exists at that pathPass upsert: true
STORAGE_NOT_OWNEROnly the uploader, editor or admin may change it
STORAGE_FORBIDDENSomeone else's file in a private bucketAsk for a signed link
STORAGE_NOT_FOUND, STORAGE_BUCKET_NOT_FOUNDNo such file or bucket
STORAGE_NOT_PUBLICgetPublicUrl on a private bucketUse createSignedUrl
STORAGE_SIGNATURE_EXPIREDThe signed URL expiredSign a new one
STORAGE_SIGNATURE_INVALIDThe signed URL was altered or signed for another fileSign a new one
STORAGE_BAD_PATHThe path is empty, badly encoded or otherwise invalidUse a relative path such as u123/lunch.pdf
PROJECT_ARCHIVEDThe project is archivedRestore it
UNAUTHENTICATED, NO_ACCESSNot signed in, or no access to the app
STORAGE_ERRORAnything 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.

server.js
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()))
})
Was this page helpful?