Sirv REST API – Curl examples

On this page

Use the Sirv REST API to perform over 40 common tasks on your Sirv account. Use the example Curl scripts below for a quick start.

Before using the Sirv REST API, create an API client. Your API client will give you a client ID and client Secret, which you can use to connect to Sirv and perform any API operation.

Connect to Sirv with Curl

Firstly, connect to Sirv to get a bearer token (JSON Web Token), which will then allow you to use any REST API method.

The following Curl script will get a token. Replace CLIENT_ID and CLIENT_SECRET from your Sirv account:

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

The JSON response to the POST request will contain the token and expiry.

The response 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"
]
}

Now you have a token, use it to perform any of the Sirv REST API methods. Some example Curl scripts are below.

Upload file

Endpoint: https://api.sirv.com/v2/files/upload
Documentation: https://apidocs.sirv.com/#upload-file

The following script will upload an image to a folder:

curl --request POST 
 --url 'https://api.sirv.com/v2/files/upload?filename=%2Fpath%2Fto%2Fuploaded-image.jpg' 
 --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' 
 --header 'content-type: image/jpeg' 
 --data "@/path/to/local-file.jpg"

This will upload the file to /path/to/uploaded-image.jpg. Characters in the upload file path should be HTML encoded, for example / should be changed to %2F.

Search

Endpoint: https://api.sirv.com/v2/files/search
Documentation: https://apidocs.sirv.com/#search-files

This example script will return a list of all .spin files that exist in the account:

curl --request POST \
 --url https://api.sirv.com/v2/files/search \
 --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
 --header 'content-type: application/json' \
 --data '{
  "query": "basename:*.spin"
}'

This example script will return a list of folders that exist within the /Example-folder folder:

curl --request POST \
  --url https://api.sirv.com/v2/files/search \
  --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
  --header 'content-type: application/json' \
  --data '{
	"query": "isDirectory:true AND dirname.paths:\\/Example-folder"
}'

This example script will return a list of folders that have been created within the last 7 days:

curl --request POST \
  --url https://api.sirv.com/v2/files/search \
  --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
  --header 'content-type: application/json' \
  --data '{
	"query": "isDirectory:true AND dirname.paths:\\/Another-Example-Folder AND ctime:[now-7d TO now]"
}'

This example script will search for multiple files by name and return 5 most recently modified files:

curl --request POST \
 --url https://api.sirv.com/v2/files/search \
 --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
 --header 'content-type: application/json' \
 --data '{
  "query": "basename.raw:(1.jpg OR 2.jpg OR 3.jpg)",
  "sort": {
    "mtime": "desc"
  },
  "from": 0,
  "size": 5
}'

Convert spin to video

Endpoint: https://api.sirv.com/v2/files/spin2video
Documentation: https://apidocs.sirv.com/#convert-spin-to-video

The following example Curl script will convert a spin to an MP4 video, with maximum height or width of 800px, that loops a single row 3 times:

curl --request POST \
 --url https://api.sirv.com/v2/files/spin2video \
 --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
 --header 'content-type: application/json' \
 --data '{
  "filename": "/path/to/spin/Example.spin",
  "options": {
   "width": 800,
   "height": 800,
   "loops": 3,
   "row": "single"
  }
}'

The JSON response will contain the converted video filename:

{
  "filename": "/path/to/spin/Example_single_200x200.mp4"
}

Note how all parts of the file path and name are predictable - the spin is created in a folder of the same name as the video and the file is created using the video file name, number of rows, width and height (separated by underscores).

Convert video to spin

Endpoint: https://api.sirv.com/v2/files/video2spin
Documentation: https://apidocs.sirv.com/#convert-video-to-spin

The following example Curl script will convert a video to a spin.

curl --request POST \
  --url https://api.sirv.com/v2/files/video2spin \
  --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE' \
  --header 'content-type: application/json' \
  --data '{
  "filename": "/path/to/video/Example.mp4"
}'

The JSON response will contain the converted spin filename:

{
  "filename": "/path/to/video/Example/Example.spin"
}

or an error:

{
 "statusCode": 404,
 "error": "Not Found",
 "message": "No such file: /path/to/video/Example.mp4"
}

Check API limit usage

Endpoint: https://api.sirv.com/v2/account/limits
Documentation: https://apidocs.sirv.com/#get-api-limits

The following example Curl script will tell you your API usage limits, current usage, remaining allowance and the time (Unix timestamp) that the limit will refresh:

curl --request GET \
 --url https://api.sirv.com/v2/account/limits \
 --header 'authorization: Bearer RECEIVED_AUTH_TOKEN_HERE'

Example response:

{
 "s3:global": {
  "count": 27,
  "limit": 7000,
  "remaining": 6973,
  "reset": 1451575673
 },
 "s3:PUT": {
  "count": 0,
  "limit": 1500,
  "remaining": 1500,
  "reset": 1451577898
 },
  "s3:GET": {
  "count": 27,
  "limit": 2500,
  "remaining": 2473,
  "reset": 1451575673
 },
 "s3:DELETE": {
  "count": 0,
  "limit": 1000,
  "remaining": 1000,
  "reset": 1451577898
 }
}