Skip to main content
POST
/
releases
Create Release
curl --request POST \
  --url https://api.royalti.io/releases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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\nChorus\nVerse 2\nChorus\nBridge\nChorus",
      "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
    }
  ]
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "TenantId": "<string>",
    "TenantUserId": "<string>",
    "title": "<string>",
    "displayArtist": "<string>",
    "artists": [
      {
        "id": "3816be64-720c-4105-990f-a6b99b0f928b",
        "artistName": "Bally Jhay",
        "type": "primary"
      }
    ],
    "tracks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "TenantId": 123,
        "ReleaseId": "660e8400-e29b-41d4-a716-446655441111",
        "assetId": "770e8400-e29b-41d4-a716-446655442222",
        "trackNumber": 1,
        "title": "My Track Title",
        "version": "Radio Edit",
        "isrc": "USABC1234567",
        "iswc": "T-123456789-0",
        "duration": 213.5,
        "lyrics": "Verse 1\nChorus\nVerse 2",
        "language": "en",
        "displayArtist": "Artist Name",
        "artists": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "artistName": "John Doe",
            "type": "primary"
          },
          {
            "id": "660e8400-e29b-41d4-a716-446655441111",
            "artistName": "Jane Smith",
            "type": "featuring"
          }
        ],
        "mainGenre": [
          "Pop",
          "Rock"
        ],
        "subGenre": [
          "Alternative"
        ],
        "contributors": {
          "producer": [
            "Producer Name"
          ],
          "songwriter": [
            "Writer Name"
          ]
        },
        "media": [
          {
            "cloudId": "550e8400-e29b-41d4-a716-446655440000",
            "cloudUrl": "https://storage.royalti.io/files/audio.mp3",
            "type": "audio",
            "name": "my-track.mp3",
            "isLink": false,
            "releasePath": "tenant123/releases/release456/tracks/track789/file.mp3",
            "metadata": {
              "duration": 213.5,
              "bitrate": "320",
              "sampleRate": "44100",
              "channels": "2",
              "codec": "mp3",
              "fileSize": 1048576,
              "mimeType": "audio/mpeg",
              "processedAt": "2023-11-07T05:31:56Z",
              "linkValidated": true
            }
          }
        ],
        "metadata": {
          "bpm": 120,
          "key": "C Major"
        },
        "explicit": false
      }
    ],
    "format": "Single",
    "type": "Audio",
    "version": "<string>",
    "label": "<string>",
    "copyright": "<string>",
    "mainGenre": [
      "<string>"
    ],
    "subGenre": [
      "<string>"
    ],
    "contributors": [
      "<string>"
    ],
    "description": "<string>",
    "metadata": {},
    "media": [
      {}
    ],
    "releaseDate": "2023-11-07T05:31:56Z",
    "preReleaseDate": "2023-11-07T05:31:56Z",
    "status": "<string>",
    "autoCreationError": "<string>",
    "createdProductId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAssetIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "owner": {
      "id": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "<string>"
    }
  }
}
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
fieldtypedescription
titlestringThe title of the release
formatstringFormat of the release (Single, EP, Album, etc.)
typestringType of release (Audio, Video, Mixed)
versionstringVersion of the release
labelstringRecord label
copyrightstringCopyright information
displayArtiststringThe display artist name
artistsobjectArtists and their roles (must include at least one primary artist)
mainGenrearrayMain genres
subGenrearraySub-genres
contributorsobjectContributors and their roles
descriptionstringDescription of the release
metadataobjectAdditional metadata
mediaarrayArray of media files
explicitstringContent rating: ‘explicit’, ‘clean’, or null
releaseDatestringRelease date
preReleaseDatestringPre-release date
tracksarrayArray of tracks
ownerIdstringOptional: specify a different owner

​
Code Examples

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);

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
title
string
required

The title of the release

​
displayArtist
string
required

The display artist name

​
artists
object
required

Artists and their roles (must include at least one primary artist)

​
tracks
object[]
required

Array of tracks in the release

​
format
enum<string>
default:Single

Format of the release

Available options:
Single,
EP,
Album,
LP,
Video
​
type
enum<string>
default:Audio

Type of release

Available options:
Audio,
Video
​
version
string

Version of the release

​
label
string

Record label

​
copyright
string

Copyright information

​
mainGenre
string[]

Main genres of the release

​
subGenre
string[]

Sub-genres of the release

​
contributors
object

Contributors and their roles

​
description
string

Description of the release

​
metadata
object

Additional metadata

​
media
object[]
​
explicit
enum<string> | null

Content rating: explicit, clean, or null (not specified)

Available options:
explicit,
clean
​
ownerId
string<uuid> | null

Optional: UUID of the user who will own the release (admin/owner only)

Example:

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

​
releaseDate
string<date>

Release date

​
preReleaseDate
string<date>

Pre-release date

Response

Success - Release created

​
success
boolean
Example:

true

​
data
object