Documentation

Upload, store, transform, and deliver product images with the Image Upload API, built on the Filestack File API.

Image Upload API Reference

This API is organized around REST. It has predictable resource-oriented URLs, accepts binary and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Uploads go to www.filestackapi.com and images are delivered from cdn.filestackcontent.com.

Just Getting Started?

Send your first upload with POST /upload, or add a browser upload widget with the Filestack web picker guide.

Authentication

Image Upload API uses API keys to authenticate requests. You can view and manage your API keys in the Filestack developer portal.

Pass the key as the key query parameter on upload and file requests, and as the first path segment of a transformation URL. The API key identifies your application and is safe to use in browser code.

Enabling application security in the developer portal requires a policy and signature on every request. Generate both on your server with the application secret, and keep the secret out of client-side code and public repositories. Overwrite and delete require a policy and signature on every application.

Secured request
# application security enabled
https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY&policy=POLICY&signature=SIGNATURE

Send every request over HTTPS.

Endpoints

POST/uploadUpload a file image

POST https://www.filestackapi.com/api/store/S3

Stores an image from the request body and returns its CDN URL. The handle at the end of the URL is the ID for every later call.

Parameters

ParameterLocation, typeDescription
keyrequiredQuery, stringYour Filestack API key.
bodyrequiredBody, binaryThe image file, sent as the raw request body with its Content-Type.
filenameoptionalQuery, stringName for the stored file.
mimetypeoptionalQuery, stringMIME type of the file, for example image/jpeg.
pathoptionalQuery, stringPath to store the file under in the bucket.
containeroptionalQuery, stringBucket or container to store the file in, when you connect your own storage.
accessoptionalQuery, stringS3 only. Access setting for the stored file: public or private.
base64decodeoptionalQuery, booleanDecode a base64-encoded body before storing it.
policy, signatureoptionalQuery, stringRequired when application security is enabled.

Code samples

POST /upload
curl -X POST \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg \
  "https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY&filename=product.jpg"

Words in capitals, such as YOUR_API_KEY, are placeholders to replace with your own values.

Returns

Response
{
  "url": "https://cdn.filestackcontent.com/zcjsVk1qSKWjIebIhHuc",
  "size": 209870,
  "type": "image/jpeg",
  "filename": "straw-hat.jpg"
}
POST/urlUpload an URL image

POST https://www.filestackapi.com/api/store/S3

Fetches an image from a public URL and stores it. Send the source as a form-encoded url field.

Parameters

ParameterLocation, typeDescription
keyrequiredQuery, stringYour Filestack API key.
urlrequiredBody, stringPublic URL of the image to fetch and store, sent form-encoded.
filenameoptionalQuery, stringName for the stored file.
path, container, accessoptionalQuery, stringSame as POST /upload.
policy, signatureoptionalQuery, stringRequired when application security is enabled.

Code samples

POST /url
curl -X POST \
  -d "url=https://www.example.com/images/product.jpg" \
  "https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY&filename=product.jpg"

Returns

Response
{
  "url": "https://cdn.filestackcontent.com/LIzX21hMTqSmU5PDnhg4",
  "size": 209870,
  "type": "image/jpeg",
  "filename": "hat-from-url.jpg"
}
GET/file/{HANDLE}/metadataRead image metadata

GET https://www.filestackapi.com/api/file/{HANDLE}/metadata

Returns the stored file's properties. Request each field with a boolean query parameter.

Parameters

ParameterLocation, typeDescription
HANDLErequiredPath, stringThe file handle returned by an upload.
width, heightoptionalQuery, booleanReturn the image dimensions in pixels.
mimetype, size, filenameoptionalQuery, booleanReturn the MIME type, size in bytes, and stored filename.

Code samples

Metadata
curl "https://www.filestackapi.com/api/file/zcjsVk1qSKWjIebIhHuc/metadata?width=true&height=true&mimetype=true&size=true&filename=true"

Returns

