# How to Integrate Retool with Filestack

- Tool: Retool
- Difficulty: Beginner
- Time required: 15 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Filestack using a REST API Resource with your API key as a URL parameter or header. Access Filestack's Processing, Store, and Transform APIs to build media asset management panels — apply image transformations, manage uploaded files, and track file metadata in Retool dashboards that combine Filestack's CDN-powered file processing with your internal data.

## Build Media Asset Management Dashboards in Retool with Filestack

Filestack is widely used in web applications for handling file uploads and image processing, but the operational side — reviewing what files have been uploaded, applying bulk transformations, and managing file metadata — is often handled manually or not at all. Retool solves this by connecting to Filestack's APIs, enabling internal tools where teams can browse uploaded assets, apply transformations on demand, and track file inventory alongside other business data.

Filestack's API covers three main areas: the Store API for managing files stored in Filestack's cloud (or connected S3/GCS buckets), the Processing API for applying real-time transformations to images and documents (resize, crop, watermark, convert, compress), and the CDN URL pattern for serving transformed files. Authentication is simple — your API key is included as a path segment or query parameter in API requests, making configuration straightforward.

Common Retool apps built on Filestack include: media asset browsers that display uploaded images with metadata and allow on-demand transformation previews, image processing batch tools that apply resizing or watermarking to selected assets and generate new CDN URLs, file inventory dashboards that combine Filestack file handles with product or content records from a database, and upload monitoring panels that track file size, type, and upload frequency over time.

## Before you start

- A Filestack account with an active API key (available in the Filestack Developer Portal)
- File handles from your Filestack integration stored in your application database (or use known test handles)
- A Retool account with permission to create Resources
- Basic familiarity with URL construction and REST API concepts

## Step-by-step guide

### 1. Locate your Filestack API key

Log into your Filestack account at app.filestack.com. Once logged in, you land on the Dashboard which displays your API key prominently at the top of the page. This is your publishable API key (used in frontend picker embeds) but also valid for server-side API calls from Retool. If you need a more restricted key or want to use Filestack's Security (policy + signature) for sensitive operations, navigate to the Security tab in your dashboard to configure signed URLs with time-limited access. For standard Retool integrations accessing file metadata and processing APIs, the regular API key is sufficient. Copy the API key value. If your account has multiple apps, each app has its own API key — select the app whose files you want to manage and copy the corresponding key. Note that Filestack API keys are not secret by default (they are embedded in frontend picker code), but server-side access through Retool's proxy still prevents exposure of your account's full capabilities to end users.

**Expected result:** You have your Filestack API key copied from the Filestack Dashboard and ready to configure in Retool.

### 2. Create the Filestack REST API Resource in Retool

In Retool, navigate to the Resources tab and click 'Create New'. Select 'REST API' from the resource type list. Filestack has two different base URLs depending on the operation type — the CDN and metadata URL is 'https://cdn.filestackcontent.com' and the Store API URL is 'https://www.filestackapi.com'. For general use, set the Base URL to 'https://cdn.filestackcontent.com' as most metadata and transformation operations use this endpoint. Under the Headers section, you can optionally add the API key as a custom header for some endpoint types, but for most Filestack operations, the API key is included as a URL path segment rather than a header. Add 'Content-Type: application/json' as a default header. Store your API key in Retool Settings → Configuration Variables as 'FILESTACK_API_KEY' — while not strictly a secret for this service, storing it as a configuration variable makes it easy to update across all queries if you ever rotate your key. Click 'Save Resource'.

```
{
  "Base URL": "https://cdn.filestackcontent.com",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Note": "API key is included as a URL path segment: /api_key/metadata/file_handle"
}
```

**Expected result:** The Filestack REST API Resource is saved in Retool with the CDN base URL configured and your API key stored as a configuration variable.

### 3. Query file metadata for stored file handles

