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 https://api.upload.io/v2/accounts/{accountId}/uploads/binary
curl --data-binary @sample-image.jpg \
     -H "Content-Type: image/jpeg" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     -X POST "https://api.upload.io/v2/accounts/{accountId}/uploads/binary"

The result contains the URL of your uploaded file:

Example Response
  {
    "accountId": "W142hJk",
    "filePath": "/example.jpg",
    "fileUrl": "https://upcdn.io/W142hJk/raw/example.jpg"
  }

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.

Specifying file paths:

The following optional querystring parameters allow you to specify where your file is stored:

  • filePath specifies an absolute file path for this file. (Must start with a /.)
  • fileName specifies a file name for this file. (Ignored if filePath is set.)
  • folderPath specifies a folder path for this file. (Ignored if filePath is set.)

Caching:

Upload uses a temporary cache for raw file downloads, and a perma cache for transformed file downloads.

If you overwrite a file, you will need to "cache bust" to download its latest version. This involves adding an arbitrary version number to your URLs, which you change after overwriting your files.

For example:

https://upcdn.io/abc1234/raw/example.jpg?_v=2022-11-04T14:52:01

Transforming files

GET https://upcdn.io/{accountId}/{transformation}/{filePath}
curl https://upcdn.io/{accountId}/{transformation}/{filePath}

To transform a file:

  1. Create a transformation in the Upload Dashboard.
  2. Use the transformation's slug as the transformation parameter above.
  3. To download the original file, use raw as your transformation.

To "cache bust" after making changes to your transformation:

  • Add a ?_v=<incremental_version_number> to your file URLs, or
  • Add a ?_cache=false to your file URLs.Note: this method is much slower than the previous method, as your file will be re-transformed on every request. As such, we don't generally recommend serving files with ?_cache=false in production. Instead, use an incremental version number.

Deleting files

DELETE /v2/accounts/{accountId}/files
curl https://api.upload.io/v2/accounts/{accountId}/files?filePath={filePath} \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY

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 paths 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_paths table in your application's database.
  2. Whenever your API accepts a file submission from a user, add the file path to this table.
  3. Implement your own "delete unused file" endpoint which first validates the file path 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.

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.

https://api.upload.io/docs/openapi-spec-v3.json

Authentication

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"
    }
  }
}

Multipart file uploads

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, uploadId, 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.

Upload endpoints

Begin multipart upload

Supported API keys: public_* and secret_*

Begins a new multipart file upload.

POST /v2/accounts/{accountId}/uploads
curl https://api.upload.io/v2/accounts/{accountId}/uploads \
  -X POST \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "metadata": {},
    "mime": "image/jpeg",
    "originalFileName": "example.jpg",
    "size": 43182,
    "tags": [
      "images/profile"
    ]
  }