Response
{
  "filename": "straw-hat.jpg",
  "height": 1118,
  "mimetype": "image/jpeg",
  "size": 209870,
  "width": 721
}
GET/{API_KEY}/{TASKS}/{HANDLE}Resize, crop, and optimize

GET https://cdn.filestackcontent.com/{API_KEY}/{TASKS}/{HANDLE}

Chain tasks in the URL, separated by /, and they run left to right. The CDN caches each variant, and the stored original stays unchanged. Use the URL directly in an <img> tag, or end the chain with store to save the result as a new file.

Tasks

TaskParametersWhat it does
resizewidth, height, fit, alignResize to a width, a height, or both. fit:crop fills the box and crops the overflow; align picks the anchor.
resize=width:480,height:480,fit:crop,align:center
cropdimCut an exact region: x and y of the top-left corner, then width and height.
crop=dim:[40,120,600,600]
rotatedeg, backgroundRotate by degrees. deg:exif applies the orientation stored by the camera.
rotate=deg:exif
outputformat, qualityConvert to jpg, png, webp, or avif at a set quality.
output=format:webp,quality:80
compressnoneRecompress the image to reduce file size.
compress
enhancenoneAutomatic color and lighting correction. Paid plans.
enhance
storelocation, path, containerSave the transformed result as a new file and return its JSON.
store

Code samples

Transformation
# square 480px WebP, saved as a new file
curl "https://cdn.filestackcontent.com/YOUR_API_KEY/rotate=deg:exif/resize=width:480,height:480,fit:crop,align:center/output=format:webp,quality:80/store/zcjsVk1qSKWjIebIhHuc"

Returns

The image bytes, or with store at the end of the chain:

Response
{
  "filename": "straw-hat.webp",
  "handle": "2XF12SikSRO5r9D60ptO",
  "size": 123968,
  "type": "image/webp",
  "url": "https://cdn.filestackcontent.com/2XF12SikSRO5r9D60ptO"
}

The full task list is in the Filestack Processing API reference.

DELETE/file/{HANDLE}Delete a file

DELETE https://www.filestackapi.com/api/file/{HANDLE}

Removes a stored file. Delete always requires a policy with the remove call and its signature, generated on your server with the application secret.

Parameters

ParameterLocation, typeDescription
HANDLErequiredPath, stringThe file handle to delete.
keyrequiredQuery, stringYour Filestack API key.
policy, signaturerequiredQuery, stringA policy that allows remove for this handle, and its HMAC-SHA256 signature.

Code samples

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

Rate Limiting

Each plan includes an allowance of uploads, transformations, bandwidth, and storage. Start on the Free plan and move to a larger plan as your catalog grows.

PlanPriceUploadsTransformationsBandwidthStorage
Free$05001,0001 GB1 GB
Start$69 / mo20,00050,00075 GB50 GB
Grow$199 / mo50,000150,000200 GB150 GB
Scale$379 / mo125,000300,000400 GB350 GB
EnterpriseCustomCustomCustomCustomCustom

Paid plans bill usage past the allowance at the overage rates on Filestack pricing. For volume beyond the Scale plan, contact Filestack about Enterprise.

Error Codes

Image Upload API uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with the request, such as an invalid parameter or a missing policy, and codes in the 5xx range indicate an error on Filestack's servers.

Error bodies are plain text that names the problem. A successful upload always returns JSON with a url field, so check for that field as well as the status code.

StatusExplanation
200 with Invalid ApplicationThe key parameter is missing or does not match an application. The store endpoint answers with a plain-text body.
200 with Invalid response when trying to read fromA POST /url source could not be fetched. Check that the URL is public.
400 Bad RequestA transformation parameter is invalid, for example validation error: invalid value format abc for parameter width required by resize task.
403 ForbiddenThe request needs a policy and signature that allow the action, or it came from a domain outside the application whitelist.
404 Not FoundThe handle does not exist: file not found: HANDLE.
5xx Server ErrorFilestack could not process the request. Contact Filestack support with the request details.

You can always contact Filestack support for more assistance with building your product.