Create a new query using the Filestack CDN resource to retrieve metadata for a specific file handle. Set the method to GET and the path to '/{{ retoolContext.configVars.FILESTACK_API_KEY }}/metadata/{{ fileHandleInput.value }}'. Filestack's metadata endpoint returns a JSON object with file properties including filename, size (in bytes), type (MIME type), width and height (for images), created timestamp, and the CDN URL. This query requires a known file handle — typically a string like 'ABC123XYZ' that was returned when the file was originally uploaded via the Filestack picker or API. If your application stores Filestack handles in a database, create a database query to retrieve the list of handles and populate a Select dropdown or Table, then bind the selected handle to this metadata query. The metadata response gives you all the information needed to display file information without downloading the file itself.

```
// GET /{api_key}/metadata/{file_handle}
// Returns: filename, size, type, width, height, created, url

// Transformer: format metadata for display
const meta = data || {};
return {
  filename: meta.filename || 'Unknown',
  file_type: meta.mimetype || 'Unknown',
  size_kb: meta.size ? Math.round(meta.size / 1024 * 10) / 10 : 0,
  size_display: meta.size
    ? meta.size < 1048576
      ? `${Math.round(meta.size / 1024 * 10) / 10} KB`
      : `${Math.round(meta.size / 1048576 * 100) / 100} MB`
    : 'Unknown',
  dimensions: meta.width && meta.height
    ? `${meta.width} × ${meta.height}px`
    : 'N/A (non-image)',
  cdn_url: meta.url || `https://cdn.filestackcontent.com/${fileHandleInput.value}`,
  uploaded: meta.uploaded
    ? new Date(meta.uploaded * 1000).toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' })
    : 'Unknown'
};
```

**Expected result:** The metadata query returns formatted file properties including name, type, size, dimensions, and CDN URL for the selected file handle.

### 4. Generate image transformation URLs and preview transformed files

Filestack's transformation API is URL-based — you construct a CDN URL with transformation parameters embedded as path segments, and Filestack processes and serves the transformed file on demand. This URL can be used directly in Retool Image components for live previews without making a separate API call. The transformation URL format is: 'https://cdn.filestackcontent.com/[transform_params]/[file_handle]'. Common transformations include resize (width, height, fit mode), output format conversion (format=webp, format=png), quality adjustment (quality=80), crop (crop=dim:[x,y,w,h]), and watermark overlays. Build a Retool form with number inputs for target width and height, a Select dropdown for output format, and a slider for quality. Use a JavaScript transformer to construct the transformation URL from these component values and display a live preview in an Image component.

```
// JavaScript transformer: build Filestack transformation URL
const apiKey = retoolContext.configVars.FILESTACK_API_KEY;
const handle = fileHandleInput.value || '';
const width = widthInput.value || '';
const height = heightInput.value || '';
const format = formatSelect.value || '';
const quality = qualitySlider.value || 90;
const fit = fitSelect.value || 'scale';

if (!handle) return '';

// Build transformation chain
const transforms = [];

if (width || height) {
  const resizeParams = [
    width ? `width:${width}` : '',
    height ? `height:${height}` : '',
    `fit:${fit}`
  ].filter(Boolean).join(',');
  transforms.push(`resize=${resizeParams}`);
}

if (quality !== 90) {
  transforms.push(`quality=value:${quality}`);
}

if (format) {
  transforms.push(`output=format:${format}`);
}

const transformString = transforms.join('/');
return transformString
  ? `https://cdn.filestackcontent.com/${apiKey}/${transformString}/${handle}`
  : `https://cdn.filestackcontent.com/${handle}`;
```

**Expected result:** The transformation URL builder generates a properly formatted Filestack CDN URL with the specified transformations. An Image component bound to this URL displays a live preview of the transformed file.

### 5. Build the media asset management panel with bulk operations

Assemble a complete media management interface in Retool. Create a Table component that reads file handles and associated metadata from your application database. For each row, display the file name, type, size, upload date, and a thumbnail image generated using Filestack's resize transformation (target width: 100px). Add a row selection feature that allows selecting multiple file handles for batch operations. Create action buttons: 'Preview' opens a modal with the full-size image and transformation controls built in step 4; 'Copy CDN URL' copies the original CDN URL to clipboard; 'Convert to WebP' triggers a store operation via the Filestack API that permanently stores a WebP-converted version and saves the new handle to the database. For the store operation, use POST to 'https://www.filestackapi.com/api/store/S3?key={{ retoolContext.configVars.FILESTACK_API_KEY }}' with the file URL in the body to save processed versions back to storage. For complex integrations involving multiple API endpoints and database updates, RapidDev's team can help architect and build your Retool solution.

```
// POST to Store API to save transformed version
// URL: https://www.filestackapi.com/api/store/S3?key={api_key}
// Body:
{
  "url": "https://cdn.filestackcontent.com/output=format:webp/quality=value:85/{{ table1.selectedRow.data.file_handle }}"
}

