Riverstarz Digital Deliver API - Public Overview

0. Conceptual Overview

The Riverstarz Digital Deliver API empowers your applications to programmatically manage and distribute your digital music catalog. Automate your workflows, seamlessly integrate with your existing systems, and efficiently handle assets, metadata, and releases. This API is designed for backend-to-backend integration, providing a robust platform for your music distribution needs.

1. General API Information

Base URL

The primary base URL for the Riverstarz Digital Deliver API is:

• https://api.riverstarz.com

Authentication and Authorization

Authentication to the Riverstarz Digital Deliver API is performed via an API key, which must be included in the Authorization header as a Bearer token. Your API key authenticates your tenant account for all requests. Requests without a valid API key will result in a 401 Unauthorized error. Requests with an API key that lacks permission for the specific operation will result in a 403 Forbidden error.

API Design Principles

The Riverstarz Digital Deliver API is built with the following core principles in mind:

• Backend-to-Backend Integration: The API is primarily designed for server-side communication between your application and Riverstarz. Your application is responsible for authenticating its own end-users.
• Client User Context (client_user_id): Many API operations, especially those involving user-specific data (like uploads or created parties/releases), require a client_user_id to be passed in the request. This ID, obtained by registering your users via the Client User Management endpoints, is crucial. It links API activities to your end-users, ensuring actions are correctly attributed, data is properly scoped to the correct user within your tenant, and for auditability. It is vital that the client_user_id provided corresponds to a user you have registered.
• Owner-Only Data Access: For resources tied to a specific client user (e.g., assets uploaded by a user, parties they created), an 'Owner-Only' access principle is generally enforced. This means that API requests to view or modify such data must typically include the client_user_id of the resource's owner. This helps ensure that users can only access and manage their own data.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses are in JSON format. Common codes like 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Unprocessable Entity), and 500 (Internal Server Error) are used.

The JSON error response typically includes fields to help you diagnose the issue:

• type: A unique URI identifying the error type.
• title: A brief summary of the error.
• status: The HTTP status code.
• detail: A human-readable explanation of the error.
• errors (for validation issues): An object containing specific error messages for individual fields in your request.

Detailed error messages are provided in the JSON response body when an issue occurs.

Pagination

Endpoints that return a list of resources are paginated. Use the page and limit query parameters to control the data retrieved. The API response for these endpoints includes a pagination object with details such as total items, items per page, current page, and total pages.

Sorting

List endpoints support sorting of results. Use the sort_by (specifying the field) and sort_order (asc or desc) query parameters to arrange the data as needed. The applied sorting criteria are reflected in the response.

2. Core Resources and Capabilities

The Riverstarz Digital Deliver API provides a comprehensive suite of tools to manage your digital music distribution workflow.

Asset Management

Assets are your audio and artwork files. The API allows you to easily upload and manage these critical components.

• Capabilities: Upload new assets (artwork, audio), List existing assets with filtering and sorting, Get detailed information for a specific asset, and Delete assets (subject to ownership and usage checks).
• Supports various formats and adheres to industry standards.

Accepted File Configurations

Artwork Files (asset_type: "artwork")

• Allowed MIME Types: image/jpeg, image/png
• Maximum File Size: 10MB (10,485,760 bytes)
• Storage Prefix: artwork/

Audio Files (asset_type: "audio")

• Allowed MIME Types: audio/mpeg, audio/wav, audio/x-wav, audio/flac, audio/x-flac
• Maximum File Size: 200MB (209,715,200 bytes)
• Storage Prefix: audio/
• Bit Depth: 16-bit to 24-bit.
• Sample Rates: 44.1kHz, 48kHz, 88.2kHz, 96kHz.

It is recommended to ensure your uploaded files comply with these default configurations to avoid errors during the upload and processing stages.

Party Management

Parties represent entities such as artists, songwriters, publishers, or labels, and can be of type 'person' or 'organization'.

• Capabilities: Create new parties, List existing parties with filtering and sorting, Get details for a specific party, Update party information, and Delete parties (subject to ownership and usage checks).