EOF
Response
  {
    "file": {
      "metadata": {},
      "mime": "image/jpeg",
      "tags": [
        "images/profile"
      ],
      "filePath": "/uploads/image.jpg",
      "fileUrl": "https://upcdn.io/AkE9c32/raw/uploads/image.jpg",
      "lastModified": 1615680311115,
      "size": 43182
    },
    "uploadId": "Kd759aLFxttm69kZ",
    "uploadParts": {
      "first": {
        "range": {
          "inclusiveEnd": 5242879,
          "inclusiveStart": 0
        },
        "uploadId": "Kd759aLFxttm69kZ",
        "uploadPartIndex": 7,
        "uploadUrl": "https://...long-url...x-id=PutObject"
      },
      "count": 12
    }
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Request body

ParameterTypeRequiredDescription

size

Integer

Yes

Size in bytes, e.g:

43182

mime

String

No

File MIME type, e.g:

"image/jpeg"

originalFileName

String

No

File name, e.g:

"example.jpg"

tags

String Array

No

File tag, to help organize uploaded files, e.g:

["images/profile"]

Response body

ParameterTypeRequiredDescription

file.filePath

String

Yes

Absolute path to a file. Must begin with a "/", e.g:

"/uploads/image.jpg"

file.fileUrl

String

Yes

URL for an http(s) resource, e.g:

"https://upcdn.io/AkE9c32/raw/uploads/image.jpg"

file.lastModified

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

file.mime

String

Yes

File MIME type, e.g:

"image/jpeg"

file.size

Integer

Yes

Size in bytes, e.g:

43182

file.tags

String Array

No

File tag, to help organize uploaded files, e.g:

["images/profile"]

uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

uploadParts.count

Integer

Yes

Number of parts the file will be uploaded in, e.g:

12

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.uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

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 /v2/accounts/{accountId}/uploads/{uploadId}/parts/{uploadPartIndex}
curl https://api.upload.io/v2/accounts/{accountId}/uploads/{uploadId}/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

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

uploadPartIndex

Integer

Yes

Index of an uploadable file part, e.g:

7

Request body

ParameterTypeRequiredDescription

etag

String

Yes

File ETag, e.g:

"33a64df551425fcc55e4d42a148795d9f25f89d4"

Get upload part

Supported API keys: public_* and secret_*

Gets a remaining upload part for an in-progress upload.

GET /v2/accounts/{accountId}/uploads/{uploadId}/parts/{uploadPartIndex}
curl https://api.upload.io/v2/accounts/{accountId}/uploads/{uploadId}/parts/{uploadPartIndex} \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "range": {
      "inclusiveEnd": 5242879,
      "inclusiveStart": 0
    },
    "uploadId": "Kd759aLFxttm69kZ",
    "uploadPartIndex": 7,
    "uploadUrl": "https://...long-url...x-id=PutObject"
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

uploadPartIndex

Integer

Yes

Index of an uploadable file part, e.g:

7

Response body

ParameterTypeRequiredDescription

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

uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

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 /v2/accounts/{accountId}/uploads/{uploadId}/parts
curl https://api.upload.io/v2/accounts/{accountId}/uploads/{uploadId}/parts \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "remainingUploadParts": [
      3,
      4,
      6
    ]
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

uploadId

String

Yes

ID for a multipart file upload (unique per account), e.g:

"Kd759aLFxttm69kZ"

Response body

ParameterTypeRequiredDescription

remainingUploadParts

Integer Array

No

Index of an uploadable file part, e.g:

[7]

File endpoints

Delete file

Supported API keys: secret_* only.

Synchronously deletes a file.

DELETE /v2/accounts/{accountId}/files
curl https://api.upload.io/v2/accounts/{accountId}/files?filePath={filePath} \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY
Response
<NO RESPONSE BODY>

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

filePath

String

Yes

Absolute path to a file. Must begin with a "/", e.g:

"/uploads/image.jpg"

Delete file batch

Supported API keys: secret_* only.

Asynchronously deletes multiple files.

DELETE /v2/accounts/{accountId}/files/batch
curl https://api.upload.io/v2/accounts/{accountId}/files/batch \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "files": [
      "/uploads/image.jpg"
    ]
  }
EOF
Response
  {
    "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Request body

ParameterTypeRequiredDescription

files

String Array

No

Absolute path to a file. Must begin with a "/", e.g:

["/uploads/image.jpg"]

Response body

ParameterTypeRequiredDescription

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

Get file details

Supported API keys: public_* and secret_*

Gets the full metadata for a file.

GET /v2/accounts/{accountId}/files/details
curl https://api.upload.io/v2/accounts/{accountId}/files/details?filePath={filePath} \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "metadata": {},
    "mime": "image/jpeg",
    "tags": [
      "images/profile"
    ],
    "filePath": "/uploads/image.jpg",
    "fileUrl": "https://upcdn.io/AkE9c32/raw/uploads/image.jpg",
    "lastModified": 1615680311115,
    "size": 43182
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

filePath

String

Yes

Absolute path to a file. Must begin with a "/", e.g:

"/uploads/image.jpg"

Response body

ParameterTypeRequiredDescription

filePath

String

Yes

Absolute path to a file. Must begin with a "/", e.g:

"/uploads/image.jpg"

fileUrl

String

Yes

URL for an http(s) resource, e.g:

"https://upcdn.io/AkE9c32/raw/uploads/image.jpg"

lastModified

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

mime

String

Yes

File MIME type, e.g:

"image/jpeg"

size

Integer

Yes

Size in bytes, e.g:

43182

tags

String Array

No

File tag, to help organize uploaded files, e.g:

["images/profile"]

Folder endpoints

Create folder

Supported API keys: secret_* only.

Creates or updates the folder specified by "folderPath". If the folder's ancestors don't exist, they will be created automatically.

PUT /v2/accounts/{accountId}/folders
curl https://api.upload.io/v2/accounts/{accountId}/folders \
  -X PUT \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "folderPath": "/uploads/absolute/path"
  }
