Filestack Architecture Overview

Filestack is a flexible upload API hosted in the cloud. We facilitate the uploading, transformation, and distribution of end-user content. File assets can be any file type: images, office documents, audio files, videos, pdfs, photoshop files, illustrator files and countless other file types are fully supported.

After assets have been uploaded into our system either through our file uploader or through our rest api, you can run them through our transformation engine for processing. For example you can compress files or crop and resize them.

Filestack Handles, URL based manipulation, and Content Delivery

For every file uploaded into Filestack, a unique handle is generated. The handle can be used in a number of ways. For example, when an image is uploaded it gets a unique handle assigned to it:

You can use this handle reference to modify and convert the source file on the fly by using that handle in the appropriate URL:

Filestack Content Delivery

Filestack API Architecture

Filestack Transformation Architecture

Filestack Metadata

After a successful call to our API we return a standard JSON object that contains information about the file. The properties of the object are as follows:

Here is a sample Filestack object. We will discuss each field below.


The name of the file that was uploaded.


The Filestack file handle. This is useful because other Filestack methods accept handles as their input.


The mimetype of the file, if available.


The size of the file in bytes, if available. We will attach this directly to the returned metadata when we have it, otherwise you can always get the size by calling client.retrieve(filestackHandle, { metadata: true })


The source the file was uploaded from. This could be "local_file_system", "instagram", "dropbox" or any other source.


The Filestack URL that points to the uploaded file.


If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), the key will tell you where in your storage container this file was placed.


If the file was stored in one of the file stores you specified or configured (S3, Rackspace, Azure, etc.), the container will be the bucket/container the file was placed in.


The status of the upload. This is not returned if the Filestack link is a symbolic link. Possible statuses are "Stored", "InTransit", and "Failed". "InTransit" means the file has not yet been copied to your bucket, but the Filestack link will still be valid and won't change once the file's status changes to "Stored". If the status returned is other than "Stored", and you have configured webhooks, you will receive a webhook when the status changes to "Stored".