Getting started

The first time you use the Sirv REST API, create an API client, then connect to Sirv. Once connected, you can use over 30 API methods.

API client

To use the Sirv REST API, create an API client from the Settings page of your Sirv account:

Create client in Sirv REST API

Once created, you'll see your Client ID and Client Secret:

List of Sirv REST API clients

The clientId and clientSecret pair represent the API client. The API client can can have full access to all operations or be limited to specific API methods.

Connect to Sirv

Each API call must be authenticated with a bearer token (JSON Web Token). You can get a token with a POST request. Here's an example in curl:

{
  curl --request POST \
    --url https://api.sirv.com/v2/token \
    --header 'content-type: application/json' \
    --data '{
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET"
}'

If you would like an example in another language, please send your requirements from your Sirv account contact form. The JSON response to the POST request will look like this:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6IkNMSVlYRjVqMERQV053cWpzdHJWbkNPVFRNbCIsImNsaWVudE5hbWUiOiJUZXN0IGNsaWVudCIsInNjb3BlIjpbImFjY291bnQ6cmVhZCIsImFjY291bnQ6d3JpdGUiLCJ1c2VyOnJlYWQiLCJ1c2VyOndyaXRlIiwiYmlsbGluZzpyZWFkIiwiYmlsbGluZzp3cml0ZSIsImZpbGVzOnJlYWQiLCJmaWxlczp3cml0ZSIsInZpZGVvcyIsImltYWdlcyJdLCJpYXQiOjE1MjIwODExMTYsImV4cCI6MTUyMjA4MjMxNiwiYXVkIjoiNDlnaGEyN2ZraHQzdGtyaml0aWJoNGJrazQxemdqdTgifQ.GkhToMKvy8hB68SNpqpPcxhsMczyyTtlROMvsqiPJ4Y",
  "expiresIn": 1200,
  "scope": [
    "account:read",
    "account:write",
    "user:read",
    "user:write",
    "billing:read",
    "billing:write",
    "files:read",
    "files:write",
    "videos",
    "images"
    ]
}

Use the token with the Sirv REST API methods listed below. When the token expires (see the expiresIn field, in seconds), you should request a new token.

For example, this curl script shows how to use the API method to convert a video to spin:

curl --request POST \
  --url https://api.sirv.com/v2/files/video2spin \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6IkNMSVlYRjVqMERQV053cWpzdHJWbkNPVFRNbCIsImNsaWVudE5hbWUiOiJUZXN0IGNsaWVudCIsInNjb3BlIjpbImFjY291bnQ6cmVhZCIsImFjY291bnQ6d3JpdGUiLCJ1c2VyOnJlYWQiLCJ1c2VyOndyaXRlIiwiYmlsbGluZzpyZWFkIiwiYmlsbGluZzp3cml0ZSIsImZpbGVzOnJlYWQiLCJmaWxlczp3cml0ZSIsInZpZGVvcyIsImltYWdlcyJdLCJpYXQiOjE1MjIwODExMTYsImV4cCI6MTUyMjA4MjMxNiwiYXVkIjoiNDlnaGEyN2ZraHQzdGtyaml0aWJoNGJrazQxemdqdTgifQ.GkhToMKvy8hB68SNpqpPcxhsMczyyTtlROMvsqiPJ4Y' \
  --header 'content-type: application/json' \
  --data '{
	"filename": "/My-Video.mp4"
}'

The response JSON will either contain the filename of the converted spin:

{
	"filename": "/A-Folder/My-Video.spin"
}

or an error:

{
	"statusCode": 404,
	"error": "Not Found",
	"message": "No such file: /My-Video.mp4"
}

The following example uses JavaScript to obtain a bearer token (JSON Web Token):

var request = require('request');
 
var headers = {
    'content-type': 'application/json'
};
 
var dataString = '{ "clientId": "CLIENT_ID", "clientSecret": "CLIENT_SECRET"}';
 
var options = {
    url: 'https://api.sirv.com/v2/token',
    method: 'POST',
    headers: headers,
    body: dataString
};
 
request(options, (error, response, body) => {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
});

API methods

GET Get account info /v2/account POST Update account info /v2/account POST List or search account events /v2/account/events/search experimental POST Remote fetching /v2/account/fetching GET Get API limits /v2/account/limits GET Get storage info /v2/account/storage GET Get users /v2/account/users GET Get billing info /v2/billing/plan POST Download file /v2/files/fetch POST Get JWT protected URL /v2/files/jwt experimental GET Get approval flag /v2/files/meta/approval POST Set approval flag /v2/files/meta/approval GET Get meta description /v2/files/meta/description POST Set meta description /v2/files/meta/description GET Get product meta /v2/files/meta/product POST Set product meta /v2/files/meta/product GET Get file meta tags /v2/files/meta/tags POST Add file meta tags /v2/files/meta/tags DELETE Delete file meta tags /v2/files/meta/tags GET Get meta title /v2/files/meta/title POST Set meta title /v2/files/meta/title GET Get folder options /v2/files/options POST Set folder options /v2/files/options GET Read folder contents /v2/files/readdir experimental POST Search files /v2/files/search POST Convert spin to video /v2/files/spin2video GET Get file info /v2/files/stat POST Upload file /v2/files/upload experimental POST Convert video to spin /v2/files/video2spin GET Get transfer stats /v2/stats/http GET Get storage stats /v2/stats/storage POST Get API access token /v2/token GET Get user info /v2/user

Looking for file management?

The S3 API let's you upload / download / query / delete / modify / move files.

S3 API documentation

Need Help?