Retrieving a File with the REST API

Whenever you get or save a file using the Filestack javascript library, you get a Filestack file URL that acts a pointer to the selected or saved file. The most common thing is just to download the contents of the file, but there's a number of additional features these urls enable via our REST interface.

Using REST to Retrieve Files and File Info

To get the contents of the file, use a GET request on the url provided:

>>> curl -X GET "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby" > \get_success.png

If you have security enabled on your API key, then you need to include a valid policy and signature with your request:

>>> curl -X GET "https://www.filestackapi.com/api/file/KW9EJhYtS6y48Whm2S6D?signature=4098f262b9dba23e4766ce127353aaf4f37fde0fd726d164d944e031fd862c18&policy=eyJoYW5kbGUiOiJLVzlFSmhZdFM2eTQ4V2htMlM2RCIsImV4cGlyeSI6MTUwODE0MTUwNH0=" > \get_success.png

To get the metadata of the file, use a GET request:

>>> curl -X GET "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby/metadata"

You can get a specific metadata value:

>>> curl -X GET "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby/metadata?md5=true"

Alternatively, if you just want to know the size or type of a file, use a HEAD request:

>>> curl -i -X HEAD "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby"
HTTP/1.1 200 OK
...
Content-Type: image/png
Content-Length: 455060
Content-Disposition: inline; filename="dtKZNd1J.png"
X-File-Name: dtKZNd1J.png
...
      

Content Disposition

The Filestack file URLs will respect browser settings by default. Most browsers will open files that they can and download the rest. If you want it to download or give the user a 'save as' dialog, you can attach the ?dl=true flag.

The filename will be in X-File-Name. This is the recommended way of getting the filename, as opposed to parsing the Content-Disposition.

>>> curl -X GET "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby?dl=true"

Cache Settings

Using the cache=true query parameter, we'll set the file not to expiry. The cache=false parameter will ask the browser not the cache the file.

>>> curl -I "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby?cache=true"
HTTP/1.1 200 OK
...
Cache-Control: public, max-age=315360000, no-transform
...
>>> curl -I "https://www.filestackapi.com/api/file/DCL5K46FS3OIxb5iuKby?cache=false"
HTTP/1.1 200 OK
...
Cache-Control: no-cache
...