Storage¶

Overview¶

Centrali's Storage service provides secure file storage and management integrated with your workspace. Upload, download, and manage files that can be referenced from records and accessed by functions.

Key Features¶

• Secure storage: Files are scoped to your workspace
• Large file support: Upload files up to 5 GB
• Access control: Workspace-level permissions
• Integration: Reference files from records
• CDN: Fast file delivery via Azure Blob Storage

Folder Structure¶

Every workspace has a predefined folder structure. Files must be uploaded to folders within this structure.

Root Folders¶

Default Upload Location¶

If you don't specify a location when uploading, files are automatically placed in /root/shared.

Path Format¶

All paths must be absolute, starting with /root/. For example: - /root/shared - Default shared folder - /root/shared/images - Images subfolder - /root/shared/documents/invoices - Nested folder structure

Creating Folders¶

Create folders using the API before uploading files to them:

# Create a folder in /root/shared
curl -X POST https://api.centrali.io/storage/ws/my-workspace/api/v1/folders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "images",
    "parentPath": "/root/shared"
  }'

Create a subfolder inside an existing folder:

# Create a subfolder using parent folder ID
curl -X POST https://api.centrali.io/storage/ws/my-workspace/api/v1/folders/{parent_folder_id}/sub-folders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "thumbnails"
  }'

Listing Folders¶

curl -X GET https://api.centrali.io/storage/ws/my-workspace/api/v1/folders \
  -H "Authorization: Bearer YOUR_TOKEN"

Uploading Files¶

Upload files to a specific folder or let them default to /root/shared:

# Upload to default location (/root/shared)
curl -X POST https://api.centrali.io/storage/ws/my-workspace/api/v1/storage/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.pdf" \
  -F "fileName=my-document.pdf"

# Upload to a specific folder (must exist)
curl -X POST https://api.centrali.io/storage/ws/my-workspace/api/v1/storage/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/file.pdf" \
  -F "fileName=my-document.pdf" \
  -F "location=/root/shared/documents"

Response:

"kvHJ4ipZ3Q6EAoguKrWmU7KYyDHcU03C"

The response is a render ID - a unique identifier for the uploaded file. Use this ID to construct URLs for rendering or downloading the file.

Constructing File URLs¶

Use the render ID to access your file:

Example:

# Render the file (e.g., display image in browser)
curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/kvHJ4ipZ3Q6EAoguKrWmU7KYyDHcU03C" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Download the file as attachment
curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/download/kvHJ4ipZ3Q6EAoguKrWmU7KYyDHcU03C" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output file.pdf

If using the SDK, use the helper methods:

const renderId = result.data;
const renderUrl = client.getFileRenderUrl(renderId);
const downloadUrl = client.getFileDownloadUrl(renderId);

Upload Parameters¶

Downloading Files¶

Download files using the render ID:

curl -X GET "https://api.centrali.io/storage/ws/my-workspace/api/v1/download/{renderId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output file.pdf

Image Resize & Compression¶

Centrali supports on-the-fly image transformation when rendering images. Resize, compress, and convert image formats without storing multiple versions.

Render Endpoint¶

GET /storage/ws/{workspace}/api/v1/render/{render_id}

Query Parameters¶

Examples¶

Resize to specific width (maintains aspect ratio):

curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123?width=200" \
  -H "Authorization: Bearer YOUR_TOKEN"

Resize to fit within dimensions:

curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123?width=800&height=600" \
  -H "Authorization: Bearer YOUR_TOKEN"

Compress JPEG with lower quality:

curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123?format=jpeg&quality=60" \
  -H "Authorization: Bearer YOUR_TOKEN"

Convert PNG to JPEG:

curl "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123?format=jpeg" \
  -H "Authorization: Bearer YOUR_TOKEN"

Supported Image Formats¶

• JPEG / JPG
• PNG
• WebP
• GIF (converted to PNG on output)
• BMP
• TIFF

Behavior¶

• Aspect ratio: Automatically preserved when only width or height is specified
• Both dimensions: Image fits within the specified bounds while maintaining aspect ratio
• Quality: Only applies to JPEG output format
• Fallback: Returns original image if transformation fails
• Non-images: Files that aren't images are returned unchanged

Use Cases¶

• Thumbnails: Generate thumbnails on-the-fly for galleries
• Responsive images: Serve appropriately sized images for different devices
• Bandwidth optimization: Compress images for faster loading
• Format conversion: Convert to more efficient formats like WebP

Listing Files¶

curl -X GET https://api.centrali.io/storage/ws/my-workspace/api/v1/storage/list?prefix=documents/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Deleting Files¶

curl -X DELETE https://api.centrali.io/storage/ws/my-workspace/api/v1/storage/documents/file.pdf \
  -H "Authorization: Bearer YOUR_TOKEN"

Referencing Files in Records¶

Store file references in record properties:

{
  "name": "invoice",
  "properties": [
    { "name": "invoiceNumber", "type": "string" },
    { "name": "pdfFile", "type": "string" }
  ]
}

Create record with file reference:

{
  "invoiceNumber": "INV-001",
  "pdfFile": "documents/invoices/INV-001.pdf"
}

Using Storage in Functions¶

Functions can create and store files using the api.storeFile() method. This is useful for generating reports, exporting data, or processing files programmatically.

async function run() {
  // Generate a CSV report
  const csvContent = "name,email,status\nJohn,john@example.com,active";

  // Store the file
  const result = await api.storeFile(
    csvContent,
    "daily-report.csv",
    {
      mimeType: "text/csv",
      encoding: "utf8",        // Use "base64" for binary files (PDFs, images)
      folder: "/root/shared/reports",  // Optional: target folder (must exist)
      isPublic: false          // Private by default (requires auth to access)
    }
  );

  if (result.success) {
    api.log(`File stored successfully`);
    api.log(`URL: ${result.fileUrl}`);
    api.log(`Render ID: ${result.renderId}`);

    // Save the renderId to a record for future reference
    await api.updateRecord(executionParams.recordId, {
      reportFile: result.renderId
    });
  } else {
    api.logError(`Failed to store file: ${result.error}`);
  }

  return { success: result.success };
}

File Storage Options¶

Limits¶

For complete documentation including examples for PDFs, images, and error handling, see the Writing Functions Guide.

Best Practices¶

• Use full paths: Always use absolute paths starting with /root/ (e.g., /root/shared/documents)
• Create folders first: Create folders via API before uploading files to them
• Organize by type: Use subfolders to organize files (e.g., /root/shared/images, /root/shared/documents)
• Use safe file names: Avoid spaces and special characters in file names
• Clean up regularly: Delete unused files to manage storage quota
• Don't use system folders: Only upload to /root/ paths; /system/ and /support/ are reserved

Limits¶

• Max file size: 5 GB
• Storage quota: 100 GB per workspace (default)
• Upload rate: 100 requests/minute