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
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.
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.
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.
Delete files through the API. Remove files from Filestack and your storage, or keep the storage copy while clearing the Filestack reference.
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
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"
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"
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"
}
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/"
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"
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
}
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"
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"
The response confirms the update:
{
"url": "https://cdn.filestackcontent.com/YOUR_HANDLE",
"mimetype": "text/plain",
"isWriteable": true,
"size": 19,
"filename": "updated-file.txt"
}
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"
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
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"
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:
Processing API for image and document transformations
Webhooks for real-time upload notifications
Workflows for automating file processing pipelines
The article was originally published on the Filestack blog.