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.

Note: if you want to upload files from the browser (or from an Electron app) we recommend using Upload.js instead, since it performs these requests for you.

Uploading files

To upload a file, use the following POST request:

POST {UPLOAD_API}/v1/files/basic
curl --data-binary @sample-image.jpg \
     -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:

Example Response
  {
    "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.

GET {UPLOAD_API}/v1/files
curl https://api.upload.io/v1/files?accountId=___&pageSize=10 \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json"

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

GET {UPLOAD_CDN}/{fileId}/{transformationSlug}
curl https://files.upload.io/{fileId}/{transformationSlug}

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.

DELETE {UPLOAD_API}/v1/files/{fileId}
curl https://api.upload.io/v1/files/{fileId} \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY

Ready to start uploading files? Get Started

Client SDKs & libraries

Upload.js is Upload's official client-side library for the Upload API — please note its operation is limited to uploads only and must be run in a browser.

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:

Example HTTP Authorization Header
Authorization: Bearer public_FW25aki7semo48qmSkN3dK7rAutJ

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:

ParameterValueDescription

username

"apikey"

Your username is the literal string "apikey" (without quotation marks).

password

<YOUR API KEY>

Your password is your API key.

Example HTTP Authorization Header
Authorization: Basic YXBpa2V5OnB1YmxpY19GVzI1YWtpN3NlbW80OHFtU2tOM2RLN3JBdXRK

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:

{
  "error": {
    "code": "example_error_code",         // Always present
    "message": "Human-readable message.", // Always present
    "details": {                          // Not always present
      "additional": "information",
      "appears": "here"
    }
  }
}

Files

Begin multipart upload

Supported API keys: public_* and secret_*

Begins a new multipart file upload.

POST {UPLOAD_API}/v1/files
curl https://api.upload.io/v1/files \
  -X POST \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "accountId": "A623uY2",
    "fileName": "example.jpg",
    "fileSize": 43182,
    "mime": "image/jpeg",
    "tags": [
      {
        "name": "images/profile",
        "searchable": true
      }
    ]
  }
EOF
Response
  {
    "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

ParameterTypeRequiredDescription

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

ParameterTypeRequiredDescription

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.

PUT {UPLOAD_API}/v1/files/{fileId}/upload_parts/{uploadPartIndex}
curl https://api.upload.io/v1/files/{fileId}/upload_parts/{uploadPartIndex} \
  -X PUT \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "etag": "33a64df551425fcc55e4d42a148795d9f25f89d4"
  }
EOF
Response
<NO RESPONSE BODY>

URL parameters

ParameterTypeRequiredDescription

fileId

String

Yes

File ID, e.g:

"A623uY2RXvnNq1vZ80fYw13"

uploadPartIndex

Integer

Yes

Index of an uploadable file part, e.g:

7

Request body

ParameterTypeRequiredDescription

etag

String

Yes

File ETag, e.g:

"33a64df551425fcc55e4d42a148795d9f25f89d4"

Delete file

Supported API keys: secret_* only.

Deletes a single file.

DELETE {UPLOAD_API}/v1/files/{fileId}
curl https://api.upload.io/v1/files/{fileId} \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY
Response
<NO RESPONSE BODY>

URL parameters

ParameterTypeRequiredDescription

fileId

String

Yes

File ID, e.g:

"A623uY2RXvnNq1vZ80fYw13"

Delete file batch

Supported API keys: secret_* only.

Deletes multiple files.

DELETE {UPLOAD_API}/v1/files
curl https://api.upload.io/v1/files \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "files": [
      "A623uY2RXvnNq1vZ80fYw13"
    ]
  }
EOF
Response
<NO RESPONSE BODY>

URL parameters

The URL for this endpoint takes no parameters.

Request body

ParameterTypeRequiredDescription

files

String Array

No

File ID, e.g:

["A623uY2RXvnNq1vZ80fYw13"]

Get file

Supported API keys: secret_* only.

Gets information about a specific file.

GET {UPLOAD_API}/v1/files/{fileId}
curl https://api.upload.io/v1/files/{fileId} \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json"
Response
  {
    "accountId": "A623uY2",
    "fileId": "A623uY2RXvnNq1vZ80fYw13",
    "mime": "image/jpeg",
    "size": 43182,
    "tags": [
      {
        "name": "images/profile",
        "searchable": true
      }
    ],
    "uploadedAt": 1615680311115
  }

URL parameters

ParameterTypeRequiredDescription

fileId

String

Yes

File ID, e.g:

"A623uY2RXvnNq1vZ80fYw13"

Response body

ParameterTypeRequiredDescription

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.

GET {UPLOAD_API}/v1/files
curl https://api.upload.io/v1/files?accountId=___&pageSize=10 \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json"
Response
  {
    "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

ParameterTypeRequiredDescription

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

ParameterTypeRequiredDescription

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.

GET {UPLOAD_API}/v1/files/{fileId}/upload_parts/{uploadPartIndex}
curl https://api.upload.io/v1/files/{fileId}/upload_parts/{uploadPartIndex} \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "fileId": "A623uY2RXvnNq1vZ80fYw13",
    "range": {
      "inclusiveEnd": 5242879,
      "inclusiveStart": 0
    },
    "uploadPartIndex": 7,
    "uploadUrl": "https://...long-url...x-id=PutObject"
  }

URL parameters

ParameterTypeRequiredDescription

fileId

String

Yes

File ID, e.g:

"A623uY2RXvnNq1vZ80fYw13"

uploadPartIndex

Integer

Yes

Index of an uploadable file part, e.g:

7

Response body

ParameterTypeRequiredDescription

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.

GET {UPLOAD_API}/v1/files/{fileId}/upload_parts
curl https://api.upload.io/v1/files/{fileId}/upload_parts \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "remainingUploadParts": [
      3,
      4,
      6
    ]
  }

URL parameters

ParameterTypeRequiredDescription

fileId

String

Yes

File ID, e.g:

"A623uY2RXvnNq1vZ80fYw13"

Response body

ParameterTypeRequiredDescription

remainingUploadParts

Integer Array

No

Index of an uploadable file part, e.g:

[7]

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: