> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get all assets
> Retrieve a paginated list of assets. Supports filtering, sorting, and searching.
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
**Query Parameters:**
| Parameter | Type | Description |
| ---------- | ------- | --------------------------------------------- |
| search | string | Search term to filter assets |
| type | string | |
| splits | boolean | |
| artist | string | filter by artist uuids |
| statistics | boolean | include assets stats |
| sort | string | Field to sort by (default: 'createdAt') |
| order | string | Sort order ('asc' or 'desc', default: 'desc') |
| attributes | string | Comma-separated list of attributes to include |
| size | number | Items per page (default: 10) |
| page | number | Page number (default: 1) |
| product | string | Include product id to filter assets |
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/asset', {
method: 'GET',
headers: {
'Authorization': `Bearer ${token}`,
},
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.royalti.io/asset',
headers={
'Authorization': f'Bearer {token}'
},
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X GET https://api.royalti.io/asset \
-H "Authorization: Bearer YOUR_TOKEN" \
```
## OpenAPI
````yaml get /asset
openapi: 3.0.0
info:
title: Royalti.io API
description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
version: 2.6.0
contact:
name: Royalti.io Support
email: support@royalti.io
url: https://royalti.io
license:
name: Proprietary
url: https://royalti.io/terms
servers:
- url: https://api.royalti.io
description: Production server
- url: https://api-dev.royalti.io
description: Development server
- url: http://localhost:8084
description: Local development
security:
- bearerAuth: []
tags:
- name: Accounting
description: Accounting and financial transaction operations
- name: DDEX
description: DDEX operations (ERN/MEAD, messages, delivery, providers)
- name: Label
description: Label management operations
- name: Internal Webhooks
description: Internal system webhooks for royalty processing and downloads
- name: Payment Webhooks
description: Payment processor webhook endpoints
- name: Billing Webhooks
description: Stripe billing and subscription webhooks
- name: Infrastructure Webhooks
description: Cloudflare domain and SSL webhooks
- name: Distribution Webhooks
description: Digital distribution platform webhooks (FUGA)
paths:
/asset:
get:
tags:
- Asset
summary: Get all assets
description: >-
Retrieve a paginated list of assets. Supports filtering, sorting, and
searching.
**Query Parameters:**
| Parameter | Type | Description |
| --- | --- | --- |
| search | string | Search term to filter assets |
| type | string |
| splits | boolean |
| artist | string | filter by artist uuids |
| statistics | boolean | include assets stats |
| sort | string | Field to sort by (default: 'createdAt') |
| order | string | Sort order ('asc' or 'desc', default: 'desc') |
| attributes | string | Comma-separated list of attributes to include |
| size | number | Items per page (default: 10) |
| page | number | Page number (default: 1) |
| product | string | Include product id to filter assets |
parameters:
- in: query
name: search
schema:
type: string
description: Search term
- in: query
name: type
schema:
type: string
description: Asset type
- in: query
name: splits
schema:
type: boolean
default: false
description: Include splits
- in: query
name: artist
schema:
type: string
description: Filter by artist uuids
- in: query
name: statistics
schema:
type: boolean
default: false
description: Include assets stats
- in: query
name: sort
schema:
type: string
default: createdAt
enum:
- updatedAt
- createdAt
- title
- isrc
- displayArtist
- type
- splits
- products
- count
- royalty
description: >
Field to sort by. Standard fields include any asset attribute (e.g.,
title, isrc, displayArtist, createdAt).
When `statistics=true`, additional sortable fields become available:
- `splits` - Number of splits associated with the asset
- `products` - Number of products containing this asset
- `count` - Total stream/sales count from royalty data
- `royalty` - Total royalty earnings
- in: query
name: order
schema:
type: string
description: 'Sort order (''asc'' or ''desc'', default: ''desc'')'
- name: attributes
in: query
schema:
type: string
description: Comma-separated list of attributes to include
- in: query
name: size
schema:
type: integer
default: 10
description: Items per page
- in: query
name: page
schema:
type: integer
default: 1
description: Page number
- in: query
name: limit
schema:
type: integer
default: 10
description: Items per page
responses:
'200':
description: List of assets retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Asset'
total:
type: integer
page:
type: integer
limit:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
security:
- bearerAuth: []
components:
schemas:
Asset:
type: object
required:
- title
- mainArtist
- displayArtist
properties:
id:
type: string
format: uuid
description: Pre-generated UUID (optional, rarely used)
example: 550e8400-e29b-41d4-a716-446655440000
title:
type: string
description: Title of the asset
example: Midnight City
mainArtist:
type: array
items:
type: string
description: >
Main artist name(s) for the asset (display purposes).
**Note:** This is an array of artist NAMES (strings), not UUIDs.
For creating artist associations/relationships, use the 'artists'
field with UUIDs.
example:
- M83
- M47
displayArtist:
type: string
maxLength: 510
description: Display name for the lead artist (single string representation)
example: M83
otherArtist:
type: array
items:
type: string
description: |
Featured artist name(s) in the asset (display purposes).
These are artist NAMES (strings), not UUIDs.
example:
- Featured Artist
type:
type: string
enum:
- Audio
- Video
- Ringtone
- YouTube
default: Audio
description: Type of asset
example: Audio
version:
type: string
description: Version of the asset (e.g., Remix, Live Version)
example: Album Version
isrc:
type: string
pattern: ^[A-Z]{2}[A-Z0-9]{3}[0-9]{2}[0-9]{5}$
description: >-
International Standard Recording Code (auto-generated if not
provided)
example: USRC17607839
iswc:
type: string
pattern: ^T-\d{9}-\d$
description: International Standard Musical Work Code
example: T-123456789-0
lyrics:
type: string
description: Lyrics of the asset
example: Waiting in a car...
mainGenre:
type: array
items:
type: string
description: Main genre(s) of the asset
example:
- Electronic
- Synthpop
subGenre:
type: array
items:
type: string
description: Sub-genre(s) of the asset
example:
- Synthwave
contributors:
type: object
description: Contributors to the asset (producers, mixers, songwriters, etc.)
additionalProperties:
type: array
items:
type: string
example:
producers:
- Producer Name
mixers:
- Mixer Name
songwriters:
- Songwriter Name
externalId:
type: string
description: External identifier for the asset
example: EXT-12345
extra:
type: object
description: Additional metadata about the asset
additionalProperties: true
example:
notes: Recorded in Abbey Road Studios
metadata:
type: object
description: General metadata for the asset
additionalProperties: true
example:
releaseYear: 2011
assetIDs:
type: array
items:
type: string
description: Array of individual asset IDs (for album assets)
example:
- asset-1
- asset-2
explicit:
type: string
enum:
- explicit
- clean
description: Explicit content flag
example: clean
label:
type: string
description: Record label
example: Royalti Records
copyright:
type: string
description: Copyright information
example: © 2024 Royalti Records
publisher:
type: string
description: Publisher name
example: Royalti Publishing
copyrightOwner:
type: string
description: Copyright owner name
example: Royalti Music Group
artists:
type: array
description: >
Artist associations for creating relational links in the database.
**Note:** This field uses artist record UUIDs (not names) to create
entries in the ArtistAsset join table.
This is separate from 'mainArtist' which stores artist names for
display.
Can be either:
- Array of UUID strings: ["uuid1", "uuid2"]
- Array of objects with id and type: [{id: "uuid1", type:
"primary"}]
items:
oneOf:
- type: string
format: uuid
description: Artist UUID (defaults to type 'primary')
- type: object
description: Artist association with explicit type
properties:
id:
type: string
format: uuid
description: Artist record UUID
type:
type: string
enum:
- primary
- featuring
default: primary
description: Artist role type
example:
- id: 550e8400-e29b-41d4-a716-446655440000
type: primary
- 660e8400-e29b-41d4-a716-446655440001
split:
type: array
description: Revenue split configuration (must total 100%)
items:
type: object
required:
- user
- share
properties:
user:
type: string
format: uuid
description: User ID for the split
share:
type: number
format: float
minimum: 0
maximum: 100
description: Percentage share (must total 100 across all splits)
example:
- user: 550e8400-e29b-41d4-a716-446655440002
share: 60
- user: 550e8400-e29b-41d4-a716-446655440003
share: 40
ddexMetadata:
type: object
description: DDEX-specific metadata
additionalProperties: true
example:
releaseType: Single
recordLabel: Royalti Records
resourceReference:
type: string
description: >-
DDEX resource reference (auto-generated if DDEX enabled but not
provided)
example: SR123456789
technicalResourceDetails:
type: object
description: Technical details of the resource
properties:
fileFormat:
type: string
example: WAV
audioCodec:
type: string
example: PCM
bitrate:
type: integer
example: 1411
sampleRate:
type: integer
example: 44100
duration:
type: string
example: PT3M45S
soundRecordingDetails:
type: object
description: Sound recording specific details
properties:
recordingDate:
type: string
format: date
example: '2024-01-15'
recordingLocation:
type: string
example: Abbey Road Studios
language:
type: string
example: en
musicalWorkReference:
type: object
description: Musical work reference information
properties:
workId:
type: string
example: work-123
iswc:
type: string
example: T-123456789-0
enableDDEX:
type: boolean
description: Enable DDEX for this asset
example: false
focusTrack:
type: boolean
description: Whether this is a focus track for MEAD
default: false
example: false
danceStyle:
type: array
items:
type: string
description: Dance style(s) for MEAD
example:
- Electronic Dance
rhythmStyle:
type: array
items:
type: string
description: Rhythm style(s) for MEAD
example:
- Upbeat
instrumentation:
type: array
items:
type: string
description: Instrumentation for MEAD
example:
- Synthesizer
- Drums
recordingLocation:
type: string
maxLength: 255
description: Recording location
example: Abbey Road Studios
recordingDate:
type: string
format: date
description: Recording date
example: '2024-01-15'
alternativeTitles:
type: array
items:
type: string
description: Alternative titles for the asset
example:
- Alt Title 1
- Alt Title 2
chartPositions:
type: array
items:
type: object
description: Chart positions
example:
- chart: Billboard Hot 100
position: 10
date: '2024-01-01'
reviews:
type: array
items:
type: object
description: Reviews of the asset
example:
- reviewer: Music Magazine
rating: 4.5
text: Great track!
awards:
type: array
items:
type: object
description: Awards received
example:
- name: Best Electronic Song
year: 2024
socialMediaHandles:
type: object
description: Social media handles
additionalProperties:
type: string
example:
twitter: '@artistname'
instagram: '@artistname'
language:
type: string
description: Language of the asset
example: en
mood:
type: array
items:
type: string
description: Mood of the asset
example:
- Energetic
- Uplifting
tempo:
type: number
description: Tempo in BPM
example: 128
key:
type: string
description: Musical key
example: C Major
productionYear:
type: integer
description: Year of production
example: 2024
Error:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: array
items:
type: string
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: Unauthorized
ServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````