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://files.upload.io/A623uY2RXvnNq1vZ80fYw13",
"fileId": "A623uY2RXvnNq1vZ80fYw13"
}
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
See the full API reference for this endpoint.
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": "A623uY2RXvnNq1vZ80fYw13",
"mime": "image/jpeg",
"size": 43182,
"tags": [
{
"name": "images/profile",
"searchable": true
}
],
"uploadedAt": 1615680311115
},
"uploadParts": {
"first": {
"fileId": "A623uY2RXvnNq1vZ80fYw13",
"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: "A623uY2RXvnNq1vZ80fYw13" |
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: "A623uY2RXvnNq1vZ80fYw13" |
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: "A623uY2RXvnNq1vZ80fYw13" |
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: "A623uY2RXvnNq1vZ80fYw13" |
Delete file batch
Supported API keys: secret_* only.
Deletes multiple files.
-d @- << EOF
{
"files": [
"A623uY2RXvnNq1vZ80fYw13"
]
}
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: ["A623uY2RXvnNq1vZ80fYw13"] |
Get file
Supported API keys: secret_* only.
Gets information about a specific file.
"accountId": "A623uY2",
"fileId": "A623uY2RXvnNq1vZ80fYw13",
"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: "A623uY2RXvnNq1vZ80fYw13" |
Response body
| Parameter | Type | Required | Description |
|---|---|---|---|
accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
fileId | String | Yes | File ID, e.g: "A623uY2RXvnNq1vZ80fYw13" |
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": "A623uY2RXvnNq1vZ80fYw13",
"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: "A623uY2RXvnNq1vZ80fYw13..." |
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: "A623uY2RXvnNq1vZ80fYw13..." |
Response body
| Parameter | Type | Required | Description |
|---|---|---|---|
items[].accountId | String | Yes | Upload Account ID, e.g: "A623uY2" |
items[].fileId | String | Yes | File ID, e.g: "A623uY2RXvnNq1vZ80fYw13" |
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": "A623uY2RXvnNq1vZ80fYw13",
"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: "A623uY2RXvnNq1vZ80fYw13" |
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: "A623uY2RXvnNq1vZ80fYw13" |
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: "A623uY2RXvnNq1vZ80fYw13" |
Response body
| Parameter | Type | Required | Description |
|---|---|---|---|
remainingUploadParts | Integer Array | No | Index of an uploadable file part, e.g: [7] |