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

| Operation | Method | Endpoint | Key Params | |-----------|--------|----------|------------| | Upload | POST | /v2/files/upload | ?filename=/path/file.jpg + binary body | | Download | GET | /v2/files/download | ?filename=/path/file.jpg | | Delete | POST | /v2/files/delete | ?filename=/path/file.jpg | | Copy | POST | /v2/files/copy | ?from=/a.jpg&to=/b.jpg | | Rename/Move | POST | /v2/files/rename | ?from=/a.jpg&to=/b.jpg | | Create folder | POST | /v2/files/mkdir | ?dirname=/new-folder | | List directory | GET | /v2/files/readdir | ?dirname=/folder |

Metadata Operations

| Operation | Method | Endpoint | |-----------|--------|----------| | Get all meta | GET | /v2/files/meta?filename=/path | | Set meta | POST | /v2/files/meta?filename=/path | | Get/Set title | GET/POST | /v2/files/meta/title?filename=/path | | Get/Set description | GET/POST | /v2/files/meta/description?filename=/path | | Get/Add/Delete tags | GET/POST/DELETE | /v2/files/meta/tags?filename=/path | | Get/Set product | GET/POST | /v2/files/meta/product?filename=/path |

Async Jobs (return job ID, poll for progress)

| Operation | Start | Poll | |-----------|-------|------| | Spin to video | POST /v2/files/spin2video | Returns filename directly | | Video to spin | POST /v2/files/video2spin | Returns filename directly | | Create ZIP | POST /v2/files/zip | GET /v2/files/zip?id= | | Batch delete | POST /v2/files/batch/delete | GET /v2/files/batch/delete?id= | | 3D to GLB | POST /v2/files/3d/model2GLB | GET /v2/files/3d/model2GLB?id= |

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