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:

We've previously shown you how to perform a basic file upload (recommended).

Upload also supports multipart file uploads. These are more complex, but benefit you with a higher file upload rate (1000 req/sec by default), larger files (up to 5TB for enterprise customers), and parallel uploads. Uploader and Upload.js use multipart file uploads by default.

To implement multipart file uploads manually (advanced):

1. Calculate the file's size.
2. Call begin multipart upload, passing the file's name, size, and type.
3. Open the file for reading.
4. Read the correct section of the file. (This is the section specified by the inclusiveStart andinclusiveEnd fields from the HTTP response from step 2 or step 10.)
5. Make an HTTP PUT request, using the data from step 4 as the request body, and the uploadUrl from the HTTP response from step 2 (or step 10) as the URL.
6. If uploadParts.count = 1 from step 2, then add the following HTTP request headers, changing "image/jpeg" and "foo.jpg" as necessary. (If uploadParts.count > 1, add no additional request headers.):
   
   Content-Type: image/jpeg
   
   Content-Disposition: inline; filename="foo.jpg"; filename*=UTF-8''foo.jpg
7. Read the etag HTTP response header from step 5.
8. Call complete upload part, passing the etag, fileId, and uploadPartIndex.
9. If uploadPartIndex = uploadParts.count - 1, then exit (the upload is complete), else continue:
10. Call get upload part, passing an incremented uploadPartIndex.
11. Repeat from step 4, using the new uploadPartIndex, uploadUrl, inclusiveStart, and inclusiveEnd returned by step 10.