Upload API Docs
Quick start
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.
Uploading files
To upload a file, use the following POST request:
-H "Content-Type: image/jpeg" \
-H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
-X POST "https://api.upload.io/v1/files/basic"
The result will contain your uploaded file's URL and file ID:
"fileUrl": "https://upcdn.io/W142hJkKd759aLFxttm69kZ",
"fileId": "W142hJkKd759aLFxttm69kZ"
}
Try it now!
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.
Listing files
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.
Transforming files
Transformations are created in the Upload Dashboard.
Transformations are cached. If you change a transformation's parameters, you must clear the transformation's cache to see those changes applied to previously-transformed files.
To protect you against distributed denial of service (DDOS) attacks, Upload's transformations cannot be parameterized via the URL.
This prevents malicious users from executing an unlimited number of transformations against a file, potentially depleting your monthly CPU quota. Since transformation results are cached and transformation URLs are non-parameterizable, there's a hard limit on how many transformations can be run against your account at any given time.
Deleting files
Deleting files via your frontend code
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
- Create a used_file_ids table in your application's database.
- Whenever your API accepts a file submission from a user, add the file ID to this table.
- 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).
- Call your "delete unused file" endpoint from your frontend code.
Ready to start uploading files? Get Started
Client SDKs & libraries
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.
Authentication
Public vs Secret API keys
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.
The Authorization HTTP header
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.
Option 1: Using Bearer authentication
Bearer authentication works by prefixing the string "Bearer " to your API key:
Option 2: Using Basic authentication
Basic authentication works by combining the username and password with a : character, and then base-64 encoding the string. Your username and password are:
Parameter | Value | Description |
---|---|---|
username | "apikey" | Your username is the literal string "apikey" (without quotation marks). |
password | <YOUR API KEY> | Your password is your API key. |
Error handling
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.
The error payload
In addition to the HTTP status code, you will also receive the following error payload:
Files
Begin multipart upload
Supported API keys: public_* and secret_*
Begins a new multipart file upload.
-d @- << EOF
{
"accountId": "A623uY2",
"fileName": "example.jpg",
"fileSize": 43182,
"mime": "image/jpeg",
"tags": [
{
"name": "images/profile",
"searchable": true
}
]
}
EOF
"file": {
"accountId": "A623uY2",
"fileId": "W142hJkKd759aLFxttm69kZ",
"mime": "image/jpeg",
"size": 43182,
"tags": [
{
"name": "images/profile",
"searchable": true
}
],
"uploadedAt": 1615680311115
},
"uploadParts": {
"first": {
"fileId": "W142hJkKd759aLFxttm69kZ",
"range": {
"inclusiveEnd": 5242879,
"inclusiveStart": 0
},
"uploadPartIndex": 7,
"uploadUrl": "https://...long-url...x-id=PutObject"
},
"count": 12
}
}
URL parameters
The URL for this endpoint takes no parameters.
Request body
Parameter | Type | Required | Description |
---|---|---|---|
accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
fileSize | Integer | Yes | Size in bytes, e.g: 43182 |
tags[].name | String | Yes | File tag, to help organize uploaded files, e.g: "images/profile" |
tags[].searchable | Boolean | Yes | Specifies whether the tag is searchable from the Upload Dashboard. File are allowed up to 10 searchable tags, e.g: true |
fileName | String | No | File name, e.g: "example.jpg" |
mime | String | No | File MIME type, e.g: "image/jpeg" |
Response body
Parameter | Type | Required | Description |
---|---|---|---|
file.accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
file.fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
file.mime | String | Yes | File MIME type, e.g: "image/jpeg" |
file.size | Integer | Yes | Size in bytes, e.g: 43182 |
file.tags[].name | String | Yes | File tag, to help organize uploaded files, e.g: "images/profile" |
file.tags[].searchable | Boolean | Yes | Specifies whether the tag is searchable from the Upload Dashboard. File are allowed up to 10 searchable tags, e.g: true |
file.uploadedAt | Integer | Yes | Epoch milliseconds (since midnight 1 January 1970, UTC), e.g: 1615680311115 |
uploadParts.count | Integer | Yes | Number of parts the file will be uploaded in, e.g: 12 |
uploadParts.first.fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
uploadParts.first.range.inclusiveEnd | Integer | Yes | Position in the file the last byte of this part corresponds to. Value is -1 when the part is empty (i.e. for uploading empty files), e.g: 5242879 |
uploadParts.first.range.inclusiveStart | Integer | Yes | Position in the file the first byte of this part corresponds to, e.g: 0 |
uploadParts.first.uploadPartIndex | Integer | Yes | Index of an uploadable file part, e.g: 7 |
uploadParts.first.uploadUrl | String | Yes | Pre-signed upload URL for this part, e.g: "https://...long-url...x-id=PutObject" |
Complete upload part
Supported API keys: public_* and secret_*
Finalizes an upload part for an in-progress multipart upload.
-d @- << EOF
{
"etag": "33a64df551425fcc55e4d42a148795d9f25f89d4"
}
EOF
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
uploadPartIndex | Integer | Yes | Index of an uploadable file part, e.g: 7 |
Request body
Parameter | Type | Required | Description |
---|---|---|---|
etag | String | Yes | File ETag, e.g: "33a64df551425fcc55e4d42a148795d9f25f89d4" |
Delete file
Supported API keys: secret_* only.
Deletes a single file.
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
Delete file batch
Supported API keys: secret_* only.
Deletes multiple files.
-d @- << EOF
{
"files": [
"W142hJkKd759aLFxttm69kZ"
]
}
EOF
URL parameters
The URL for this endpoint takes no parameters.
Request body
Parameter | Type | Required | Description |
---|---|---|---|
files | String Array | No | File ID, e.g: ["W142hJkKd759aLFxttm69kZ"] |
Get file
Supported API keys: secret_* only.
Gets information about a specific file.
"accountId": "A623uY2",
"fileId": "W142hJkKd759aLFxttm69kZ",
"mime": "image/jpeg",
"size": 43182,
"tags": [
{
"name": "images/profile",
"searchable": true
}
],
"uploadedAt": 1615680311115
}
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
Response body
Parameter | Type | Required | Description |
---|---|---|---|
accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
mime | String | Yes | File MIME type, e.g: "image/jpeg" |
size | Integer | Yes | Size in bytes, e.g: 43182 |
tags[].name | String | Yes | File tag, to help organize uploaded files, e.g: "images/profile" |
tags[].searchable | Boolean | Yes | Specifies whether the tag is searchable from the Upload Dashboard. File are allowed up to 10 searchable tags, e.g: true |
uploadedAt | Integer | Yes | Epoch milliseconds (since midnight 1 January 1970, UTC), e.g: 1615680311115 |
Get files
Supported API keys: secret_* only.
Lists the files for a given account.
"continuation": {
"backwardToken": "<BACKWARD_TOKEN_OR_NULL>",
"forwardToken": "<FORWARD_TOKEN_OR_NULL>"
},
"items": [
{
"accountId": "A623uY2",
"fileId": "W142hJkKd759aLFxttm69kZ",
"mime": "image/jpeg",
"size": 43182,
"tags": [
{
"name": "images/profile",
"searchable": true
}
],
"uploadedAt": 1615680311115
}
]
}
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
pageSize | Integer | Yes | Page size (i.e. maximum items to return in a page of results), e.g: 12 |
backwardToken | String | No | Continuation token (aka pagination cursor), e.g: "W142hJkKd759aLFxttm69kZ..." |
fileTag | String | No | File tag, to help organize uploaded files, e.g: "images/profile" |
fileTagPrefixSearch | Boolean | No | If true performs a prefix search using the fileTag, else performs an exact-match search, e.g: true |
forwardToken | String | No | Continuation token (aka pagination cursor), e.g: "W142hJkKd759aLFxttm69kZ..." |
Response body
Parameter | Type | Required | Description |
---|---|---|---|
items[].accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
items[].fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
items[].mime | String | Yes | File MIME type, e.g: "image/jpeg" |
items[].size | Integer | Yes | Size in bytes, e.g: 43182 |
items[].tags[].name | String | Yes | File tag, to help organize uploaded files, e.g: "images/profile" |
items[].tags[].searchable | Boolean | Yes | Specifies whether the tag is searchable from the Upload Dashboard. File are allowed up to 10 searchable tags, e.g: true |
items[].uploadedAt | Integer | Yes | Epoch milliseconds (since midnight 1 January 1970, UTC), e.g: 1615680311115 |
Get upload part
Supported API keys: public_* and secret_*
Gets a remaining upload part for an in-progress upload.
"fileId": "W142hJkKd759aLFxttm69kZ",
"range": {
"inclusiveEnd": 5242879,
"inclusiveStart": 0
},
"uploadPartIndex": 7,
"uploadUrl": "https://...long-url...x-id=PutObject"
}
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
uploadPartIndex | Integer | Yes | Index of an uploadable file part, e.g: 7 |
Response body
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
range.inclusiveEnd | Integer | Yes | Position in the file the last byte of this part corresponds to. Value is -1 when the part is empty (i.e. for uploading empty files), e.g: 5242879 |
range.inclusiveStart | Integer | Yes | Position in the file the first byte of this part corresponds to, e.g: 0 |
uploadPartIndex | Integer | Yes | Index of an uploadable file part, e.g: 7 |
uploadUrl | String | Yes | Pre-signed upload URL for this part, e.g: "https://...long-url...x-id=PutObject" |
Get upload parts
Supported API keys: public_* and secret_*
Lists the remaining upload parts for an in-progress upload. An empty array is returned when the upload is complete.
"remainingUploadParts": [
3,
4,
6
]
}
URL parameters
Parameter | Type | Required | Description |
---|---|---|---|
fileId | String | Yes | File ID, e.g: "W142hJkKd759aLFxttm69kZ" |
Response body
Parameter | Type | Required | Description |
---|---|---|---|
remainingUploadParts | Integer Array | No | Index of an uploadable file part, e.g: [7] |