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

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.

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
}'

To return more than 1000 results, submit a scrolling search.

In your search request, set scroll to true and size to 100, to receive 100 results at a time:

curl --request POST \
  --url https://api.sirv.com/v2/files/search \
  --header 'authorization: Bearer BEARER_TOKEN_HERE' \
  --header 'content-type: application/json' \
 --data '{
  "query":"extension:.jpg AND dirname:\/products",
  "sort":{"filename.raw":"asc"},
  "scroll":"true",
  "size":100
  }'

The response will contain a count of the total results and a scrollId e.g.

...results here, ending with the following:
        }
    ],
    "total": 2812,
    "_relation": "eq",
    "scrollId": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFmFhQ0xUVmc2UmotVXBlM1pCSDJYc3cAAAAAGlSdQBYyVmlyUmdiTVF3MjNZNkRIemptTTBn"
}

Use that scrollId to submit a scrolling search:

curl --request POST \
  --url https://api.sirv.com/v2/files/search/scroll \
  --header 'authorization: Bearer BEARER_TOKEN_HERE' \
  --header 'content-type: application/json' \
  --data '{
  "scrollId":"SCROLLID_HERE"
  }'

The scrolling search will return the first 100 results. Submit that same request again to get the next 100 results. Keep submitting it until all results have been received.

Below is a complete bash script to run on Linux or macOS. It will connect to Sirv, get a bearer token, submit a scrolling search, retrieve batches of 100 results and save the entire list of filenames in a text file. It requires the jq utility. Replace the CLIENT_ID and CLIENT_SECRET with your API credentials and the query with your desired parameters.

#!/bin/bash

# ================================================
# Configuration
# ================================================
CLIENT_ID="Gs6GDq4xydfFtSl8SCutjW8w5UV"
CLIENT_SECRET="0Gx42l3c94E4FuwJjC0iZtLZfkk70QDt/XDfGRKkMRns5BPe7jPv4ogn4m1Ye56ejLR2X8f7WAfRm6sKDXRJaQ=="

API_BASE="https://api.sirv.com/v2"

# Define timestamp format for filename: MM:HH-DDMMYY (Minute:Hour)
TIMESTAMP=$(date +"%M:%H-%d%m%y")
OUTPUT_FILE_NAME="Sirv-API-search-results-${TIMESTAMP}.txt"
OUTPUT_FILE_PATH=~/"$OUTPUT_FILE_NAME"

# Ensure jq is installed
if ! command -v jq &> /dev/null; then
    echo "Error: jq is not installed. Please install jq to run this script."
    exit 1
fi

# Create or clear the output file
> "$OUTPUT_FILE_PATH"

echo "--- Starting Sirv API Scrolling Search ---"
echo "Output file: $OUTPUT_FILE_PATH"

# ================================================
# Step 1: Obtain Bearer Token
# ================================================
echo -n "Attempting to retrieve Bearer Token... "

TOKEN_RESPONSE=$(curl -s -X POST "${API_BASE}/token" 
     -H "Content-Type: application/json" 
     -d "{"clientId": "$CLIENT_ID", "clientSecret": "$CLIENT_SECRET"}")

BEARER_TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.token')

if [ "$BEARER_TOKEN" == "null" ] || [ -z "$BEARER_TOKEN" ]; then
    echo "Failed."
    echo "API Response: $TOKEN_RESPONSE"
    exit 1
fi
echo "Success."


# ================================================
# Step 2: Initial Search Request (Get Scroll ID)
# ================================================
echo "Starting initial search for contentType: "image/jpeg"..."

# Define payload for initial search with scroll enabled
INITIAL_PAYLOAD='{
  "query": "contentType: "image/jpeg"",
  "scroll": "true",
  "size": 100
}'

# Perform initial search
SEARCH_RESPONSE=$(curl -s -X POST "${API_BASE}/files/search" 
  -H "Authorization: Bearer $BEARER_TOKEN" 
  -H "Content-Type: application/json" 
  -d "$INITIAL_PAYLOAD")

