Sirv REST API

Base URL: https://api.sirv.com

Authentication

All requests require a Bearer token from /v2/token:

curl -X POST https://api.sirv.com/v2/token \
  -H "Content-Type: application/json" \
  -d '{"clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET"}'

Response:

{"token": "eyJhbG...", "expiresIn": 1200, "scope": ["account:read", ...]}

Use token in subsequent requests:

curl https://api.sirv.com/v2/account \
  -H "Authorization: Bearer eyJhbG..."

Tokens expire in 20 minutes. Request a new one before expiry.

Quick Reference

File Operations

Metadata Operations

Async Jobs (return job ID, poll for progress)

When to Read Reference Files

• File operations (upload, download, copy, delete, directory listing): See files.md
• Metadata & search (meta fields, search query syntax, product data): See metadata.md
• Async jobs (video conversion, ZIP, batch ops): See jobs.md
• Account & stats (usage, billing, events, settings): See account.md

Common Patterns

Upload an image

const token = await getToken();
await fetch('https://api.sirv.com/v2/files/upload?filename=/images/photo.jpg', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'image/jpeg'
  },
  body: imageBuffer
});

Search for recent images

await fetch('https://api.sirv.com/v2/files/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'extension:.jpg AND mtime:[now-7d TO now]',
    size: 50
  })
});

Create ZIP archive (async)

// Start job
const { id } = await fetch('https://api.sirv.com/v2/files/zip', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    filenames: ['/images/photo1.jpg', '/images/photo2.jpg'],
    zipFilename: '/downloads/photos.zip'
  })
}).then(r => r.json());

// Poll until complete
let progress = 0;
while (progress < 100) {
  const status = await fetch(`https://api.sirv.com/v2/files/zip?id=${id}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  }).then(r => r.json());
  progress = status.progress;
  await new Promise(r => setTimeout(r, 1000));
}