S3 API guide
Tip: We recommend using the REST API instead of the S3 API. The REST API has many more capabilities than the S3 API and developers find that it is faster and easier to work with.
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:
- 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.
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
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.