Sirv REST API
Sirv provides you with 2 APIs:
- REST API - manage your account, your users, search files, upload, delete and more.
- S3 API - move files, rename files and create folders.
This page explains how to use the Sirv REST API.
To use the Sirv REST API, create an API client from the Settings page of your Sirv account:
Once created, you'll see your Client ID and Client Secret:
The clientId and clientSecret pair represent the API client. The API client can have full access to all operations or be limited to specific API methods.
Each API call must be authenticated with a bearer token (JSON Web Token). You can get a token with a POST request.
Once you have a token, you can use any of the 40+ Sirv REST API methods.
You can continue use the token repeatedly until it expires, in 20 minutes. Once the token expires (see the expiresIn field, in seconds), request a new token.
Documentation for all Sirv REST API methods is at https://apidocs.sirv.com/. It contains a summary of each method, how it can be used and a list of properties that can be set.
Sample scripts for various languages are provided:
The Sirv REST API has a limit to how many requests can be returned per hour.
Enterprise plan limits:
- Total requests per hour: 14000
- Search requests: 2000
- Video to spin conversions: 400
- Spin to video conversions: 400
- Fetch requests: 4000
Business plan limits:
- Total requests per hour: 7000
- Search requests: 1000
- Video to spin conversions: 200
- Spin to video conversions: 200
- Fetch requests: 2000
Free plan limits:
- Total requests per hour: 500
- Search requests: 50
- Video to spin conversions: 20
- Spin to video conversions: 20
- Fetch requests: 300
The total requests per hour is for all types of request combined.
The hour starts counting from the time that the first request is received by Sirv. For example, if a request is received at 18:35:51, the API allowance will be reset at 19:35:51.
Check your current REST API usage on the Usage page of your Sirv account.
If you exceed your limit, you will reeive 429 responses. See the guide below on how to handle 429 and other errors.
- Endpoint: https://api.sirv.com/v2/account/limits
- Documentation: https://apidocs.sirv.com/#get-api-limits
The API method will return:
- Your limit
- Number of requests in last hour
- Number of requests remaining
- Time when limit will reset (UTC epoch seconds)
Note: accessing this endpoint will not count towards your REST API rate limit.
Sirv also provides special API methods, available upon request. Please contact Sirv support if you need access to:
- Create new accounts
- Get user credentials
- Get list of a users' accounts
Proper error handling is essential to building high quality applications and a seamless end-user experience.
Each Sirv response contains a standard response code, to indicate the type of error, with JSON or plaintext bodies.
A 400 error could be caused from a malformed JSON request body or JSON that does not conform to input fields and validation. 400 errors may also be returned to a user without permission to use the REST API.
Responses with error code 400 suggest an issue with the request itself, so they won't be resolved by retrying.
A 401 error occurs when the bearer token is invalid or expired. Tokens expire after 20 minutes.
Retrying a 401 will not succeed. If your application experiences a 401, it should re-authenticate (get a new token).
A 429 error means that your API usage has reached its hourly limit.
Your hourly limit and current usage is shown on the Usage page of your account. You can also retrieve this information via an API limit request (it will work even if your account has reached its hourly limit).
Sirv API limits are generous, so your application is unlikely to hit them. Still, we recommend you follow best-practice and write your scripts to properly handle 429 errors. Optimize the logic of your application (are you using the most efficient approach?) and if you hit limits, pause until your hourly limit refreshes. If you're incurring 429 errors due to a large one-time migration of files, you can request a temporary higher limit.
To avoid hitting your limits, every Sirv REST API response (even 200 "OK" responses) contain the following useful headers:
- X-RateLimit-Limit - the hourly request limit.
- X-RateLimit-Remaining - the number of requests remaining in the current hour.
- X-RateLimit-Reset - a UNIX timestamp (in seconds) for when the limit will be reset.
- X-RateLimit-Type - the type of request this limit relates to e.g. rest:post:files:search.
The header information listed above is also duplicated in the JSON structure. The error message includes a "Retry after" message, in human readable format.
Internal server errors are rare, undefined errors on the Sirv side. Such errors should be brief. If you see 500 errors for an extended period, please check https://status.sirv.com/ or contact the Sirv support team.
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.
If your script receives any 429 responses, resubmit those requests once your hourly limit has refreshed.
Sirv provides the following Swagger OpenAPI Specification JSON file:
It describes the entire API, including:
- Authentication, to get an API access token
- Available endpoint paths and operations on each endpoint (GET and POST)
- Operation parameters and responses for each operation
It is also possible to have limited scope API keys, with any combination of the following capabilities:
- File management - read
- File management - write (upload/create, overwrite, rename, move, copy, delete)
- File management - create (upload/create)
- File management - sub-accounts (access files on sub-accounts)
- Account management - read
- Account management - write
- User management - read
- User management - write
- Billing management - read
- Billing management - write
- Image operations - (background removal, image preprocessing)
- Video operations - (HLS stream management, video to spin conversion)
Ask the support team if you require a limited scope API key.