This guide will get you up and running with the Royalti.io API in just a few minutes. You’ll learn how to authenticate, make your first API call, and explore the core functionality.

​
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.
All API requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Step 2: Make Your First API Call

Let’s start with retrieving your user information: 
curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/user" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

​
Error Handling

The API returns standard HTTP status codes with detailed error information:
Status CodeDescription
200The request was processed successfully
400Bad Request - missing parameters, incorrect format, or validation failure
401Unauthorized - verify authentication token is provided and valid
404Not Found - the requested endpoint or entity does not exist
500Internal Server Error

​
Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": ["Required field missing"]
  }
}

​
Pagination, Sorting & Filtering

Most endpoints support comprehensive query parameters for data management:

​
Common Query Parameters

ParameterTypeDescriptionDefault
qstringGlobal search parameter. Searches across multiple fields.None
pagenumberPage number for pagination.1
sizenumberNumber of items to return per page.10
orderstringSort order. Options: ‘asc’ or ‘desc’.‘desc’
sortstringField to sort by.‘updatedAt’
attributesstringComma-separated list of fields to return.Varies by endpoint
statisticsbooleanWhether to include statistical data.false

​
Endpoint-Specific Parameters

Artists:
  • user - Filter by user ID(s), comma-separated for multiple
  • catalog - Filter by catalog
Assets:
  • artist - Filter by artist ID(s), comma-separated for multiple
  • type - Filter by asset type
  • splits - Whether to include splits information
Products:
  • artist - Filter by artist ID(s), comma-separated for multiple
  • type - Filter by product type
  • splits - Whether to include splits information
Expenses:
  • include - Additional models to include: ‘Artist’, ‘Product’, ‘Asset’

​
Step 3: Common API Operations

​
Get Artists with Filtering

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/artist?q=john&page=1&size=20&order=asc&sort=artistName&statistics=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Create a New Artist

curl -X POST "https://server26-dot-royalti-project.uc.r.appspot.com/artist/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "artistName": "Sample Artist",
    "signDate": "2024-01-21",
    "label": "Sample Records",
    "users": ["user-id-1", "user-id-2"],
    "split": [
      {"user": "user-id-1", "share": 60},
      {"user": "user-id-2", "share": 40}
    ]
  }'

​
Get Assets with Complex Filtering

curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/asset?q=hit&page=2&size=20&sort=createdAt&order=desc&type=audio&artist=artistId1&statistics=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Advanced Filtering Examples

​
Multiple Filters

# Filter by status and type
GET /api/expenses?status=approved&type=marketing&include=Artist,Product

# Filter by multiple user IDs
GET /api/assets?user=userId1,userId2,userId3&splits=true

​
Search with Pagination

# Search for "marketing" expenses with pagination
GET /api/expenses?q=marketing&page=1&size=25&include=Artist,Product&sort=amount&order=desc

​
Response Format

All API responses follow a consistent structure: 
{
  "success": true,
  "data": {
    // Response data here
  },
  "total": 150,
  "page": 1,
  "size": 10
}

​
Best Practices

​
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: