P
PUGUH
ID Get Started

File Storage

PUGUH provides S3-compatible file storage with organization-level isolation, automatic virus scanning, and CDN delivery.

Overview

The storage service handles:

  • File uploads with size limits per plan
  • Organization isolation — files are scoped to the uploading organization
  • Image processing — automatic thumbnail and variant generation
  • Presigned URLs for secure, time-limited downloads
  • Visibility control — public or private per file

Uploading Files

Via API

bash 
curl -X POST https://api-puguh.arsaka.io/storage/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -F "file=@logo.png" \
  -F "visibility=public"

Response:

json 
{
  "id": "file_abc123",
  "filename": "logo.png",
  "content_type": "image/png",
  "size_bytes": 45200,
  "visibility": "public",
  "url": "https://cdn.arsaka.io/org_xxx/logo.png",
  "variants": {
    "thumbnail": "https://cdn.arsaka.io/org_xxx/logo_thumb.png",
    "medium": "https://cdn.arsaka.io/org_xxx/logo_medium.png"
  },
  "created_at": "2026-02-20T10:00:00Z"
}

Via SDK (TypeScript)

typescript 
import { PuguhClient } from '@arsaka/puguh-sdk';

const client = new PuguhClient({ apiKey: 'YOUR_KEY' });

// Upload a file
const file = await client.storage.upload(fileBlob, {
  visibility: 'public',
  organizationId: 'org_abc'
});

console.log(file.url);       // Public CDN URL
console.log(file.variants);  // { thumbnail, medium }

Via SDK (Python)

python 
from puguh_sdk import PuguhClient

client = PuguhClient(api_key="YOUR_KEY")

with open("logo.png", "rb") as f:
    file = client.storage.upload(f, visibility="public")

print(file.url)
print(file.variants)

File Visibility

VisibilityAccessURL Type
publicAnyone with the URLPermanent CDN URL
privateAuthenticated users onlyPresigned URL (expires)

Changing Visibility

bash 
curl -X PATCH https://api-puguh.arsaka.io/storage/file_abc123/visibility \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"visibility": "private"}'

Presigned URLs

Generate time-limited download URLs for private files:

bash 
curl -X POST https://api-puguh.arsaka.io/storage/file_abc123/presign \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"expires_in": 3600}'

Response:

json 
{
  "url": "https://cdn.arsaka.io/org_xxx/file_abc123?token=xxx&expires=1708430400",
  "expires_at": "2026-02-20T11:00:00Z"
}

Image Variants

When you upload an image (PNG, JPG, WebP), PUGUH automatically generates variants:

VariantMax SizeFormat
thumbnail150x150WebP
medium600x600WebP
originalAs uploadedOriginal

Listing Files

bash 
curl https://api-puguh.arsaka.io/storage?page=1&page_size=20 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Response:

json 
{
  "items": [
    {
      "id": "file_abc123",
      "filename": "logo.png",
      "content_type": "image/png",
      "size_bytes": 45200,
      "visibility": "public",
      "created_at": "2026-02-20T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "has_next": true,
  "has_prev": false
}

Deleting Files

bash 
curl -X DELETE https://api-puguh.arsaka.io/storage/file_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Deleted files are soft-deleted and can be recovered within 30 days.

Storage Usage

bash 
curl https://api-puguh.arsaka.io/storage/usage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Response:

json 
{
  "used_bytes": 524288000,
  "quota_bytes": 5368709120,
  "file_count": 156,
  "usage_percent": 9.8
}

Limits by Plan

PlanStorageMax File SizeBandwidth
Free1 GB10 MB5 GB/month
Pro10 GB100 MB50 GB/month
Business100 GB500 MB500 GB/month
EnterpriseCustomCustomCustom

Allowed File Types

By default, PUGUH allows common file types. Organization admins can customize allowed types via policies.

CategoryExtensions
Images.png, .jpg, .jpeg, .gif, .webp, .svg
Documents.pdf, .doc, .docx, .xls, .xlsx, .csv
Archives.zip, .tar.gz
Other.json, .xml, .txt

Best Practices

  1. Use presigned URLs for private files instead of proxying through your server
  2. Set appropriate visibility at upload time (public for logos/assets, private for user documents)
  3. Use image variants instead of serving full-size originals for thumbnails
  4. Monitor storage usage to avoid hitting plan limits
  5. Clean up unused files periodically

Related