# File API

## API Endpoint

All requests for the File API should be sent to:

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

## Security

Security may be required for certain API requests, such as [overwrite](https://www.filestack.com/docs/api/file/#overwrite) and [delete](https://www.filestack.com/docs/api/file/#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"
```

## Download

Please use the [Filestack CDN](https://www.filestack.com/docs/delivery/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](https://www.filestack.com/docs/api/file/#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](https://www.filestack.com/docs/delivery/cdn/#cache) |

## Store

Uploads a file directly to any of our supported backends. This will return JSON metadata, including a [Filestack URL for the file](https://www.filestack.com/). 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](https://www.filestack.com/docs/api/file/#security) has been enabled on 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](https://www.filestack.com/docs/api/file/#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](https://www.filestack.com/docs/api/file/#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}/metadata | 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](https://www.filestack.com/docs/api/processing/#image-size) task from our [Processing API](https://www.filestack.com/docs/api/processing/).

#### 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
}
```