Syntra Storage

Bucket management

1. •storage_list_buckets — see existing buckets
2. •storage_create_bucket — create with name and optional is_public
3. •storage_get_bucket — get bucket details by ID
4. •storage_update_bucket — toggle public access
5. •storage_delete_bucket — delete bucket and all objects

Public vs private buckets

• •Public (is_public: true): Objects accessible via direct URL without authentication
• •Private (is_public: false): Requires signed URLs or authenticated download

Upload files

Small files (< 5MB) — inline base64

{
  "bucket_name": "avatars",
  "key": "users/user-123/avatar.png",
  "content_base64": "<base64-encoded-content>",
  "content_type": "image/png"
}

Use storage_upload_object with base64-encoded content.

Large files — signed upload URL

1. •storage_get_signed_upload_url with bucket_name, key, content_type
2. •Returns a signed_url valid for 1 hour (configurable via expires_in)
3. •Client uploads directly via HTTP PUT to the signed URL

Download files

Inline download

storage_download_object returns:

• •Files < 5MB: content_base64 + content_type + size
• •Files > 5MB: signed_url for direct download

Signed download URL

storage_get_signed_download_url — returns a time-limited URL for direct access.

File operations

• •storage_list_objects — list files in a bucket with optional prefix filter and pagination
• •storage_delete_object — delete a single file
• •storage_copy_object — copy between buckets or rename within a bucket

Common patterns

User avatar upload

1. storage_create_bucket  { name: "avatars", is_public: true }
2. storage_upload_object  { bucket_name: "avatars", key: "users/{user_id}/avatar.png", content_base64: "...", content_type: "image/png" }

Document storage (private)

1. storage_create_bucket  { name: "documents", is_public: false }
2. storage_upload_object  { bucket_name: "documents", key: "contracts/2024/contract-001.pdf", ... }
3. storage_get_signed_download_url  { bucket_name: "documents", key: "contracts/2024/contract-001.pdf", expires_in: 3600 }

Organize with prefixes

Use / in keys to create virtual folder structures:

• •images/products/shoe-001.jpg
• •images/products/shoe-002.jpg
• •images/banners/hero.png

Then list with prefix: "images/products/" to get only product images.

Storage providers

Configured via environment variables:

• •Local: STORAGE_PROVIDER=local, files in LOCAL_STORAGE_PATH
• •S3-compatible: STORAGE_PROVIDER=s3 with S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, optional S3_ENDPOINT (for MinIO, Cloudflare R2, etc.)