Upload files with the API

The upload API lets you upload files to your Sirv account.

Upload options

Files should be uploaded one at a time to the endpoint https://api.sirv.com/v2/files/upload.

Your request should send the path to the local file and specify the path where the file should be saved in your Sirv account. If the folder path does not already exist, the folder(s) will be created on Sirv.

You can save the file with any filename - it does not need to match the original.

Your request must specify the appropriate content type and use binary content encoding (not base64).

Required parameters are:

• filename - file name and its path to be saved on Sirv.
• content-type - content-type of the original image e.g. image/png. See list of common content types.

File size limit

The file size limit for API uploads is 300 MB. If you need to upload larger files, please contact the Sirv team to describe your requirements.

Hourly file upload limit

Your account can upload a large number of files per hour. There is a limit as follows:

• Enterprise plan - 4,000 uploads per hour
• Business plan - 2,000 uploads per hour
• Trial plan - 2,000 uploads per hour
• Free plan - 300 uploads per hour

If you reach your hourly limit, pause uploads until the limit refreshes.

How to handle upload errors

For each upload request, Sirv will return a response. A successful upload will return a 200 response. If you receive any other response, your script should retry or take some other action.

We recommend logging each response that Sirv returns - this will give you a history of uploads, to help you troubleshoot any issue.

These are the possible error responses that your script should handle:

• 401 - The Unauthorized error could be returned if your API access token has reached its 20 minute expiry. If so, get a new token and try again.
• 403 - The Forbidden error means that you are not permitted to upload a file to the path, for example because a file with the same name already exists at the destination, in a protected folder. Consider saving the file with another name or path.
• 429 - The Too Many Requests error will be returned if you have reached your hourly file upload limit. Your limit and current status is shown on the Usage page of your Sirv account. To handle such an error, pause your upload script and resume your uploads once your hourly limit has refreshed.
• 503 - The Service Unavailable error will be returned if Sirv's upload service is overloaded. If files cannot be uploaded immediately, they join a queue. If the queue becomes too long, new requests won't be added to the queue and a 503 response will be returned. This is a rare occurence that will resolve itself after some time. To handle such an error, we recommend retrying after 15 to 30 minutes.

Protect your API key

If you use the upload API to let third parties upload files to your Sirv account, consider how to protect your API credentials. You should keep your client ID and client secret private, without exposing them in your code.

There are 2 ways to allow uploads without exposing your key:

• You could configure your page so that the user uploads files to your backend first. Then your backend can upload the file to your Sirv account.
• Alternatively, you can use the API key on your backend to issue JWT tokens for your web app. This way only the 20 minutes JWT token will be exposed.

Example scripts

The REST API upload documentation contains an example payload, JSON schema, response and scripts for 10 popular programming languages:

• cURL upload example | more cURL examples
• Python upload example | more Python examples
• Node.js upload example | more Node.js examples
• JavaScript upload example
• Java upload example | more Java examples
• PHP upload example | more PHP examples
• Ruby upload example
• Swift upload example
• Go upload example
• C# upload example
• jQuery example

Example response

You'll receive an empty body in response to your upload request. The response will include some useful headers, such as your hourly upload limit, the number of requests remaining and the time when the limit will reset (in 10-digit epoch time):

< HTTP/1.1 200
< date: Fri, 03 Jun 2022 15:21:07 GMT
< content-length: 0
< connection: close
< x-ratelimit-limit: 2000
< x-ratelimit-remaining: 1999
< x-ratelimit-reset: 1654273267
< x-ratelimit-type: rest:post:files:upload
< access-control-allow-origin: *
< access-control-expose-headers: *
< cache-control: no-cache
< server: Sirv.API
< strict-transport-security: max-age=31536000

Get expert help

If you'd like advice using the file upload API, please contact the Sirv customer success team.