Skip to main content

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​

MethodPathBody / queryAuthWhat it does
POST/storage/buckets{ name, visibility?, readRoles? }manageCreate a bucket (201), or update it if it exists (200). Response { created, bucket }.
PATCH/storage/buckets/:bucket{ visibility?, readRoles? }manageChange visibility or read roles
DELETE/storage/buckets/:bucket?force=1manageDelete a bucket. force also deletes its files.
PUT/storage/limits{ quotaBytes?, maxFileBytes? }org adminSet 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.

MethodPathBody / queryWhat it does
POST/v1/object/:bucket/:pathFile bytes; content-type, content-lengthUpload
PUT/v1/object/:bucket/:pathFile bytesUpload and replace (or send x-upsert: true with POST)
GET/v1/object/:bucket/:pathRange, If-None-Match, ?download=1Download
DELETE/v1/object/:bucket/:pathDelete one file
DELETE/v1/object/:bucket{ "prefixes": ["path", …] }Delete files. Response { removed, errors }.
GET/v1/object/list/:bucket?prefix&search&limit&cursorList: { 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/bucketsBuckets
GET/v1/usageUsage 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
Was this page helpful?