// Response includes new file handle for the stored WebP version:
// { "url": "https://cdn.filestackcontent.com/NEW_HANDLE", "handle": "NEW_HANDLE", ... }

// On success: update database record with new webp_handle
// updateProduct.trigger({ additional_scope: { webp_handle: storeResult.data.handle } });
```

**Expected result:** The media panel shows a browsable table of uploaded files with thumbnails, allows previewing files with interactive transformation controls, and can save processed versions back to Filestack and update your database.

## Best practices

- Store your Filestack API key in Retool configuration variables — while Filestack keys appear in frontend code, using configuration variables makes rotation easy and prevents accidental exposure in query bodies
- Use URL-based transformations for previews rather than storing every variant — Filestack caches CDN transformations automatically, so building preview URLs is more storage-efficient than storing every size and format
- Build file handle lookup from your database rather than from Filestack's API directly — Filestack does not provide a list-all-files endpoint, so your database is the source of truth for which handles are in use
- Cache metadata queries for 5-10 minutes — file metadata (size, type, dimensions) does not change after upload and does not need real-time refresh on every component interaction
- Implement error handling for broken handles — file handles in your database may refer to files that have been deleted from Filestack; add 404 handling in your transformer to mark these as 'missing' rather than showing broken image placeholders
- Use Filestack's output transformation to convert images to WebP format for web display — WebP images are typically 25-35% smaller than equivalent PNG or JPEG files, improving dashboard load times when displaying many images
- When running bulk operations on many file handles, process them in batches of 10-20 using a Retool Workflow with delays between batches to avoid overwhelming Filestack's processing API

## Use cases

### Build a media asset browser with transformation previews

Create a Retool panel that displays Filestack file handles stored in your database alongside their processed image previews. For each file handle, generate thumbnail URLs using Filestack's URL-based transform syntax (resize, format conversion). Allow users to select a file and adjust transformation parameters interactively — changing width, height, and output format — with a live preview updating in real time using the generated CDN URL. Provide a 'Copy URL' button to copy the final transformation URL for use in other tools.

Prompt example:

```
Build a Retool media asset browser that reads Filestack file handles from a database table, displays thumbnail previews using Filestack's resize transformation, and allows users to select an image and configure custom resize parameters. Show the resulting transformation URL and a preview of the transformed image.
```

### Create an image batch processing tool

Build a Retool tool for operations teams that need to apply standard transformations to multiple images at once — resizing product images to specific dimensions, converting PNG uploads to WebP format, or adding a watermark to all assets in a category. Select multiple file handles from a Table, configure the transformation parameters, and generate new processed file handles via the Filestack Store API, saving the new handles back to your database alongside the originals.

Prompt example:

```
Create a Retool batch image processor where users select multiple Filestack file handles from a product image table, specify a target width and height, output format, and quality setting, then click Process to generate resized versions via the Filestack API and save the new handles to the products database.
```

### Build a file inventory and metadata dashboard

Query Filestack's metadata endpoint for all file handles stored in your application database to build an inventory view showing file type, size, upload source, and current CDN URL. Identify oversized files, non-compliant formats, or files missing from Filestack's CDN (returning 404). Combine file metadata with application data — associating files with the users, products, or content records that uploaded them — to give the content team full visibility into the media library.

Prompt example:

```
Build a Retool file inventory dashboard that queries Filestack metadata for all file handles stored in the application database, showing file name, size, type, and upload date. Include filters for file type and size range, and flag any file handles that return 404 from Filestack's CDN as 'broken links'.
```

## Troubleshooting

### Metadata query returns 'not_found' or 404 for a known file handle

Cause: The file handle is invalid, the file was deleted from Filestack storage, or the file belongs to a different Filestack app than the API key being used.

Solution: Verify the file handle is complete and correctly copied — Filestack handles are typically 20 characters. Check the Filestack Dashboard under Storage to confirm the file is still present. If your account has multiple apps, ensure the API key in Retool matches the app that contains the file. File handles are app-specific and do not transfer between Filestack applications.

### Transformation URLs return 'missing security' or 403 error

Cause: The Filestack account or app has Security (Policies) enabled, which requires all CDN requests to include a signed policy and HMAC signature. Without these, transformation requests are blocked.

Solution: In the Filestack Dashboard, navigate to the Security tab and check if 'Security' is enabled for your app. For internal Retool tools where the API key is server-side anyway, you can disable security requirements for specific operations. Alternatively, implement signed URL generation: create a policy JSON object with expiry and allowed calls, base64-encode it, and generate an HMAC-SHA256 signature using your Filestack app secret. Include both as query parameters: ?policy=BASE64_POLICY&signature=HMAC_SIG.

### Image transformation URL works in browser but Image component in Retool shows broken image

Cause: CORS restrictions on Filestack's CDN may block direct image loading from Retool's domain, or the transformation is producing an error that returns HTML instead of image data.

Solution: Test the transformation URL directly in a browser — if it loads correctly there but not in Retool's Image component, the component may have a URL parsing issue with complex transformation strings. Simplify the URL by building it in a JavaScript transformer and verifying the output format. For CORS issues, use Retool's Custom HTTP Headers to proxy the request, or use a GET query that fetches the image data and serves it through the Retool proxy.

### Store API returns 400 Bad Request when saving a transformed file

Cause: The request body format is incorrect, the source URL is not accessible by Filestack's servers, or the destination storage configuration is missing.

Solution: Verify the URL in the request body is a complete, publicly accessible URL (not localhost). Filestack's Store API fetches the source URL from its own servers, so it must be reachable from the internet. Check that the Store API endpoint includes your API key as a query parameter (?key=YOUR_KEY) rather than in the path. If you are storing to a connected S3 bucket, verify the bucket permissions in the Filestack Dashboard allow Filestack to write files.

## Frequently asked questions

### Does Retool have a native Filestack connector?

No, Retool does not have a native Filestack connector. You connect using a REST API Resource with your Filestack API key included in request URLs. Filestack's CDN-based transformation system means many operations are URL-construction tasks rather than traditional REST API calls, which can be accomplished with JavaScript transformers in Retool without making additional API requests.

### Can I use Filestack's file picker inside a Retool app?

Filestack's file picker is a JavaScript SDK component that can be embedded in Retool Custom Components. Add a Custom Component to your Retool app and include the Filestack picker SDK in the component's HTML. On upload completion, use the Custom Component's model.setValue() method to pass the resulting file handle back to the Retool app, where other queries can use it for metadata retrieval or transformation.

### How do I list all files stored in my Filestack account?

Filestack does not provide a list-all-files API endpoint. Your application's database is the source of truth for which Filestack handles exist. When designing Filestack integrations, always store file handles in your database at upload time, including metadata like original filename, upload timestamp, and associated record ID. This makes Retool's file management queries straightforward — read handles from your database, then fetch metadata from Filestack for each.

### Can I delete files from Filestack storage using the API?

Yes. Use DELETE to 'https://www.filestackapi.com/api/file/{file_handle}?key={api_key}' to permanently delete a file from Filestack storage. This is an irreversible operation — once deleted, the file handle no longer works and the CDN URL returns 404. Always build a confirmation prompt in Retool before triggering delete operations, and remove the handle from your database in the same workflow to keep records consistent.

### Are there rate limits on Filestack API calls?

Filestack rate limits vary by plan. The Processing API for transformations is CDN-backed and has very high throughput limits for serving existing transformations. The metadata API and Store API have per-account request limits. For high-volume operations like batch metadata queries for hundreds of files, implement request batching with delays between groups to stay within limits. Check your Filestack plan details for specific rate limit numbers.

---

Source: https://www.rapidevelopers.com/retool-integrations/filestack
© RapidDev — https://www.rapidevelopers.com/retool-integrations/filestack