File API

Reference for the Filestack File API, built on REST principles.

API Endpoint

All requests for the File API should be sent to:

https://www.filestackapi.com/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=https://d3urzlae3olibs.cloudfront.net/watermark.png" "https://www.filestackapi.com/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://d3urzlae3olibs.cloudfront.net/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://www.filestackapi.com/api/file/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"

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)

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
}