File API

API Endpoint

All requests for the File API should be sent to:

https://www.filestackapi.com/api/file

Related: Tutorial On Performing A Workflow API

Security

Security may be required for certain API requests, such as overwrite and delete, or if security has been enabled for the application. For the File API, security credentials should be provided in the form of query parameters or using HTTP basic auth:

Query Parameters

?policy=POLICY&signature=SIGNATURE

Basic Authentication

  • User: “app”
  • Password: APP_SECRET_KEY

Example for file overwrite:

curl -X POST \
    -u "app:SECRET_KEY" \
    -d "url=SOME_URL" "https://www.filestackapi/api/file/hGdfDXDSSNyVhVa0UeiB"

Please refer to our section on security for more information on generated policies and signatures.

Download

Please use the Filestack CDN to download and/or serve files. Using the API is inefficient and incurs higher bandwidth costs.

Retrieves file via a Filestack handle. Requires policy and signature only when security has been enabled on account.

METHOD URI RETURNS
GET /file/{HANDLE} File

Query Params

NAME TYPE DESCRIPTION
dl boolean When running GET requests on Filestack URLs inside a browser, the browser may choose to open the file itself or download it, depending on its default settings. You may pass in the "dl" query parameter to force the browser to download the file.
cache boolean See cache

Store

Uploads a file directly to any of our supported backends. This will return JSON metadata, including a Filestack URL for the file. You must provide your APIKEY as a query parameter and a file as multipart form data. Alternatively, you may provide a public URL as a file through the “url” parameter in body of the request.

Requires policy and signature only when security has been enabled on account.

Please refer to our documentation on storage providers to find out more on configuring custom cloud storage for your account.

METHOD URI RETURNS
POST /store/{PROVIDER}/{HANDLE}?key={APIKEY} JSON

Provider

Where to store the file. The default is S3. Other options include ‘azure’,‘dropbox’, ‘rackspace’ and ‘gcs’. You must have the chosen provider configured in the developer portal to enable this feature.

Query Params

NAME TYPE DESCRIPTION
key string Filestack API key
filename string Name for the stored file
mimetype string i.e. text/plain (default) or image/jpeg
path string The path to store the file within the specified bucket. By default, Filestack stores the file at the root with a unique identifier, followed by an underscore, followed by the filename. For example: "3AB239102DB_myphoto.png".
container string The bucket or container in which to store the file. If this parameter is omitted, the file is stored in the default container specified in your developer portal settings. Note: this parameter does not apply when storing to Dropbox
access string S3 Only. Configures access for the file on the given container. Can be set to "public" or "private" (default).
base64decode boolean Specifies that you want the data to be first decoded from base64 before being written to the file. For example, if you have base64 encoded image data, you can use this flag to first decode the data before writing the image file.

Request

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

Response

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

Overwrite

Overwrites a handle with a new file supplied as the body of the request. This action requires security.

METHOD URI RETURNS
POST /file/{HANDLE} JSON

Query Params

NAME TYPE DESCRIPTION
base64decode boolean Specifies that you want the data to be first decoded from base64 before being written to the file. For example, if you have base64 encoded image data, you can use this flag to first decode the data before writing the image file.

Request

curl -X POST \
    --data-binary @filename.txt \
    --header "Content-Type:text/plain" \
    "https://www.filestackapi.com/api/file/Bc2FQwXReueTsaeXB6rO?policy={POLICY}&signature={SIGNATURE}"

Response

{
    "url": "https://cdn.filestackcontent.com/Bc2FQwXReueTsaeXB6rO",
    "mimetype": "plain/text",
    "isWriteable": true,
    "size": 19,
    "filename": "filename.txt"
}

Delete

Deletes a file via its handle. This request requires security.

METHOD URI RETURNS
DELETE /file/{HANDLE} JSON

Query Params

NAME TYPE DESCRIPTION
skip_storage boolean When true, the file will be removed from Filestack but will remain in its storage container.

Request

curl -X DELETE \
"https://www.filestackapi.com/api/file/{HANDLE}?key={APIKEY}&policy={POLICY}&signature={SIGNATURE}"

Metadata

Get a JSON payload of your uploaded file metadata. This metadata is generated on the fly and is not stored in the Filestack database. Requires policy and signature when using exif=true.

METHOD URI RETURNS
GET /file/{HANDLE} JSON

Query Params

Query parameters to the metadata endpoint determine which fields will be returned in the JSON response.

NAME TYPE DESCRIPTION
size boolean Get file size in bytes
mimetype boolean Get mimetype of file
filename boolean Get filename of file
uploaded boolean Timestamp when file was uploaded
writeable boolean Is the file writeable
cloud boolean Get info if file was stored through Cloud API
source_url boolean Get info if file was stored from a URL
exif boolean Get EXIF info (requires security)
upload_status boolean Get info about the status of upload

If your file is an image and you would like to know its width and height you can use imagesize task from our Processing API.

Hashing

Return a hash of the file.

NAME TYPE DESCRIPTION
md5 boolean MD5 hash as string
sha1 boolean SHA-1 hash as string
sha224 boolean SHA-224 hash as string
sha256 boolean SHA-256 hash as string
sha384 boolean SHA-384 hash as string
sha512 boolean SHA-512 hash as string

Storage

Get storage information.

NAME TYPE DESCRIPTION
location boolean Get storage location
path boolean Get storage path
container boolean Get storage container

Request

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

Response

{
    "mimetype": "image/png",
    "uploaded": 1431950945811.783,
    "container": "fp-documentation-assets",
    "writeable": true,
    "filename": "dtKZNd1J.png",
    "location": "S3",
    "key": "kWg7nloGTWmHFi5nlbF9_dtKZNd1J.png",
    "path": "kWg7nloGTWmHFi5nlbF9_dtKZNd1J.png",
    "size": 270
}