Upload API Docs

The Upload API provides out-the-box file uploading & processing functionality for your app. Every endpoint follows RESTful design principles, benefiting you with predictable, resource-oriented URLs and standard HTTP verbs and response codes.

To upload a file, use the following POST request:

The result will contain your uploaded file's URL and file ID:

Explanation:

• The request body is the file you want to upload.
• The Content-Type: <YOUR_MIME_TYPE> header tells Upload what type of file this is.
• The Authorization: Bearer <YOUR_PUBLIC_API_KEY> header contains your API key.

You may optionally provide these request headers:

• X-Upload-Tags: tags help to organize your files as they can be prefix-searched using the list files endpoint. The header value is a JSON array following the same structure as the tags field from the begin file upload endpoint. The array must not be wrapped in quotes.
• X-Upload-File-Name: a name to associate with the file.

See the full API reference for this endpoint.

You may optionally provide these additional querystring parameters:

• fileTag=X: returns only those files marked with the specified tag.
• fileTagPrefixSearch=true: performs a prefix search using fileTag, returning results in descending order of each file's tag and then time. If false the request will perform an exact-match search on fileTag and the results will be in descending order of time.

Pagination is performed by adding one of the following querystring parameters:

• forwardToken=X: where X is taken from the prior result's continuation.forwardToken field. Note: if continuation.forwardToken was absent in the previous response, there are no more pages after that page.
• backwardToken=X: where X is taken from the prior result's continuation.backwardToken field. Note: if continuation.backwardToken was absent in the previous response, there are no more pages before that page.

Frontend code must use public API keys when calling API endpoints. This introduces a challenge when deleting files because the "delete file" endpoint requires a secret API key.

Try the following solutions instead:

Solution 1: Suitable for small files (e.g. images)

• For small files, frontend developers often find it simpler to treat Upload as an append-only datastore. This means using your application's database to keep track of which file IDs are meaningful, and ignoring everything else that's uploaded to your Upload account.
• When using this approach, consider configuring a "max file size" rule and a "rate limit" rule in the Upload Dashboard to keep your storage usage down.

Solution 2: Suitable for all files

1. Create a used_file_ids table in your application's database.
2. Whenever your API accepts a file submission from a user, add the file ID to this table.
3. Implement your own "delete unused file" endpoint which first validates the file ID is not in this table, and secondly deletes the file via the Upload API (using a secret API key).
4. Call your "delete unused file" endpoint from your frontend code.

To generate client SDKs & libraries for any language or to integrate with Upload API endpoints not included in Upload.js, please use the OpenAPI Specification file below — in conjunction with the Swagger Codegen tool — to generate code in your desired language.

All Upload API keys are prefixed with one of the following:

• public_*: these keys are designed to be publicly visible and can appear in your frontend code. They are limited to performing file upload operations only, and cannot be used to retrieve, modify or delete data.

• secret_*: these must be kept secret. Secret API keys allow you to access any endpoint in the Upload API, and are intended to be used by backend services only.

You must provide the Authorization HTTP header in every request to the Upload API. The value for this header can follow either HTTP Bearer Auth or HTTP Basic Auth, depending on your preference.

The Upload API returns 4** HTTP status codes to indicate problems with client requests, and 5** HTTP status codes to indicate problems with the Upload service itself.

In addition to the HTTP status code, you will also receive the following error payload: