Sirv Getting Started: Account, Keys, and First API Request

Getting started overview

This guide outlines the initial steps for integrating with Sirv, focusing on account creation, credential retrieval, and making a foundational API request. Sirv provides a platform for image hosting, optimization, and dynamic delivery, including 360-degree product spins and video hosting as described on the Sirv homepage. The Sirv REST API facilitates programmatic management of these assets, allowing developers to automate uploads, apply dynamic imaging profiles, and manage asset metadata.

The process typically involves:

1. Creating a Sirv account.
2. Generating API credentials (client ID, client secret, bucket name).
3. Obtaining an OAuth 2.0 access token.
4. Executing a first API call, such as uploading an image.

The following table provides a quick reference for these initial steps:

Create an account and get keys

To access the Sirv API, you must first create a Sirv account. Sirv offers a free tier with 5 GB storage and 15 GB transfer per month, which is suitable for initial testing and development. Paid plans are also available, starting at $19/month.

Account Creation

1. Navigate to the Sirv pricing page.
2. Select your desired plan (e.g., the free tier) and complete the registration process. This typically involves providing an email address, setting a password, and confirming your account.
3. Once registered, log in to your Sirv dashboard.

Generating API Credentials

After logging into your Sirv dashboard, you need to generate specific API credentials to authenticate your requests. Sirv uses OAuth 2.0 with the Client Credentials Grant type for API authentication, requiring a Client ID and Client Secret.

1. From your Sirv dashboard, navigate to Account > API.
2. If no API client exists, click the button to Create new API client.
3. Sirv will generate a Client ID and a Client Secret. Record these values immediately, as the Client Secret is often shown only once for security reasons. If lost, you may need to regenerate it.
4. Note your Sirv bucket name. This is typically displayed prominently in your dashboard or account settings and forms part of your Sirv URL (e.g., https://your-bucket-name.sirv.com).

These three pieces of information—Client ID, Client Secret, and bucket name—are essential for all subsequent API interactions.

Your first request

The first step in making any Sirv API request is to obtain an access token using your Client ID and Client Secret. This token must then be included in the Authorization header of subsequent requests.

1. Obtain an Access Token

Send a POST request to the Sirv token endpoint:

POST /v2/token HTTP/1.1
Host: api.sirv.com
Content-Type: application/json

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

A successful response will return a JSON object containing an accessToken and an expiresIn value (in seconds):

{
  "accessToken": "YOUR_ACCESS_TOKEN",
  "expiresIn": 3600
}

The token is valid for the duration specified by expiresIn (e.g., 3600 seconds = 1 hour). You should refresh the token before it expires.

2. Upload an Image

With your access token, you can now perform operations like uploading an image. This example demonstrates uploading a file using curl, which is a common command-line tool for making HTTP requests as documented in the curl manual.

To upload an image named my-image.jpg to the root of your Sirv bucket:

curl -X POST \
  "https://api.sirv.com/v2/files/upload?bucketId=YOUR_BUCKET_NAME&filePath=/my-image.jpg" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@/path/to/my-image.jpg"

Replace YOUR_BUCKET_NAME, YOUR_ACCESS_TOKEN, and /path/to/my-image.jpg with your actual values. The filePath parameter specifies the desired path and filename within your Sirv bucket. A successful upload typically returns a 200 OK status with a JSON response confirming the upload.

3. Verify the Uploaded Image

You can verify the image upload by accessing it directly via its Sirv URL:

https://YOUR_BUCKET_NAME.sirv.com/my-image.jpg

Or, you can use the Sirv API to list files in your bucket:

curl -X GET \
  "https://api.sirv.com/v2/files/list?bucketId=YOUR_BUCKET_NAME&path=/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This request should return a JSON array of files, including my-image.jpg, confirming its presence in your Sirv account.

Common next steps

After successfully performing your first API request, consider these common next steps to further integrate with Sirv:

• Dynamic Imaging: Explore Sirv's dynamic imaging capabilities. You can apply various image transformations (resizing, watermarking, effects) by simply appending parameters to the image URL. Refer to the Sirv Dynamic Imaging documentation for a comprehensive list of available options.
• 360-degree Spins: If your application involves product visualization, learn how to upload image sequences to create interactive 360-degree product spins. Sirv automates the assembly of these spins, which can then be embedded on your website. The Sirv 360 Spin API documentation provides details.
• Webhooks: Set up webhooks to receive notifications about events in your Sirv account, such as new file uploads, deletions, or processing completions. Webhooks can enable real-time automation and synchronization with your backend systems.
• Integrations: Sirv offers plugins and integrations for popular e-commerce platforms like Shopify, Magento, and WooCommerce. These integrations can streamline the process of using Sirv for product imagery without extensive custom development.
• Error Handling: Implement robust error handling in your application to manage API rate limits, authentication failures, and other potential issues. The Sirv REST API error documentation details common error codes and their meanings.
• SDKs and Libraries: While Sirv does not officially provide SDKs, community-contributed libraries might exist for specific programming languages. These can simplify API interactions by abstracting HTTP requests and authentication.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting tips:

• Incorrect Credentials: Double-check your Client ID, Client Secret, and bucket name for typos. Ensure you are using the correct credentials generated for your Sirv account.
• Expired Access Token: The access token has a limited lifespan (e.g., 1 hour). If you are making requests after this period, you will need to obtain a new token. Implement a mechanism to refresh tokens proactively.
• Authorization Header Format: Ensure the Authorization header is correctly formatted as Bearer YOUR_ACCESS_TOKEN. A common mistake is omitting "Bearer " or having incorrect spacing.
• Content-Type Header: For upload requests, the Content-Type header must accurately reflect the type of file being uploaded (e.g., image/jpeg for a JPEG image). Mismatches can lead to processing errors.
• File Path Issues: Verify that the filePath parameter in your upload request specifies a valid path within your Sirv bucket and includes the correct filename and extension.
• Network Connectivity: Confirm that your environment has outbound internet access to api.sirv.com. Firewall or proxy settings might block API requests.
• Sirv API Documentation: Refer to the Sirv REST API documentation for specific endpoint details, required parameters, and expected responses. This is the authoritative source for API behavior.
• Error Messages: Pay close attention to the error messages returned by the Sirv API. They often provide specific clues about what went wrong. For example, a 401 Unauthorized typically indicates an authentication issue, while a 400 Bad Request might point to incorrect parameters or malformed JSON.