EOF
Response
<NO RESPONSE BODY>

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Request body

ParameterTypeRequiredDescription

folderPath

String

Yes

Absolute path to a folder. Must begin with a "/". Should not end with a "/", e.g:

"/uploads/absolute/path"

allowUnnamedFolders

Boolean

No

You must specify "true" if the "folderPath" ends with a "/". (This prevents the accidental creation of folders that produce file paths with double forward-slashes in them.) Default: false

Delete folder batch

Supported API keys: secret_* only.

Asynchronously deletes multiple folders.

DELETE /v2/accounts/{accountId}/folders/batch
curl https://api.upload.io/v2/accounts/{accountId}/folders/batch \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "folders": [
      {
        "folderPath": "/uploads/absolute/path"
      }
    ]
  }
EOF
Response
  {
    "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Request body

ParameterTypeRequiredDescription

folders[].folderPath

String

Yes

Absolute path to a folder. Must begin with a "/". Should not end with a "/", e.g:

"/uploads/absolute/path"

folders[].retainFolderSettings

Boolean

No

If true, does not delete (virtual folder) settings at the 'folderPath' or its descendants. Default: false

folders[].scope

String

No

"ThisFolder": deletes the folder specified by 'folderPath' if it contains no files and sub-folders. Fails otherwise. "Descendants": deletes the files and folders contained within 'folderPath' and below, but not the folder object itself. "All": deletes the files and folders that are or descend the path specified by 'folderPath'. Default: "ThisFolder"

Response body

ParameterTypeRequiredDescription

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

Delete folder request

Supported API keys: secret_* only.

Asynchronously deletes a folder.

DELETE /v2/accounts/{accountId}/folders
curl https://api.upload.io/v2/accounts/{accountId}/folders \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- << EOF
  {
    "folderPath": "/uploads/absolute/path"
  }
EOF
Response
  {
    "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Request body

ParameterTypeRequiredDescription

folderPath

String

Yes

Absolute path to a folder. Must begin with a "/". Should not end with a "/", e.g:

"/uploads/absolute/path"

retainFolderSettings

Boolean

No

If true, does not delete (virtual folder) settings at the 'folderPath' or its descendants. Default: false

scope

String

No

"ThisFolder": deletes the folder specified by 'folderPath' if it contains no files and sub-folders. Fails otherwise. "Descendants": deletes the files and folders contained within 'folderPath' and below, but not the folder object itself. "All": deletes the files and folders that are or descend the path specified by 'folderPath'. Default: "ThisFolder"

Response body

ParameterTypeRequiredDescription

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

List children

Supported API keys: public_* and secret_*

Lists the children (files and sub-folders) of a folder.

GET /v2/accounts/{accountId}/folders/children
curl https://api.upload.io/v2/accounts/{accountId}/folders/children?path={path} \
  -u apikey:YOUR_PUBLIC_API_KEY \
  -H "Accept: application/json"
Response
  {
    "children": [
      null
    ],
    "cursor": "aGVsbG8=",
    "parent": {
      "folderPath": "/uploads/absolute/path",
      "settings": {
        "publicPermissions": [
          {
            "permissions": {
              "file": {
                "downloadFile": [
                  "thumbnail*"
                ]
              },
              "folder": {}
            }
          }
        ]
      }
    }
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

path

String

Yes

Absolute path to a folder. Must begin with a "/". Should not end with a "/", e.g:

"/uploads/absolute/path"

cursor

String

No

Cursor (aka continuation token) for listing folder children, e.g:

"aGVsbG8="

includeFiles

Boolean

No

includeFolders

Boolean

No

limit

Integer

No

Folder listing limit, e.g:

50

traverseVirtualFolders

Boolean

No

Response body

ParameterTypeRequiredDescription

cursor

String

Yes

Cursor (aka continuation token) for listing folder children, e.g:

"aGVsbG8="

parent.folderPath

String

Yes

Absolute path to a folder. Must begin with a "/". Should not end with a "/", e.g:

"/uploads/absolute/path"

parent.settings.publicPermissions[].permissions.file.downloadFile

String Array

No

Transformation URL slug prefix (so can be zero-length), e.g:

["thumbnail*"]

parent.settings.publicPermissions[].permissions.file.getFileDetails

Boolean

Yes

parent.settings.publicPermissions[].permissions.folder.getFolderDescription

Boolean

Yes

parent.settings.publicPermissions[].permissions.folder.getFolderPublicPermissions

Boolean

Yes

parent.settings.publicPermissions[].permissions.folder.getFolderStorageLayer

Boolean

Yes

parent.settings.publicPermissions[].permissions.folder.listFolderChildren

Boolean

Yes

parent.settings.publicPermissions[].scope

String

Yes

Specifies the level in the tree, relative to the specified path, that these path permissions apply.

parent.status

String

Yes

parent.type

String

Yes

Job endpoints

Cancel job

Supported API keys: secret_* only.

Cancels an in-progress job.

DELETE /v2/accounts/{accountId}/jobs/{jobType}/{jobId}
curl https://api.upload.io/v2/accounts/{accountId}/jobs/{jobType}/{jobId} \
  -X DELETE \
  -u apikey:YOUR_SECRET_API_KEY
Response
<NO RESPONSE BODY>

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

Get job

Supported API keys: secret_* only.

Gets information on a job in any state.

GET /v2/accounts/{accountId}/jobs/{jobType}/{jobId}
curl https://api.upload.io/v2/accounts/{accountId}/jobs/{jobType}/{jobId} \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json"
Response
  {
    "accountId": "A623uY2",
    "created": 1615680311115,
    "error": {
      "message": "Error message.",
      "code": "error_code"
    },
    "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "lastUpdated": 1615680311115,
    "payload": {}
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

Response body

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

attempts

Number

Yes

created

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

error.code

String

Yes

Machine-readable error code, e.g:

"error_code"

error.message

String

Yes

Human-readable error message, e.g:

"Error message."

jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

lastUpdated

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

status

String

Yes

List recent jobs

Supported API keys: secret_* only.

Lists the most recently issued jobs.

GET /v2/accounts/{accountId}/jobs
curl https://api.upload.io/v2/accounts/{accountId}/jobs?jobType1={jobType1} \
  -u apikey:YOUR_SECRET_API_KEY \
  -H "Accept: application/json"
Response
  {
    "items": [
      {
        "accountId": "A623uY2",
        "created": 1615680311115,
        "error": {
          "message": "Error message.",
          "code": "error_code"
        },
        "jobId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "lastUpdated": 1615680311115,
        "payload": {}
      }
    ]
  }

URL parameters

ParameterTypeRequiredDescription

accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

Response body

ParameterTypeRequiredDescription

items[].accountId

String

Yes

Upload account ID, e.g:

"A623uY2"

items[].attempts

Number

Yes

items[].created

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

items[].error.code

String

Yes

Machine-readable error code, e.g:

"error_code"

items[].error.message

String

Yes

Human-readable error message, e.g:

"Error message."

items[].jobId

String

Yes

Job ID, e.g:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

items[].lastUpdated

Integer

Yes

Epoch milliseconds (since midnight 1 January 1970, UTC), e.g:

1615680311115

items[].status

String

Yes

You are using an outdated browser.

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

Chrome

Download

Firefox

Download

Opera

Download

Safari

Download
(macOS only)

Internet Explorer

Download
(Windows only)

Microsoft Edge

Download
(Windows only)