# Folio

Private file storage for SaaS apps. 3 GB free per workspace. REST API; no SDK required.

Reference: https://folio.atef.dev/api-reference
Signup: https://folio.atef.dev/auth/sign-up
API base: https://folio.atef.dev/api/v1

Keep FOLIO_KEY on your SERVER. Your server authorizes its user and sets X-Folio-Tenant to that user's tenant ID. A workspace key can access all its tenants; never let a browser choose an arbitrary tenant.

Upload:
POST /files
Authorization: Bearer $FOLIO_KEY
X-Folio-Tenant: customer_123
Multipart fields: file (required, 1 byte–25 MiB), purpose, profile, metadata (JSON object).
Returns {file:{id,tenantId,status,derivatives,...}}. IDs are opaque.

GET /files/:id returns {file}. Poll derivatives until thumbnail/preview/optimized are ready or failed. Originals remain available when preview processing fails. Raster images receive WebP thumbnail + optimized rendition. PDFs receive a first-page PNG preview. Other files are stored without visual previews.

POST /files/:id/links with JSON {"variant":"thumbnail"} returns {url,expiresAt}. Resolve relative URL against API origin. Five-minute signed links are safe to pass to browsers and authorize exactly one file rendition. Variants: content, thumbnail, preview, optimized.

GET /files?limit=100&cursor=... returns {items,nextCursor}.
GET /usage returns workspace + current tenant storage and limits.
GET /tenants returns {items}.
PUT /tenants/:tenantId with JSON {"limitBytes":100000000} sets allowance; null inherits workspace.
DELETE /files/:id deletes logical file and invalidates its links.
POST /files/:id/retry retries failed renditions.

Error envelope: {error:{code,message,requestId}}. Handle 401 authentication, 404 scope/not found, 409 pending rendition or conflicting limit, 415 unsupported rendition, 413 upload too large or tenant/workspace quota exceeded (inspect code), 429 rate limit, 503 unavailable. Do not retry writes blindly; upload idempotency is not supported yet.

Original bytes count toward 3 GB; automatic renditions are included. Paid storage from $5/month is planned, unavailable today. Resumable uploads, browser upload tokens, SDKs and user-defined automations are future features.