Skip to main content
POST
/
asset
Create a new asset
curl --request POST \
  --url https://api.royalti.io/asset \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Midnight City",
  "mainArtist": [
    "M83",
    "M47"
  ],
  "displayArtist": "M83",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "otherArtist": [
    "Featured Artist"
  ],
  "type": "Audio",
  "version": "Album Version",
  "isrc": "USRC17607839",
  "iswc": "T-123456789-0",
  "lyrics": "Waiting in a car...",
  "mainGenre": [
    "Electronic",
    "Synthpop"
  ],
  "subGenre": [
    "Synthwave"
  ],
  "contributors": {
    "producers": [
      "Producer Name"
    ],
    "mixers": [
      "Mixer Name"
    ],
    "songwriters": [
      "Songwriter Name"
    ]
  },
  "externalId": "EXT-12345",
  "extra": {
    "notes": "Recorded in Abbey Road Studios"
  },
  "metadata": {
    "releaseYear": 2011
  },
  "assetIDs": [
    "asset-1",
    "asset-2"
  ],
  "explicit": "clean",
  "label": "Royalti Records",
  "copyright": "© 2024 Royalti Records",
  "publisher": "Royalti Publishing",
  "copyrightOwner": "Royalti Music Group",
  "artists": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "primary"
    },
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "split": [
    {
      "user": "550e8400-e29b-41d4-a716-446655440002",
      "share": 60
    },
    {
      "user": "550e8400-e29b-41d4-a716-446655440003",
      "share": 40
    }
  ],
  "ddexMetadata": {
    "releaseType": "Single",
    "recordLabel": "Royalti Records"
  },
  "resourceReference": "SR123456789",
  "technicalResourceDetails": {
    "fileFormat": "WAV",
    "audioCodec": "PCM",
    "bitrate": 1411,
    "sampleRate": 44100,
    "duration": "PT3M45S"
  },
  "soundRecordingDetails": {
    "recordingDate": "2024-01-15",
    "recordingLocation": "Abbey Road Studios",
    "language": "en"
  },
  "musicalWorkReference": {
    "workId": "work-123",
    "iswc": "T-123456789-0"
  },
  "enableDDEX": false,
  "focusTrack": false,
  "danceStyle": [
    "Electronic Dance"
  ],
  "rhythmStyle": [
    "Upbeat"
  ],
  "instrumentation": [
    "Synthesizer",
    "Drums"
  ],
  "recordingLocation": "Abbey Road Studios",
  "recordingDate": "2024-01-15",
  "alternativeTitles": [
    "Alt Title 1",
    "Alt Title 2"
  ],
  "chartPositions": [
    {
      "chart": "Billboard Hot 100",
      "position": 10,
      "date": "2024-01-01"
    }
  ],
  "reviews": [
    {
      "reviewer": "Music Magazine",
      "rating": 4.5,
      "text": "Great track!"
    }
  ],
  "awards": [
    {
      "name": "Best Electronic Song",
      "year": 2024
    }
  ],
  "socialMediaHandles": {
    "twitter": "@artistname",
    "instagram": "@artistname"
  },
  "language": "en",
  "mood": [
    "Energetic",
    "Uplifting"
  ],
  "tempo": 128,
  "key": "C Major",
  "productionYear": 2024
}
'
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Example Song",
    "type": "Audio",
    "ddexMetadata": null,
    "focusTrack": false,
    "media": [],
    "explicit": null,
    "TenantId": 2,
    "mainArtist": [
      "M83",
      "M47"
    ],
    "displayArtist": "M83",
    "version": "Album Version",
    "mainGenre": [
      "Electronic",
      "Mental"
    ],
    "subGenre": [
      "Synthwave"
    ],
    "contributors": {
      "producers": [
        "string"
      ],
      "mixers": [
        "string"
      ]
    },
    "iswc": "T1234567890",
    "externalId": "string",
    "isrc": "USRC17607839",
    "updatedAt": "2025-08-21T11:42:29.827Z",
    "createdAt": "2025-08-21T11:42:29.827Z",
    "assetIDs": "null,",
    "otherArtist": "null,",
    "lyrics": "null,",
    "extra": "null,",
    "danceStyle": "null,",
    "rhythmStyle": "null,",
    "instrumentation": "null,",
    "recordingLocation": "null,",
    "recordingDate": "null,",
    "alternativeTitles": "null,",
    "chartPositions": "null,",
    "reviews": "null,",
    "awards": "null,",
    "socialMediaHandles": "null,",
    "language": "null,",
    "mood": "null,",
    "tempo": "null,",
    "key": "null,",
    "copyrightOwner": "null,",
    "productionYear": "null,",
    "metadata": null
  }
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

​
Description

Required Fields:
ParameterTypeDescription
title (Required)stringTitle of the asset
mainArtist (Required)arrayMain artist of the asset
displayArtist (Required)stringDisplay artist of the asset
type (Required)stringType of the asset (default: ‘Audio’)
Optional Fields:
ParameterTypeDescription
id (Optional)stringID of the asset
otherArtist (Optional)arrayOther artist of the asset
version (Optional)stringVersion of the asset
lyrics (Optional)stringLyrics of the asset
mainGenre (Optional)arrayMain genre of the asset
subGenre (Optional)arraySub genre of the asset
contributors (Optional)objectContributors of the asset
iswc (Optional)stringISWC of the asset
isrc (Optional))stringISRC of the asset
externalId (Optional)stringExternal ID of the asset
extra (Optional)objectExtra information of the asset
metadata (Optional)objectMetadata of the asset
assetIDs (Optional)arrayAsset IDs of the asset
explicit (Optional)booleanExplicit content of the asset
DDEX Fields:
ParameterTypeDescription
ddexMetadata (Optional)objectDDEX metadata of the asset
resourceReference (Optional)stringResource reference of the asset
technicalResourceDetails (Optional)objectTechnical resource details of the asset
soundRecordingDetails (Optional)objectSound recording details of the asset
musicalWorkReference (Optional)objectMusical work reference of the asset
Other Fields:
ParameterTypeDescription
artists (Optional)arrayArtists of the asset
split (Optional)arraySplits of the asset
Asset will be created with an ISRC which can be provided or auto-generated based on tenant settings.

