InsForge provides bucket-based file storage. Like S3, but simpler.

​
How It Works

Buckets → Files → URLs
  1. Create bucket (public or private)
  2. Upload files to bucket
  3. Get URL for access
  4. Files served directly or with auth

​
Buckets

Containers for files with access policies:
  • Public - Anyone can download (images, assets)
  • Private - Requires authentication (documents, reports)
Only admins create buckets. Users upload to existing buckets.

​
Uploading Files

// Upload with FormData
const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('/api/storage/buckets/avatars/objects', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

// Response
{
  url: "/api/storage/buckets/avatars/objects/file-123.jpg",
  size: 102400,
  contentType: "image/jpeg"
}

​
File URLs

Predictable URL pattern: 
/api/storage/buckets/{bucket}/objects/{filename}
  • Public buckets: No auth required
  • Private buckets: Include Authorization header

​
Automatic Naming

Files get unique names to prevent overwrites:
  • Upload: resume.pdf
  • Stored as: resume-1704067200-xyz789.pdf
  • User still sees: resume.pdf

​
Key Concepts

No Direct CDN - InsForge handles uploads. Add CloudFlare for CDN. FormData Required - Files must use multipart/form-data. Bucket Creation - Admin only via MCP tools. Local or S3 - Same API works with local disk or S3 storage.

​
Common Patterns

// Image upload with preview
async function uploadAvatar(file) {
  const formData = new FormData();
  formData.append('file', file);
  
  const res = await fetch('/api/storage/buckets/avatars/objects', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData
  });
  
  const { url } = await res.json();
  
  // Save URL to user profile
  await fetch('/api/database/records/profiles', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ avatar_url: url })
  });
  
  return url;
}

​
Storage Backends

  • Local - Files on disk (development, small apps)
  • S3 - AWS or compatible (production, scale)
Switch backends without code changes.

​
Next Steps