# Extract total count, initial filenames, and the scrollId
TOTAL_HITS=$(echo "$SEARCH_RESPONSE" | jq -r '.total // 0')
SCROLL_ID=$(echo "$SEARCH_RESPONSE" | jq -r '.scrollId')
INITIAL_FILENAMES=$(echo "$SEARCH_RESPONSE" | jq -r '.hits[]._source.filename')

echo "Found $TOTAL_HITS total files matching criteria."

# If no files found, exit early
if [ "$TOTAL_HITS" -eq 0 ]; then
   echo "No files found. Exiting."
   exit 0
fi

# Append initial batch of filenames to file
if [ -n "$INITIAL_FILENAMES" ]; then
  echo "$INITIAL_FILENAMES" >> "$OUTPUT_FILE_PATH"
  RETRIEVED_COUNT=$(echo "$INITIAL_FILENAMES" | grep -c '^')
  echo "Retrieved batch 1: $RETRIEVED_COUNT files."
else
  # This shouldn't happen if total hits > 0, but good for safety
  echo "Error: Total hits > 0 but no filenames found in initial response."
  echo "Response payload: $SEARCH_RESPONSE"
  exit 1
fi


# ================================================
# Step 3: Scrolling Loop (Get remaining results)
# ================================================

BATCH_NUMBER=1

# Keep looping as long as we have retrieved fewer files than the total available
while [ "$RETRIEVED_COUNT" -lt "$TOTAL_HITS" ]; do
    ((BATCH_NUMBER++))

    # Define payload for scrolling search using the newly obtained scrollId
    # We use jq to safely create the JSON payload to handle special characters in scrollId
    SCROLL_PAYLOAD=$(jq -n --arg sid "$SCROLL_ID" '{"scrollId": $sid}')

    # Perform scrolling search request
    # Note the different URL endpoints: /files/search/scroll
    SCROLL_RESPONSE=$(curl -s -X POST "${API_BASE}/files/search/scroll" 
      -H "Authorization: Bearer $BEARER_TOKEN" 
      -H "Content-Type: application/json" 
      -d "$SCROLL_PAYLOAD")

    # Extract new filenames from this batch
    NEW_FILENAMES=$(echo "$SCROLL_RESPONSE" | jq -r '.hits[]._source.filename // empty')

    # If no new filenames are found, break the loop (safety check)
    if [ -z "$NEW_FILENAMES" ]; then
       echo "Warning: Expected more results but received empty batch. Ending search."
       break
    fi

    # Append new filenames to file
    echo "$NEW_FILENAMES" >> "$OUTPUT_FILE_PATH"

    # Update our local count of retrieved files
    BATCH_COUNT=$(echo "$NEW_FILENAMES" | grep -c '^')
    RETRIEVED_COUNT=$((RETRIEVED_COUNT + BATCH_COUNT))
    echo "Retrieved batch $BATCH_NUMBER: $BATCH_COUNT files. (Total: $RETRIEVED_COUNT/$TOTAL_HITS)"

    # IMPORTANT: Get the new scrollId for the next iteration
    # The API may return a new ID to use for the next request.
    SCROLL_ID=$(echo "$SCROLL_RESPONSE" | jq -r '.scrollId // empty')

    # If the API stops sending a scrollId, we cannot continue.
    if [ -z "$SCROLL_ID" ] && [ "$RETRIEVED_COUNT" -lt "$TOTAL_HITS" ]; then
        echo "Error: API did not return a new scrollId before all results were fetched."
        break
    fi
done

echo "--- Process Complete ---"
echo "Successfully saved $RETRIEVED_COUNT filenames to:"
echo "$OUTPUT_FILE_PATH"

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

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

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
 }
}

Was this article helpful?

Array

Get help from a Sirv expert

Contact Us

help ukraine help ukraine Powered by Ukrainian determination and British ingenuity

How can you support Ukraine