DEV Community

Cover image for How to Manage Files with the Filestack File API
Froala
Froala

Posted on • Originally published at blog.filestack.com

How to Manage Files with the Filestack File API

#filestack #programming #javascript #webdev

If you’re using Filestack, you probably started with our File Picker. It’s the fastest way to get uploads working. But here’s something you might not know: you can also manage files programmatically without the Picker, directly from your backend.

The file uploader API gives you full control over file operations through REST endpoints. This means you can store files from URLs, update existing uploads, pull metadata, and delete files, all from server-side code. It’s the layer that powers what happens after (or instead of) the Picker.

In this guide, we’ll walk through each endpoint in the Filestack File API. By the end, you’ll know how to store files to your preferred cloud provider, fetch file metadata, update existing files, and remove them entirely.

5 Key Takeaways

  1. Store files without the Picker. Upload directly from your server using URLs or binary data. This is useful for migrations, automated imports, or backend processing pipelines.

  2. Retrieve metadata on demand. Check file size, type, upload timestamp, and storage location without downloading the entire file. You can also generate hash values for integrity verification.

  3. Overwrite files while keeping the same URL. Update profile pictures, documents, or any content that changes over time. Existing links continue to work with the new file.

  4. Delete files through the API. Remove files from Filestack and your storage, or keep the storage copy while clearing the Filestack reference.

  5. All operations use a single base endpoint. Every request goes to https://www.filestackapi.com/api/file, making integration straightforward.

When to Use the File API Instead of the Picker

The Picker is great for user-facing uploads. But certain situations call for direct API access:

  • Data migrations. Moving files from another service? Use the Store endpoint to import them by URL without downloading to your server first.

  • Automated workflows. Processing files in a cron job or background worker? The API lets you store, transform, and manage files without any UI.

  • Server-side uploads. Accepting files through your own form or API? Post them directly to Filestack from your backend.

  • File versioning. Need to replace a file while keeping the same handle? The Overwrite endpoint updates the content without breaking existing links.

  • Cleanup operations. Building admin tools or retention policies? The Delete endpoint lets you remove files programmatically.

If any of these match your use case, the File API is what you need.

What You’ll Need Before Getting Started

Before diving into the code, make sure you have:

  • A Filestack API key (grab one free at filestack.com/signup-start)

  • A configured storage provider (S3 is the default, but Azure, GCS, Dropbox, and Rackspace are also supported)

  • Basic familiarity with REST APIs and cURL

All requests go to a single base endpoint:

https://www.filestackapi.com/api/file
Enter fullscreen mode Exit fullscreen mode

Storing Files to Your Cloud Provider

The POST /store endpoint lets you upload files directly to any supported backend. As a result, you get back a JSON response with metadata, including a CDN URL you can use immediately.

Here’s how to store a file from a public URL:

curl -X POST \
    -d url="https://example.com/image.png" \
    "https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can upload a local file using binary data:

curl -X POST \
    --data-binary @photo.png \
    --header "Content-Type:image/png" \
    "https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode

The response includes everything you need to reference the file later:

{
    "url": "https://cdn.filestackcontent.com/s7tdGfE5RRKFUxwsZoYv",
    "size": 8331,
    "type": "image/png",
    "filename": "photo.png",
    "key": "a1RyBxiglW92bS2SRmqM_photo.png"
}
Enter fullscreen mode Exit fullscreen mode

Storage Parameters Worth Knowing

You can customize where and how files are stored using query parameters:

ParameterWhat It DoesfilenameSets a custom name for the stored filepathSpecifies the directory path within your bucketcontainerTargets a specific bucket instead of your defaultaccessSets S3 permissions to “public” or “private”base64decodeDecodes base64 data before writing the file

For example, if you want to store a file in a specific folder with a custom name:

curl -X POST \
    -d url="https://example.com/document.pdf" \
    "https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY&filename=report-2024.pdf&path=documents/reports/"
Enter fullscreen mode Exit fullscreen mode

Retrieving File Metadata

Once a file is stored, you’ll often need to check its properties without downloading the entire file. The metadata endpoint handles this efficiently.

curl -X GET "https://www.filestackapi.com/api/file/YOUR_HANDLE/metadata"
Enter fullscreen mode Exit fullscreen mode

This returns detailed information about your file:

{
    "mimetype": "image/png",
    "uploaded": 1431950945811.783,
    "container": "your-bucket-name",
    "writeable": true,
    "filename": "photo.png",
    "location": "S3",
    "path": "kWg7nloGTWmHFi5nlbF9_photo.png",
    "size": 270
}
Enter fullscreen mode Exit fullscreen mode

Getting File Hashes for Verification

If you need to verify file integrity, you can request hash values. Simply add the hash type as a query parameter:

curl -X GET "https://www.filestackapi.com/api/file/YOUR_HANDLE/metadata?sha256=true"
Enter fullscreen mode Exit fullscreen mode

We support MD5, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. This is particularly useful when you need to confirm that a file hasn’t been corrupted during transfer.

Overwriting Existing Files

Sometimes users need to update a file while keeping the same URL. The overwrite endpoint makes this possible. However, this action requires security credentials since it modifies existing data.

curl -X POST \
    --data-binary @updated-file.txt \
    --header "Content-Type:text/plain" \
    "https://www.filestackapi.com/api/file/YOUR_HANDLE?policy=POLICY&signature=SIGNATURE"
Enter fullscreen mode Exit fullscreen mode

The response confirms the update:

{
    "url": "https://cdn.filestackcontent.com/YOUR_HANDLE",
    "mimetype": "text/plain",
    "isWriteable": true,
    "size": 19,
    "filename": "updated-file.txt"
}
Enter fullscreen mode Exit fullscreen mode

Because the handle stays the same, any existing links to this file will now serve the updated version. This is useful for profile pictures, documents that need revisions, or any content that changes over time.

Deleting Files

When it’s time to remove a file, the delete endpoint handles that cleanly. Like overwrite, this requires security credentials.

curl -X DELETE \
    "https://www.filestackapi.com/api/file/YOUR_HANDLE?key=YOUR_API_KEY&policy=POLICY&signature=SIGNATURE"
Enter fullscreen mode Exit fullscreen mode

By default, this removes the file from both Filestack and your storage container. However, if you want to keep the file in storage but remove it from Filestack’s system, add the skip_storage=true parameter.

Securing Your API Requests

For operations that modify or delete files, you’ll need to generate security credentials. We use a policy and signature system that gives you control over what actions are allowed.

You can pass credentials in two ways. First, as query parameters:

?policy=POLICY&signature=SIGNATURE
Enter fullscreen mode Exit fullscreen mode

Or second, using HTTP Basic Authentication:

curl -X POST \
    -u "app:YOUR_SECRET_KEY" \
    -d "url=https://example.com/image.png" \
    "https://www.filestackapi.com/api/file/YOUR_HANDLE"
Enter fullscreen mode Exit fullscreen mode

Check out our security documentation for details on generating policies and signatures.

Best Practices for File Delivery

While the File API can retrieve files, we recommend using our CDN for serving content to end users. The CDN is optimized for delivery and costs less in bandwidth. Use the File API for management operations like storing, updating metadata, and deleting files.

What’s Next?

Now that you understand how the File API works, you might want to explore:

The article was originally published on the Filestack blog.

Top comments (0)