> ## 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.
# Create Release
> ### POST /releases
This endpoint requires authentication. Include your Bearer token in the Authorization header.
## Description
This endpoint allows the creation of a new release with tracks. The release will be created in draft status and can be submitted for review once ready.
**Request Body**
| field | type | description |
| -------------- | ------ | ------------------------------------------------------------------ |
| title | string | The title of the release |
| format | string | Format of the release (Single, EP, Album, etc.) |
| type | string | Type of release (Audio, Video, Mixed) |
| version | string | Version of the release |
| label | string | Record label |
| copyright | string | Copyright information |
| displayArtist | string | The display artist name |
| artists | object | Artists and their roles (must include at least one primary artist) |
| mainGenre | array | Main genres |
| subGenre | array | Sub-genres |
| contributors | object | Contributors and their roles |
| description | string | Description of the release |
| metadata | object | Additional metadata |
| media | array | Array of media files |
| explicit | string | Content rating: 'explicit', 'clean', or null |
| releaseDate | string | Release date |
| preReleaseDate | string | Pre-release date |
| tracks | array | Array of tracks |
| ownerId | string | Optional: specify a different owner |
## Code Examples
```javascript Node.js theme={null}
const response = await fetch('https://api.royalti.io/releases', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"title": "sample-title",
"displayArtist": "sample-displayArtist",
"artists": {},
"format": "sample-format",
"type": "sample-type",
"version": "sample-version",
"label": "sample-label",
"copyright": "sample-copyright",
"mainGenre": [
{}
],
"subGenre": [
{}
],
"contributors": {},
"description": "sample-description",
"metadata": {},
"media": [
{
"ref": "#/components/schemas/Media"
}
],
"explicit": "sample-explicit",
"ownerId": "550e8400-e29b-41d4-a716-446655440000",
"releaseDate": "2024-01-21",
"preReleaseDate": "2024-01-21",
"tracks": [
{
"title": "sample-title",
"version": "sample-version",
"isrc": "sample-isrc",
"iswc": "sample-iswc",
"duration": 1,
"lyrics": "sample-lyrics",
"language": "sample-language",
"displayArtist": "sample-displayArtist",
"artists": {},
"mainGenre": [
{}
],
"subGenre": [
{}
],
"contributors": {},
"media": [
{}
],
"metadata": {},
"explicit": "sample-explicit"
}
]
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.royalti.io/releases',
headers={
'Authorization': f'Bearer {token}'
},
json={"title":"sample-title","displayArtist":"sample-displayArtist","artists":{},"format":"sample-format","type":"sample-type","version":"sample-version","label":"sample-label","copyright":"sample-copyright","mainGenre":[{}],"subGenre":[{}],"contributors":{},"description":"sample-description","metadata":{},"media":[{"ref":"#/components/schemas/Media"}],"explicit":"sample-explicit","ownerId":"550e8400-e29b-41d4-a716-446655440000","releaseDate":"2024-01-21","preReleaseDate":"2024-01-21","tracks":[{"title":"sample-title","version":"sample-version","isrc":"sample-isrc","iswc":"sample-iswc","duration":1,"lyrics":"sample-lyrics","language":"sample-language","displayArtist":"sample-displayArtist","artists":{},"mainGenre":[{}],"subGenre":[{}],"contributors":{},"media":[{}],"metadata":{},"explicit":"sample-explicit"}]}
)
data = response.json()
print(data)
```
```bash cURL theme={null}
curl -X POST https://api.royalti.io/releases \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"sample-title","displayArtist":"sample-displayArtist","artists":{},"format":"sample-format","type":"sample-type","version":"sample-version","label":"sample-label","copyright":"sample-copyright","mainGenre":[{}],"subGenre":[{}],"contributors":{},"description":"sample-description","metadata":{},"media":[{"ref":"#/components/schemas/Media"}],"explicit":"sample-explicit","ownerId":"550e8400-e29b-41d4-a716-446655440000","releaseDate":"2024-01-21","preReleaseDate":"2024-01-21","tracks":[{"title":"sample-title","version":"sample-version","isrc":"sample-isrc","iswc":"sample-iswc","duration":1,"lyrics":"sample-lyrics","language":"sample-language","displayArtist":"sample-displayArtist","artists":{},"mainGenre":[{}],"subGenre":[{}],"contributors":{},"media":[{}],"metadata":{},"explicit":"sample-explicit"}]}'
```
## OpenAPI
````yaml post /releases
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:
/releases:
post:
tags:
- Release
summary: Create Release
description: >-
### POST /releases
This endpoint allows the creation of a new release with tracks. The
release will be created in draft status and can be submitted for review
once ready.
**Request Body**
| field | type | description |
| --- | --- | --- |
| title | string | The title of the release |
| format | string | Format of the release (Single, EP, Album, etc.) |
| type | string | Type of release (Audio, Video, Mixed) |
| version | string | Version of the release |
| label | string | Record label |
| copyright | string | Copyright information |
| displayArtist | string | The display artist name |
| artists | object | Artists and their roles (must include at least one
primary artist) |
| mainGenre | array | Main genres |
| subGenre | array | Sub-genres |
| contributors | object | Contributors and their roles |
| description | string | Description of the release |
| metadata | object | Additional metadata |
| media | array | Array of media files |
| explicit | string | Content rating: 'explicit', 'clean', or null |
| releaseDate | string | Release date |
| preReleaseDate | string | Pre-release date |
| tracks | array | Array of tracks |
| ownerId | string | Optional: specify a different owner |
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The title of the release
displayArtist:
type: string
description: The display artist name
artists:
type: object
description: >-
Artists and their roles (must include at least one primary
artist)
additionalProperties:
type: string
enum:
- primary
- featuring
format:
type: string
description: Format of the release
enum:
- Single
- EP
- Album
- LP
- Video
default: Single
type:
type: string
description: Type of release
enum:
- Audio
- Video
default: Audio
version:
type: string
description: Version of the release
label:
type: string
description: Record label
copyright:
type: string
description: Copyright information
mainGenre:
type: array
items:
type: string
description: Main genres of the release
subGenre:
type: array
items:
type: string
description: Sub-genres of the release
contributors:
type: object
description: Contributors and their roles
additionalProperties:
type: array
items:
type: string
description:
type: string
description: Description of the release
metadata:
type: object
description: Additional metadata
additionalProperties: true
media:
type: array
items:
$ref: '#/components/schemas/Media'
explicit:
type: string
enum:
- explicit
- clean
nullable: true
default: null
description: 'Content rating: explicit, clean, or null (not specified)'
ownerId:
type: string
format: uuid
nullable: true
description: >-
Optional: UUID of the user who will own the release
(admin/owner only)
example: 550e8400-e29b-41d4-a716-446655440000
releaseDate:
type: string
format: date
description: Release date
preReleaseDate:
type: string
format: date
description: Pre-release date
tracks:
type: array
items:
type: object
properties:
title:
type: string
description: Title of the track
version:
type: string
description: Version of the track
isrc:
type: string
description: International Standard Recording Code
iswc:
type: string
description: International Standard Musical Work Code
duration:
type: integer
description: Duration in seconds
lyrics:
type: string
description: Lyrics of the track
language:
type: string
description: Language code (e.g., EN, ES, FR)
displayArtist:
type: string
description: Artist name as displayed for this track
artists:
type: object
description: Artists and their roles for this track
additionalProperties:
type: string
mainGenre:
type: array
items:
type: string
description: Main genres of the track
subGenre:
type: array
items:
type: string
description: Sub-genres of the track
contributors:
type: object
description: Contributors and their roles for this track
additionalProperties:
type: array
items:
type: string
media:
type: array
items:
type: object
description: Media files for this track
metadata:
type: object
description: Additional metadata for the track
additionalProperties: true
explicit:
type: string
enum:
- explicit
- clean
nullable: true
default: null
description: >-
Content rating: explicit, clean, or null (not
specified)
required:
- title
- displayArtist
- artists
description: Array of tracks in the release
required:
- title
- displayArtist
- artists
- tracks
example:
title: My First Single
displayArtist: Test Artist
artists:
Test Artist: primary
format: Single
type: Audio
version: Radio Edit
label: Independent Records
copyright: 2024 Test Artist
mainGenre:
- Pop
- Rock
subGenre:
- Alternative
contributors:
producer:
- Producer Name
songwriter:
- Test Artist
- Co-Writer
description: A catchy single with great production
metadata:
recordingStudio: Abbey Road Studios
mixedBy: Famous Engineer
media:
- url: https://example.com/media.mp3
type: audio
name: Media
explicit: null
releaseDate: '2024-12-01'
preReleaseDate: '2024-11-15'
ownerId: 550e8400-e29b-41d4-a716-446655440000
tracks:
- title: My First Single
version: Radio Edit
isrc: USCM51500001
iswc: T-000.000.001-0
duration: 210
lyrics: |-
Verse 1
Chorus
Verse 2
Chorus
Bridge
Chorus
language: EN
displayArtist: Test Artist
artists:
Test Artist: primary
mainGenre:
- Pop
subGenre:
- Alternative
contributors:
songwriter:
- Test Artist
media: []
metadata:
bpm: 120
key: C Major
explicit: null
responses:
'201':
description: Success - Release created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
$ref: '#/components/schemas/Release'
'400':
description: Bad Request - Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
Media:
type: object
properties:
cloudId:
type: string
description: Cloud storage file ID or unique identifier for links
example: 550e8400-e29b-41d4-a716-446655440000
cloudUrl:
type: string
format: uri
description: Public URL from cloud storage OR the submitted link URL
example: https://storage.royalti.io/files/audio.mp3
type:
type: string
enum:
- audio
- video
- image
- document
description: File type
example: audio
name:
type: string
description: File name or link title
example: my-track.mp3
isLink:
type: boolean
description: Flag to distinguish links from files
example: false
releasePath:
type: string
description: Temporary release storage path (for files only)
nullable: true
example: tenant123/releases/release456/tracks/track789/file.mp3
metadata:
type: object
description: Additional metadata
properties:
duration:
type: number
format: float
description: Duration in seconds
example: 213.5
bitrate:
type: string
description: Audio bitrate
example: '320'
sampleRate:
type: string
description: Audio sample rate
example: '44100'
channels:
type: string
description: Audio channels
example: '2'
codec:
type: string
description: Audio/video codec
example: mp3
fileSize:
type: number
description: File size in bytes
example: 1048576
mimeType:
type: string
description: MIME type
example: audio/mpeg
processedAt:
type: string
format: date-time
description: Processing timestamp
linkValidated:
type: boolean
description: For link submissions - validation status
example: true
additionalProperties: true
Release:
type: object
required:
- id
- TenantId
- TenantUserId
- title
- displayArtist
- artists
- tracks
properties:
id:
type: string
TenantId:
type: string
TenantUserId:
type: string
title:
type: string
format:
type: string
example: Single
type:
type: string
example: Audio
version:
type: string
nullable: true
label:
type: string
nullable: true
copyright:
type: string
nullable: true
displayArtist:
type: string
artists:
type: array
items:
$ref: '#/components/schemas/ArtistReference'
description: Array of artists with resolved names and types
mainGenre:
type: array
items:
type: string
subGenre:
type: array
items:
type: string
contributors:
type: array
items:
type: string
description:
type: string
nullable: true
metadata:
type: object
nullable: true
media:
type: array
items:
type: object
explicit:
type: string
enum:
- explicit
- clean
nullable: true
description: 'Content rating: explicit, clean, or null (not specified)'
releaseDate:
type: string
format: date-time
nullable: true
preReleaseDate:
type: string
format: date-time
nullable: true
status:
type: string
autoCreationStatus:
type: string
enum:
- pending
- success
- failed
nullable: true
description: Status of auto-creation pipeline (null if not started)
autoCreationError:
type: string
nullable: true
description: Error message if auto-creation failed
createdProductId:
type: string
format: uuid
nullable: true
description: UUID of Product created during auto-creation
createdAssetIds:
type: array
items:
type: string
format: uuid
nullable: true
description: >-
Array of Asset UUIDs created during auto-creation (excludes linked
assets)
tracks:
type: array
items:
$ref: '#/components/schemas/ReleaseTrack'
owner:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
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
ArtistReference:
type: object
required:
- id
- artistName
- type
properties:
id:
type: string
format: uuid
description: Artist UUID
example: 3816be64-720c-4105-990f-a6b99b0f928b
artistName:
type: string
description: Artist name
example: Bally Jhay
type:
type: string
enum:
- primary
- featuring
description: Artist role
example: primary
ReleaseTrack:
type: object
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
TenantId:
type: integer
example: 123
ReleaseId:
type: string
format: uuid
example: 660e8400-e29b-41d4-a716-446655441111
assetId:
type: string
format: uuid
nullable: true
description: Reference to linked Asset (if any)
example: 770e8400-e29b-41d4-a716-446655442222
trackNumber:
type: integer
example: 1
title:
type: string
example: My Track Title
version:
type: string
nullable: true
example: Radio Edit
isrc:
type: string
nullable: true
example: USABC1234567
iswc:
type: string
nullable: true
example: T-123456789-0
duration:
type: number
format: float
nullable: true
example: 213.5
lyrics:
type: string
nullable: true
example: |-
Verse 1
Chorus
Verse 2
language:
type: string
example: en
displayArtist:
type: string
example: Artist Name
artists:
type: array
items:
$ref: '#/components/schemas/ArtistReference'
description: Array of artists with resolved names and types
example:
- id: 550e8400-e29b-41d4-a716-446655440000
artistName: John Doe
type: primary
- id: 660e8400-e29b-41d4-a716-446655441111
artistName: Jane Smith
type: featuring
mainGenre:
type: array
items:
type: string
example:
- Pop
- Rock
subGenre:
type: array
items:
type: string
example:
- Alternative
contributors:
type: object
additionalProperties:
type: array
items:
type: string
example:
producer:
- Producer Name
songwriter:
- Writer Name
media:
type: array
items:
$ref: '#/components/schemas/Media'
metadata:
type: object
additionalProperties: true
example:
bpm: 120
key: C Major
explicit:
type: string
enum:
- explicit
- clean
nullable: true
description: 'Content rating: explicit, clean, or null (not specified)'
example: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Authorization header using the Bearer scheme. Format: "Bearer
{token}"
````