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 compute 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 Compute Functions¶

Compute 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 Compute 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