S3 API guide

Build fast, scalable imaging into your application. Sirv provides 2 APIs, depending on your needs:

• S3 API - upload files, manage files.
• REST API - upload files, manage files, account management, advanced features.

Use the S3 API to:

• Upload/download files
• Query a folder
• Check if a file exists
• Fetch image meta data (Exif)
• Create folders
• Move/copy/rename/delete files

Choose an SDK

Sirv uses its own S3 compliant infrastructure (not Amazon S3), giving you the benefits of a purpose-built, independent platform, yet usage of all AWS S3 SDKs. Choose an official AWS SDK:

• JavaScript SDK for S3
• PHP SDK for S3
• .NET SDK for S3
• Java SDK for S3
• Node.js SDK for S3
• Ruby SDK for S3
• Python SDK for S3
• Mobile SDK for S3
• Go SDK for S3

Learn more about S3 in the official S3 API documentation.

Connect to your Sirv bucket

Your S3 endpoint is s3.sirv.com. Your S3 Bucket, S3 Key and S3 Secret are on your Settings page.

If you're using the S3cmd command line tool to connect to your Sirv account and upload/download/manage your files, use the following example. Replace the items in CAPITALS with your Sirv S3 connection details:

s3cmd --host=s3.sirv.com --host-bucket=s3.sirv.com --access_key=ENTER_YOUR_SIRV_S3_ACCESS_KEY_HERE --secret_key=ENTER_YOUR_SIRV_S3_SECRET_KEY_HERE ls s3://ENTER_YOUR_SIRV_S3_BUCKET_HERE/

Authenticate your S3 requests using either AWS Signature Version v3 or Signature Version v4.

S3 API limits

The S3 API permits the following frequency of requests.

Business plan limits:

• Total requests per hour: 7000
• Of which PUT requests (uploads): 2000
• Of which GET requests (downloads): 3000
• Of which Delete requests: 3000

Enterprise plan limits:

• Total requests per hour: 14000
• Of which PUT requests (uploads): 4000
• Of which GET requests (downloads): 6000
• Of which Delete requests: 6000

Free plan limits:

• Total requests per hour: 1000
• Of which PUT requests (uploads): 300
• Of which GET requests (downloads): 1000
• Of which Delete requests: 300

If you make an S3 API upload, it will count towards the total limit and the PUT limit. Any other requests (e.g. head or directory listings) only count towards the total limit.

The hour starts counting from the time that the first request is received by Sirv. For example, if a request is received at 15:28:41, the API allowance will be reset at 16:28:41.

If your account exceeds the limit, you'll see a message on the Notifications page of your Sirv account, describing what happened and when the limit will be reset:

In each returned request, the HTTP headers inform you how many API requests have been used, how many are permitted in each hourly window and when the limit will be reset (in UTC epoch seconds):

> curl --head 'https://s3.sirv.com'
HTTP/2.0 429 Too Many Requests
Date: Thu, 01 Nov 2018 15:21:08 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 216
Connection: keep-alive
Access-Control-Allow-Origin: *
X-RateLimit-Limit: 7000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1541100375
ETag: W/"978c-klYL5sybyRPMWDsJgesRXw"
Server: Sirv.S3

If you would like the time in another format, you can use any programming language, such as the JavaScript Date object:

new Date(1541100375 * 1000)
// => Thu Nov 01 2018 16:15:52 GMT

Check your current rate limit status

You can use the Sirv REST API to check the current status of your API usage.

Requests to this endpoint will not count towards your API rate limit. They will always return the status, even if you have reached your limit.