Upload API Docs


The Upload API follows RESTful principles: it uses predictable, resource-oriented URLs, standard HTTP verbs, standard HTTP response codes and JSON for requests and responses.

OpenAPI Specification

We use OpenAPI Specification Version 3 to formally describe the Upload API's endpoints -- the specification file can be found here:

You can use the above specification file together with the Swagger Codegen tool to generate client stubs for your project in one of 30+ different programming languages.

Base URL

The base URL for the Upload API is:



The Authorization HTTP header

You must provide your API key in each HTTP request via HTTP Basic Auth:




The Upload API uses the HTTP Basic Auth scheme.



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



Your password is your API key.

Secret vs Publishable API keys

The Upload API supports two types of API key:

  • Publishable API keys are designed to be publicly visible and can appear in your frontend code. They are limited to a performing a very specific set of actions that are required by Upload.js in order to facilitate file uploads from the browser.

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

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"

You are using an outdated browser.

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