Client User Management

Client Users are the end-users of your application. The Riverstarz Digital Deliver API enables your backend to manage these user records within our system. This is essential for proper data attribution and scoping of resources created via the API.

• Capabilities: Create client user records (to obtain a Riverstarz client_user_id for your user), Retrieve details of a specific client user, List client users with filtering, Update client user information (e.g., name, active status), and Deactivate client users.
• Important Note: Password management for your client users remains the sole responsibility of your application.

Roles Management

Roles define the function of a party in relation to a release or track (e.g., MainArtist, Composer, Producer). These roles are generally based on industry standards like DDEX and are pre-populated in the system for each tenant.

• Capabilities: List all available standard roles and Get details for a specific role.
• Note: These roles are read-only via the API.

Release Management

Releases are collections of tracks and associated metadata (artwork, label, genre, copyright lines, etc.) intended for distribution.

• Capabilities: Create new releases (including all track details and contributor information), List existing releases with filtering and sorting, Get full details for a specific release (including its tracks, contributors, and asset URLs), Update release metadata (restrictions may apply based on the release's current status), and Delete releases (restrictions may apply based on status).
• Manage track information, contributors, and rights.
• Supports a wide range of genres.

Accepted Genres

The genre field in the API expects one of the string values from the "Key" column.

4. Example API Request

To give you a practical idea of how to interact with the API, here’s an example of retrieving a list of available roles using PHP and cURL. Roles are pre-defined functions (e.g., Composer, Main Artist) that can be assigned to parties involved in a release.

Example: Listing All Roles

This example demonstrates a GET request to the /api/v1/roles endpoint to fetch all available roles for your tenant.

Endpoint: GET /api/v1/roles

PHP cURL Example:

<?php

$apiBaseUrl = 'https://api.riverstarz.com';
$apiKey = 'YOUR_SECRET_API_KEY'; // Replace with your actual API key
$endpoint = '/api/v1/roles';

$fullUrl = $apiBaseUrl . $endpoint;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $fullUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Accept: application/json' // We expect a JSON response
]);
curl_setopt($ch, CURLOPT_TIMEOUT, 30); // Set a 30-second timeout

$responseBody = curl_exec($ch);
$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); // Get HTTP status code
$curlError = curl_error($ch); // Get cURL error, if any

curl_close($ch);

if ($curlError) {
    echo "cURL Error: " . $curlError . "
";
} else {
    echo "HTTP Status Code: " . $httpStatusCode . "

";

    if ($httpStatusCode == 200) {
        $decodedResponse = json_decode($responseBody, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            echo "Successfully retrieved roles:
";
            // For demonstration, we'll print the JSON response.
            // In a real application, you would iterate through $decodedResponse['data'].
            echo json_encode($decodedResponse, JSON_PRETTY_PRINT);
        } else {
            echo "Error decoding JSON response.
";
            echo "Raw Response Body:
" . $responseBody . "
";
        }
    } else {
        // Handle other HTTP status codes (e.g., 401, 403, 500)
        echo "Error retrieving roles. Response Body (if any):
";
        echo $responseBody . "
";
    }
}

?>

Expected Success Response (Simplified):

A successful request will return a 200 OK status and a JSON object containing an array of role objects. Each role object typically includes an id, ddex_code, and display_label.

{
  "data": [
    { "id": 1, "ddex_code": "MainArtist", "display_label": "Main Artist" },
    { "id": 2, "ddex_code": "Composer",  "display_label": "Composer" },
    { "id": 3, "ddex_code": "Producer", "display_label": "Producer" }
    // ... and so on for all available roles
  ],
  "pagination": {
    // ... pagination details ...
  }
}

This example illustrates the basic pattern for making authenticated GET requests to the Riverstarz Digital Deliver API. For creating or updating data, you would use POST or PUT requests with a JSON request body, as detailed in the full developer documentation.

5. Getting Started

To start using the API with full access to detailed developer documentation, endpoint specifications, request/response examples, and to obtain your API key, please contact our support team.