​
Code Examples

const response = await fetch('https://api.royalti.io/asset', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "ref": "#/components/schemas/Asset"
  })
});

const data = await response.json();
console.log(data);

Authorizations

​
Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Body

application/json
​
title
string
required

Title of the asset

Example:

"Midnight City"

​
mainArtist
string[]
required

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
string
required

Display name for the lead artist (single string representation)

Maximum string length: 510
Example:

"M83"

​
id
string<uuid>

Pre-generated UUID (optional, rarely used)

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
otherArtist
string[]

Featured artist name(s) in the asset (display purposes). These are artist NAMES (strings), not UUIDs.

Example:
["Featured Artist"]
​
type
enum<string>
default:Audio

Type of asset

Available options:
Audio,
Video,
Ringtone,
YouTube
Example:

"Audio"

​
version
string

Version of the asset (e.g., Remix, Live Version)

Example:

"Album Version"

​
isrc
string

International Standard Recording Code (auto-generated if not provided)

Example:

"USRC17607839"

​
iswc
string

International Standard Musical Work Code

Example:

"T-123456789-0"

​
lyrics
string

Lyrics of the asset

Example:

"Waiting in a car..."

​
mainGenre
string[]

Main genre(s) of the asset

Example:
["Electronic", "Synthpop"]
​
subGenre
string[]

Sub-genre(s) of the asset

Example:
["Synthwave"]
​
contributors
object

Contributors to the asset (producers, mixers, songwriters, etc.)

Example:
{
  "producers": ["Producer Name"],
  "mixers": ["Mixer Name"],
  "songwriters": ["Songwriter Name"]
}
​
externalId
string

External identifier for the asset

Example:

"EXT-12345"

​
extra
object

Additional metadata about the asset

Example:
{ "notes": "Recorded in Abbey Road Studios" }
​
metadata
object

General metadata for the asset

Example:
{ "releaseYear": 2011 }
​
assetIDs
string[]

Array of individual asset IDs (for album assets)

Example:
["asset-1", "asset-2"]
​
explicit
enum<string>

Explicit content flag

Available options:
explicit,
clean
Example:

"clean"

​
label
string

Record label

Example:

"Royalti Records"

​
copyright
string

Copyright information

Example:

"© 2024 Royalti Records"

​
publisher
string

Publisher name

Example:

"Royalti Publishing"

​
copyrightOwner
string

Copyright owner name

Example:

"Royalti Music Group"

​
artists
(string<uuid> | object)[]

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"}]

Artist UUID (defaults to type 'primary')

Example:
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "primary"
  },
  "660e8400-e29b-41d4-a716-446655440001"
]
​
split
object[]

Revenue split configuration (must total 100%)

Example:
[
  {
    "user": "550e8400-e29b-41d4-a716-446655440002",
    "share": 60
  },
  {
    "user": "550e8400-e29b-41d4-a716-446655440003",
    "share": 40
  }
]
​
ddexMetadata
object

DDEX-specific metadata

Example:
{
  "releaseType": "Single",
  "recordLabel": "Royalti Records"
}
​
resourceReference
string

DDEX resource reference (auto-generated if DDEX enabled but not provided)

Example:

"SR123456789"

​
technicalResourceDetails
object

Technical details of the resource

​
soundRecordingDetails
object

Sound recording specific details

​
musicalWorkReference
object

Musical work reference information

​
enableDDEX
boolean

Enable DDEX for this asset

Example:

false

​
focusTrack
boolean
default:false

Whether this is a focus track for MEAD

Example:

false

​
danceStyle
string[]

Dance style(s) for MEAD

Example:
["Electronic Dance"]
​
rhythmStyle
string[]

Rhythm style(s) for MEAD

Example:
["Upbeat"]
​
instrumentation
string[]

Instrumentation for MEAD

Example:
["Synthesizer", "Drums"]
​
recordingLocation
string

Recording location

Maximum string length: 255
Example:

"Abbey Road Studios"

​
recordingDate
string<date>

Recording date

Example:

"2024-01-15"

​
alternativeTitles
string[]

Alternative titles for the asset

Example:
["Alt Title 1", "Alt Title 2"]
​
chartPositions
object[]

Chart positions

Example:
[
  {
    "chart": "Billboard Hot 100",
    "position": 10,
    "date": "2024-01-01"
  }
]
​
reviews
object[]

Reviews of the asset

Example:
[
  {
    "reviewer": "Music Magazine",
    "rating": 4.5,
    "text": "Great track!"
  }
]
​
awards
object[]

Awards received

Example:
[
  {
    "name": "Best Electronic Song",
    "year": 2024
  }
]
​
socialMediaHandles
object

Social media handles

Example:
{
  "twitter": "@artistname",
  "instagram": "@artistname"
}
​
language
string

Language of the asset

Example:

"en"

​
mood
string[]

Mood of the asset

Example:
["Energetic", "Uplifting"]
​
tempo
number

Tempo in BPM

Example:

128

​
key
string

Musical key

Example:

"C Major"

​
productionYear
integer

Year of production

Example:

2024

Response

Asset created successfully

​
success
boolean
Example:

true

​
message
string
​
data
object