Prerequisites
Before you begin, youβll need:- A Royalti.io account (sign up here)
- API access credentials
- A tool to make HTTP requests (cURL, Postman, or your preferred programming language)
Authentication & Security
Royalti is built on a secure communication protocol. The Royalti API consists of a set of instructions that are sent through HTTPS requests. We use Verisign-issued certificates for added security.Security Requirements
Important Security Notes:
- All API requests must use HTTPS
- Never connect via unencrypted HTTP as this exposes your access token
- Always verify SSL certificates - stop operations if certificate validation fails
- Access tokens use industry-standard cryptographic algorithms
- Store access tokens securely and never share with unauthorized parties
TLS Support
We support TLSv1.2 and later versions. Ensure your client supports modern encryption standards.Step 1: Authentication
Authentication details and token generation endpoints are available in the Authentication section.
Step 2: Make Your First API Call
Letβs start with retrieving your user information:Error Handling
The API returns standard HTTP status codes with detailed error information:Status Code | Description |
---|---|
200 | The request was processed successfully |
400 | Bad Request - missing parameters, incorrect format, or validation failure |
401 | Unauthorized - verify authentication token is provided and valid |
404 | Not Found - the requested endpoint or entity does not exist |
500 | Internal Server Error |
Error Response Format
Pagination, Sorting & Filtering
Most endpoints support comprehensive query parameters for data management:Common Query Parameters
Parameter | Type | Description | Default |
---|---|---|---|
q | string | Global search parameter. Searches across multiple fields. | None |
page | number | Page number for pagination. | 1 |
size | number | Number of items to return per page. | 10 |
order | string | Sort order. Options: βascβ or βdescβ. | βdescβ |
sort | string | Field to sort by. | βupdatedAtβ |
attributes | string | Comma-separated list of fields to return. | Varies by endpoint |
statistics | boolean | Whether to include statistical data. | false |
Endpoint-Specific Parameters
Artists:user
- Filter by user ID(s), comma-separated for multiplecatalog
- Filter by catalog
artist
- Filter by artist ID(s), comma-separated for multipletype
- Filter by asset typesplits
- Whether to include splits information
artist
- Filter by artist ID(s), comma-separated for multipletype
- Filter by product typesplits
- Whether to include splits information
include
- Additional models to include: βArtistβ, βProductβ, βAssetβ
Step 3: Common API Operations
Get Artists with Filtering
Create a New Artist
Get Assets with Complex Filtering
Advanced Filtering Examples
Multiple Filters
Search with Pagination
Response Format
All API responses follow a consistent structure:Best Practices
Performance Optimization
Performance Optimization
- Use the
attributes
parameter to limit response payload size - Implement proper pagination for large datasets
- Cache responses where appropriate
- Use
statistics=false
unless statistical data is needed
Error Handling
Error Handling
- Always check HTTP status codes
- Implement retry logic for 5xx errors
- Validate input data before sending requests
- Handle rate limiting gracefully
Security
Security
- Never expose access tokens in client-side code
- Use HTTPS for all requests
- Validate SSL certificates
- Rotate access tokens regularly
Next Steps
Authentication Reference
Complete authentication flow documentation
Artist Management
Comprehensive artist management APIs
Asset Management
Manage songs, albums, and digital content
Payment Processing
Handle payments and financial transactions
Important Notes
- All endpoints support the common query parameters unless otherwise specified
- When using multiple values for a single parameter, separate them with commas
- The
attributes
parameter optimizes payload size by returning only specified fields - The
statistics
parameter may increase response time when enabled - Always check specific endpoint documentation for variations or additional parameters
Support
Need help? Weβre here for you:- π Full API Documentation
- π¬ Support Center
- π API Status Page