Filestack Getting Started: Quickstart Guide & First Request (2026)

Getting started overview

Integrating Filestack involves several steps, from account creation to executing your first API call. This guide focuses on the initial setup required to begin using Filestack for file uploads, transformations, and content delivery. The process typically includes signing up for an account, obtaining your API key, and performing a basic operation using either an SDK or direct API calls. Filestack supports direct file uploads from various sources and offers extensive image and video transformation capabilities.

Before proceeding, ensure you have access to a development environment for your preferred language or framework. Filestack provides SDKs for multiple platforms including JavaScript, React, Angular, iOS, Android, Python, Ruby, PHP, Java, and .NET. For the purpose of this guide, examples will focus on common web and backend languages.

The core products you will interact with include the File Uploader, Image Transformations, Video Transformations, Content Ingestion, File Storing, and Content Delivery Network (CDN). Each of these services is accessible via the Filestack API, secured by your API key.

Create an account and get keys

To start with Filestack, you must first create an account and retrieve your API key. This key is central to authenticating all your requests to the Filestack API.

1. Sign up for a Filestack account

Navigate to the Filestack homepage and locate the signup option. You can choose between a free tier or a paid plan. The free tier offers 500 uploads per month, 5GB of storage, and 5GB of bandwidth, which is sufficient for initial testing and development.

2. Access your API key

After successfully signing up and logging into your Filestack dashboard, your API key will be displayed. This key is typically found in the "API Keys" or "Settings" section of your account. It is a unique identifier that authorizes your application to interact with Filestack services. Keep your API key secure and do not expose it in client-side code without appropriate precautions like proxying requests through your backend or using signed policies for uploads, as detailed in Filestack's security documentation.

3. Understand API key types

Filestack primarily uses a single API key for most operations. However, for enhanced security, especially in production environments, you can implement policies and signatures. Policies define permissions (e.g., allow specific transformations, set file size limits) and signatures ensure that requests adhere to these policies. While not strictly necessary for a first request, understanding these advanced security features is crucial for production deployments.

Your first request

This section outlines how to make your first authenticated request to Filestack. We will demonstrate a simple file upload using a browser-based JavaScript SDK and a direct REST API call using curl for backend or testing purposes. Before proceeding, ensure you have your API key ready.

Method 1: JavaScript SDK (Browser)

The JavaScript SDK provides a convenient way to integrate Filestack's uploader into web applications. Follow these steps:

1. Include the SDK: Add the Filestack JavaScript SDK to your HTML file. You can use a CDN:
   

   <script src="https://static.filestackapi.com/filestack-js/3.x.x/filestack.min.js"></script>

   Replace 3.x.x with the latest version of the SDK.
2. Initialize the client: In your JavaScript code, initialize the Filestack client with your API key.
   

   const client = filestack.init('YOUR_API_KEY');

3. Open the picker: Use the picker method to open Filestack's file uploader interface.
   

   client.picker({
     onFileUploadFinished: (file) => {
       console.log(file); // Log the uploaded file details
       // file.url contains the URL of the uploaded file
     }
   }).open();

   This code will open a modal that allows users to select files from their local device, cloud storage providers (like Google Drive, Dropbox), or social media.
   Upon successful upload, the onFileUploadFinished callback will receive a file object containing details, including the URL to access the uploaded content. For more advanced options, refer to the Filestack JavaScript Picker documentation.

Method 2: REST API (Curl)

For direct server-side uploads or testing, you can use the REST API. This example demonstrates uploading a local file.

1. Prepare your file: Ensure you have a file available locally (e.g., myimage.jpg).
2. Execute the curl command: Use the following command in your terminal, replacing YOUR_API_KEY and myimage.jpg with your actual values.
   

   curl -F "[email protected]" https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY

   • -F "[email protected]": Specifies the file to upload. The @ prefix tells curl to read the content from the local file system.
   • https://www.filestackapi.com/api/store/S3: This is the endpoint for storing files to S3-compatible storage, which is Filestack's default.
   • key=YOUR_API_KEY: Your API key for authentication.
3. Verify the response: A successful response will return a JSON object containing information about the uploaded file, including its URL, handle, and MIME type. For example:
   

   {
     "url": "https://cdn.filestackcontent.com/YOUR_FILE_HANDLE",
     "handle": "YOUR_FILE_HANDLE",
     "size": 12345,
     "mimetype": "image/jpeg",
     "filename": "myimage.jpg"
   }

   The url field provides the direct link to your uploaded file, ready for retrieval or further transformations. For more details on direct API uploads, consult the Filestack Upload API documentation.

Common next steps

After successfully performing your first upload, consider these common next steps to further integrate Filestack into your application:

• Image and Video Transformations: Explore Filestack's powerful transformation API. You can resize images, apply watermarks, convert formats, or transcode videos directly via URL manipulation. For example, to resize an image to 200 pixels width, you might append /resize=width:200/ to your file URL.
• Webhooks: Implement webhooks to receive real-time notifications about file events, such as successful uploads, processing completion, or failures. This is crucial for building asynchronous workflows.
• Security Policies and Signatures: For production environments, generate and use security policies and signatures to control access, set expiry times for URLs, and restrict operations. This prevents unauthorized usage of your API key and content.
• Advanced Uploader Options: Customize the Filestack picker with various options, such as enabling specific sources (e.g., only local files and Dropbox), setting maximum file sizes, or defining custom upload locations.
• Client-side Validation: Implement client-side validation to ensure files meet specific criteria (e.g., file type, size) before they are sent to Filestack, improving user experience and reducing unnecessary uploads. For more on client-side security, refer to general web security practices, such as those outlined by Mozilla Developer Network's web security guide.
• Error Handling: Implement robust error handling for both client-side SDK usage and server-side API calls to gracefully manage upload failures, transformation errors, or network issues.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to common problems and their solutions:

1. Invalid API Key

• Symptom: API returns "Invalid Key" or "Unauthorized" error.
• Solution: Double-check that you are using the correct API key from your Filestack dashboard. Ensure there are no leading or trailing spaces, and that it's correctly passed in your request (e.g., as a query parameter key=YOUR_API_KEY).

2. Network Issues

• Symptom: Request times out or fails to connect.
• Solution: Verify your internet connection. If using curl, ensure you don't have proxy issues. Check Filestack's status page for any ongoing service disruptions.

3. CORS Errors (for JavaScript SDK)

• Symptom: Browser console shows Cross-Origin Resource Sharing (CORS) errors.
• Solution: Filestack's SDKs are designed to handle CORS, but if you're making direct AJAX calls from the browser to Filestack's API endpoints, ensure your origin is allowed. Filestack typically manages this internally, but if you're using a custom setup or a proxy, configure CORS headers correctly on your server if it's intercepting requests.

4. File Not Found / Incorrect Path (for curl)

• Symptom: curl returns an error indicating the file doesn't exist or cannot be read.
• Solution: Verify the file path provided in -F "[email protected]". Ensure the file exists in the directory where you are running the curl command, or provide its absolute path.

5. Missing Required Parameters

• Symptom: API returns an error about missing parameters.
• Solution: Review the Filestack API documentation for the specific endpoint you are calling. Ensure all required parameters are included in your request. For uploads, the file itself is a mandatory parameter.

6. SDK Specific Errors

• Symptom: Errors originating from the SDK (e.g., JavaScript console errors).
• Solution: Consult the relevant SDK documentation for troubleshooting specific to your chosen library. Ensure you are using a compatible version and following the correct initialization and method calls.

Quick-reference table: Getting Started Steps