S3 API guide
Build fast, scalable imaging into your application. Sirv provides 2 APIs, depending on your needs:
- REST API - upload files, complete file management, search files, account management, user management, analytics
- S3 API - upload files, partial file management
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.
The S3 API can be used to:
- Upload/download files
- Move/copy/rename/delete files
- Create folders
- Query a folders' contents
You can also use the REST API for all of the operations above, plus many more.
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.
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.
If you are using the S3 API to query the contents of a folder containing more than 1000 files, the response will be truncated after the first 1000 results. To see the next batch of results, use the continuation token called NextMarker. It will only be sent when the response is truncated. The response will also be marked with a boolean flag IsTruncated.
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
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.
Each Sirv response contains a standard response code, to indicate the type of error. Follow best practice and design your scripts to respond appropriately to errors, for the best outcomes. Common errors and resolutions are shown below.
A 429 error means that your S3 API usage has reached its hourly limit. Your hourly limit and current usage is shown on the Usage page of your account. If you hit the limit, pause your uploads until your hourly limit refreshes.
A 429 will also be returned if your client key and secret key fail to pass authentication after 60 attempts. This will block your IP address and the response will look like this:
Forbidden: s3:failed-auth rate limit exceeded: too many requests (60). Retry after 2023-01-26T02:14:57.000Z (UTC).
A 500 error probably means there are too many concurrent upload requests waiting to be processed. These are rare errors and probably indicate that your script sent too many uploads too quickly. Pause your uploads for 2 minutes, then try again, retrying those uploads that failed. Please contact the Sirv support team if you need further advice.
Track your error rates. While some types of 4xx errors may occur occasionally, high error rates indicate problems in your application and it should be optimized.
All Sirv API calls (whether successful or 4xx) return useful headers in their responses, which you should provide if you need help from Sirv support - referring to these headers can help expedite troubleshooting.
Logging your responses will give you a clear understanding of your API usage, how to optimize your application and solve problems.
When building your application, test all the error types above. This is an important best-practice measure, to ensure your application runs smoothly.