Storage
Manage a project's buckets and files as yourself. The owner, project developers and admins manage everything; auditors read. App code uses tc.storage instead.
All paths start with /api/projects/:name/storage.
Overview
GET /api/projects/:name/storage
Response 200
{
"appUrl": "https://expenses.apps.contoso.com",
"canManage": true,
"buckets": [
{ "name": "receipts", "visibility": "private", "readRoles": ["approver"], "status": "ready", "createdAt": "…", "bytes": 18763776, "objects": 40 }
],
"usage": { "usedBytes": 19288064, "objects": 42, "quotaBytes": 5368709120, "maxFileBytes": 52428800, "measuredAt": "…" }
}
Buckets
| Method | Path | Body / query | Auth | What it does |
|---|---|---|---|---|
POST | /storage/buckets | { name, visibility?, readRoles? } | manage | Create a bucket (201), or update it if it exists (200). Response { created, bucket }. |
PATCH | /storage/buckets/:bucket | { visibility?, readRoles? } | manage | Change visibility or read roles |
DELETE | /storage/buckets/:bucket | ?force=1 | manage | Delete a bucket. force also deletes its files. |
PUT | /storage/limits | { quotaBytes?, maxFileBytes? } | org admin | Set the project's quota and per-file limit |
visibility is private (default) or app-public; there is no internet-public option. Bucket names are 3–63 characters of lowercase letters, digits and dashes.
Errors: 400 INVALID_BUCKET, 400 INVALID_VISIBILITY, 400 INVALID_ROLE, 404 BUCKET_NOT_FOUND, 409 BUCKET_NOT_EMPTY, 403 ADMIN_ONLY, 400 INVALID_LIMIT, 503 STORAGE_NOT_CONFIGURED.
Files: the storage API
/api/projects/:name/storage/v1/*
The storage API itself, with the same paths as /_tc/storage/v1/* on the app's origin, streamed both ways and acting as you.
| Method | Path | Body / query | What it does |
|---|---|---|---|
POST | /v1/object/:bucket/:path | File bytes; content-type, content-length | Upload |
PUT | /v1/object/:bucket/:path | File bytes | Upload and replace (or send x-upsert: true with POST) |
GET | /v1/object/:bucket/:path | Range, If-None-Match, ?download=1 | Download |
DELETE | /v1/object/:bucket/:path | Delete one file | |
DELETE | /v1/object/:bucket | { "prefixes": ["path", …] } | Delete files. Response { removed, errors }. |
GET | /v1/object/list/:bucket | ?prefix&search&limit&cursor | List: { bucket, prefix, folders, objects, next }. limit defaults to 1000; pass next back as cursor for the next page. |
POST | /v1/object/sign/:bucket/:path | { expiresIn, download? } | Signed link: { signedUrl, path, expiresAt }. signedUrl is relative to appUrl. |
POST | /v1/object/sign/:bucket | { paths, expiresIn, download? } | Sign up to 200 paths: [{ path, signedUrl, error }] |
GET | /v1/buckets | Buckets | |
GET | /v1/usage | Usage and limits |
Responses for files carry content-security-policy: default-src 'none'; sandbox, so the console never renders a file itself.
Errors look like { "error": { "code": "STORAGE_EXISTS", "message": "…", "fix": "Pass upsert…" } }. The codes are listed under SDK storage errors.
Example
curl -X POST -H "Authorization: Bearer dev-token" -H "Content-Type: application/pdf" \
--data-binary @policy.pdf \
http://localhost:4780/api/projects/expenses/storage/v1/object/receipts/templates/policy.pdf