Filestack Logo Docs homepage

Uploading

Basic Uploads

Beyond the picker widgets, Filestack still offers easy ways to get files uploaded and ready for delivery.

If all you need is one HTTP request from file to cloud then Filestack can help. The Filestack File API provides several methods for uploading files over HTTP:

Upload file

Sample request:

curl -X POST \
    --data-binary @filename.png \
    --header "Content-Type:image/png" \
    "https://www.filestackapi.com/api/store/S3?key=MY_API_KEY"

Sample response:

{
  "url": "https://cdn.filestackcontent.com/s7tdGfE5RRKFUxwsZoYv",
  "size": 8331,
  "type": "image/png",
  "filename": "watermark.png",
  "key": "a1RyBxiglW92bS2SRmqM_watermark.png"
}

Upload from URL

Sample request:

curl -X POST \
    -d url="https://assets.filestackapi.com/watermark.png" \
    "https://www.filestackapi.com/api/store/S3?key=MY_API_KEY"

Sample response:

{
  "url": "https://cdn.filestackcontent.com/s7tdGfE5RRKFUxwsZoYv",
  "size": 8331,
  "type": "image/png",
  "filename": "watermark.png",
  "key": "a1RyBxiglW92bS2SRmqM_watermark.png"
}

Multipart Uploads

A more robust uploading flow is available through the Filestack Upload API and available to use in our API Clients. Use of this API outside of our clients is currently not supported by our SLA.

By default all Filestack applications using multi-part uploads will use Filestack S3 as the storage backend. When using your own S3 bucket as a storage backend the uploads will be sent directly to your bucket from the client, but make sure you configure your S3 bucket first.

Other storage backends are supported for multi-part uploads, but they are not direct because all files go to Filestack S3 initially and are transferred to your own storage in the background. Upload webhooks are helpful in this case to notify you when background transfers are complete.

Content Ingestion Network

The Content Ingestion Network utilizes an array of global edge servers that serve as shortest-hop points for you and your customer’s upload requests. This is made possible by the availability of our services across AWS regions. This feature can be enabled on your application without any extra configuration. However, if you are using your own S3 bucket you will need to configure it to support the Filestack CIN.

Using the CIN, as soon as a file is uploaded it goes to the nearest Filestack ingestion point accessible to the user and a filelink is created. The filelink can be used immediately, even as the CIN moves the file to its final location (our storage or yours).

The metadata?upload_status=true on your file will return a file status. Here are the three potential file status values that will be returned:

  • Started: file has begun uploading to the nearest POP
  • In Transit: file has hit the POP and is available but has not yet hit final storage destination.
  • Complete: file has been fully uploaded to the final storage destination.

Intelligent Ingestion

When Intelligent Ingestion is enabled on your application, our Upload API adds support for adjusting the multi-part parameters on the fly. Our API clients have the ability to determine poor network conditions, such as on mobile networks or networks with sub-standard or limited QoS.

For applications with FII enabled, uploaded parts that time out are re-chunked and tried again until the minimum chunk size is reached. This ensures that QoS constraints or spotty network conditions do not cause a failure of the entire upload.

Without FII enabled, the API client retry logic may usually be enough to ensure a part gets uploaded, but if the part size is too large for the network conditions, then the retried part will keep failing. FII adds an adaptive multi-part flow to help resolve these kinds of use cases.

For example, if using our Javascript API client, you will need to enable the intelligent option. This feature will not work if FII is not enabled for the application.

Please contact sales if you would like to inquire about enabling this.

Cloud Uploads

Only available through our pickers, this feature allows you to upload files from your users’ cloud provider accounts. These are powered by our proprietary Cloud API and offer the same storage options for local file uploads.

Users will be asked to authorize the Filestack OAuth clients in the picker UI, but you can use your own OAuth clients if your account plan supports it.

Use of the Cloud API outside of the pickers is not supported by our SLA.

Upload tags

Upload tags allows you to pass custom data (tags) with each file that is uploaded using Filestack. That data should have a format of key-value pair and it will be returned in the exact same configuration in the upload response and in the Webhook .

Using Upload Tags you will be able to match the data from your application (for example userID or transactionID) with the key-value pair from the upload.

Upload with Tags

You can specify the Upload tags using our File Picker and/or the backend code.

Upload using Picker

Add the tags parameter in the uploadConfig option and specify the key-value pair. Value accept callback function that will be invoked before file upload starts with one parameter of current file:

   uploadConfig: {
    	tags: {
          "foo": "bar",
          "foo2": (file) => "bar2_" + file.name
      }
    },

Example Picker code:

const client = filestack.init(APIKEY);
const options = {
  uploadConfig: {
    	tags: {
     		"foo": "bar"
      }
    },
  fromSources: ["local_file_system","instagram","facebook"],
};
client.picker(options).open();

Additionally, tags can be added dynamically:

uploadConfig: {
  tags: {
    userId: '123',
    title: 'asd',
    dynamic: (file) => { return 'DYNAMIC_TAG' + file.name;}
  },
},

Upload using Filestack Python SDK

Add the upload_tags parameter in the store_params option and specify the key-value pair:

from filestack import Client

client = Client(APIKEY)

store_params = {
    'location': 's3', 
    'path': 'folder/subfolder/',
    'upload_tags': {
          "foo":"bar"
    }
}
filelink = client.upload(filepath='path/to/filename.jpg', store_params=store_params)

Upload response

The example upload response with upload tags:

{
  "handle":"HANDLE",
  "url":"https://cdn.filestackcontent.com/HANDLE",
  "filename":"filename.jpg",
  "size":68772,
  "mimetype":"image/jpeg",
  "key":"HLcysRpSTcOQGVENECH9_filename.jpg",
  "container":"YOUR_BUCKET",
  "status":"Stored",
  "upload_tags":
        {"foo":"bar"}
  }

Webhook response

The example webhook with upload tags:

{"id": 115857146,
  "action": "fp.upload", 
  "timestamp": 1594729503, 
  "text": 
      {
      "container": "container_name", 
      "url": "https://cdn.filestackcontent.com/HANDLE", 
      "filename": "filename.jpg", 
      "client": "Computer", 
      "key": "mHkuZVnuTyKSwowoXuxl_filename.jpg", 
      "type": "image/jpeg", 
      "status": "Stored", 
      "size": 68772, 
      "upload_tags": 
                {"foo": "bar"}
    }
}

Upload tags requirements

If you would like to include the Upload Tags into your code, you need to remember about the requirements listed below:

  • Only string => string pairs are allowed.
  • You can provide up to 10 tags per upload.
  • Key should be unique (case sensitive) within the upload.
  • Key can be up to 128 Unicode characters in length.
  • Values can be up to 256 Unicode characters in length.