Skip to main content
This guide will get you up and running with the Royalti.io API quickly. You’ll learn how to authenticate, make your first API call, and explore 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)

​
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
We support TLSv1.2 and later versions. Ensure your client supports modern encryption standards.

​
Step 1: Get Your Access Token

1

Login to get refresh token

Send your credentials to the login endpoint:
cURL
curl -X POST "https://server26-dot-royalti-project.uc.r.appspot.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'
This returns a refresh_token and list of your workspaces.
2

Exchange refresh token for access token

Use the refresh token to get an access token for your workspace:
cURL
curl -X GET "https://server26-dot-royalti-project.uc.r.appspot.com/auth/authtoken?currentWorkspace=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_REFRESH_TOKEN"
This returns an access_token that you’ll use for all subsequent API calls.
3

Use the access token

Include the access token in all API requests:
Authorization: Bearer YOUR_ACCESS_TOKEN
Access tokens expire after 6 hours. Refresh tokens expire after 1 day. See the Authentication guide for token lifecycle management.

​
Step 2: Make Your First API Call

Let’s retrieve 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"

​
Step 3: Common Operations

​
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}
    ]
  }'

​
Query Artists with Filters

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"

​
Pagination, Sorting & Filtering

Most endpoints support these query parameters:
ParameterTypeDescriptionDefault
qstringGlobal search across multiple fieldsNone
pagenumberPage number for pagination1
sizenumberItems per page10
orderstringSort order: ‘asc’ or ‘desc''desc’
sortstringField to sort by’updatedAt’
attributesstringComma-separated fields to returnAll
statisticsbooleanInclude statistical datafalse

​
Endpoint-Specific Filters

Artists:
  • user - Filter by user ID(s), comma-separated
  • catalog - Filter by catalog
Assets:
  • artist - Filter by artist ID(s), comma-separated
  • type - Filter by asset type
  • splits - Include splits information
Products:
  • artist - Filter by artist ID(s), comma-separated
  • type - Filter by product type
  • splits - Include splits information

​
Response Format

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

​
Error Handling

The API uses standard HTTP status codes:
Status CodeDescription
200Success
400Bad Request - invalid parameters or validation failure
401Unauthorized - invalid or expired token
404Not Found - endpoint or entity doesn’t exist
500Internal Server Error

​
Error Response Format

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

​
Best Practices

​
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

  • Always check HTTP status codes
  • Implement retry logic for 5xx errors
  • Validate input data before sending requests
  • Handle rate limiting gracefully

​
Security

  • Never expose access tokens in client-side code
  • Use HTTPS for all requests
  • Validate SSL certificates
  • Rotate access tokens regularly

​
Next Steps

Now that you’ve made your first API calls, explore:
  • Authentication Reference - Complete guide to all authentication methods
  • API Reference - Comprehensive endpoint documentation
  • Artist Management - Deep dive into artist and catalog management
  • Payment Processing - Handle financial transactions and distributions

​
Support

Need help? We’re here for you: