A release is an album, EP, or single. Releases contain one or more tracks and various metadata. Use the /content/release/save
resource to create or edit releases. Specifically, this resource enables you to do the following:
Unless otherwise stated, the Revelator API does not support partial updates. When editing an object, the existing values of any omitted parameters will be deleted or overwritten, according to the designated behavior for a null value for that parameter. Consequently, we recommend you always query the object you want to edit and modify the JSON object to avoid partial update problems.
/content/release/save
Parameter | Type | Description |
---|---|---|
name required | string | Title of the Release.
|
releaseId optional | integer | ID for the existing release you want to edit. This ID was returned in the response when the release was created.
|
artistName optional | string | Name of the release’s primary artist/band.
|
artistId optional | integer | ID for an existing artist to assign as the primary artist for the release.
|
releasesLocals required | array of objects | Release name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the release name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules). Parameter is mandatory even if the array is empty.
|
releasesLocals.name required | string | Name in the indicated language. |
releasesLocals.version optional | string | Version in the indicated language. |
releasesLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
contributors required | array of objects | Additional key artists who should be given top level credit. Do not provide individual band member names. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr.
|
contributors.contributorId optional | GUID | ID for an existing contributor.
|
contributors.roleId required | integer | The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles .
|
contributors.artist required | object | The contributing artist. Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer do not require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional). See Artist Object |
version optional | string | Title version. For example, Remastered or Deluxe edition. Typically omitted unless the release is a new version of a previously released release. |
copyrightP required | string | The product copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The product copyright holder is the person or entity that owns the exclusive rights to the complete product, including both sound recording and artwork. |
copyrightC required | string | The sound recording copyright holder preceded by the year the rights were obtained. For example: 2008 Acme Inc. The sound recording copyright holder is the person or entity that owns the exclusive rights to the sound recording. |
hasRecordLabel optional | boolean |
|
labelName optional | string |
|
labelId optional | integer | ID for an existing label to assign to the release.
|
artistAppleId required | string | One of the following:
|
artistSpotifyId required | string | One of the following:
|
previouslyReleased optional | boolean |
|
upc optional | integer | UPC/EAN/JAN code for the release.
|
releaseDate optional | string | Official date the release was previously released in the format “mm/dd/yyyy”.
|
primaryMusicStyleId required | integer | ID for the release’s primary music style. Lookup music style IDs using the GET /common/lookup/musicstyles resource. |
languageId required | integer | Language ID for the release’s meta data. This is not the language of the songs/lyrics, but the language of the information provided in this API request. Lookup up the languageId using the GET /common/lookup/languages resource. English is 1. |
tracks required | array of objects | Tracks for the release.
|
image optional | object | Cover image for the release.
|
curl -X POST 'http://staging-api.revelator.com/content/release/save'\
-H 'Content-Type: application/json'\
-H 'Accept: application/json'\
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4'\
-d '{ "artistName":"Release_artist",
"contributors": [],
"copyrightC": "2018 companyC",
"copyrightP": "2018 companyP",
"hasRecordLabel": false,
"previouslyReleased": false,
"languageId": 1,
"name": "Single",
"primaryMusicStyleId": 60,
"releasesLocals": [],
"image": {
"fileId": "00000000-0000-0000-0000-000000000000",
"filename": "file123.jpg"
},
"tracks": [ {"artistName": "TRACK_ARTIST",
"languageId": 1,
"name":"Single",
"explicit": false,
# "trackType": 1,
"wav": { "filename":"file123.wav",
"fileId": "00000000-0000-0000-0000-000000000000" },
"trackLength": 267,
"sampleRate": 44100,
"composerContentsDTO":[{ "composerName": "John Doe",
"rightsId": 1,
"roleId": 2,
"share":100 }]}
]
}'
Parameter | Type | Description |
---|---|---|
name optional | string | Name of the artist.
|
artistId optional | integer | ID for an existing artist.
|
artistExternalIds optional* | array of objects | External IDs for the artist. *For distribution, mandatory for all artists named as a main artist and all artists named as a contributor with the role Primary Artist, Featuring, or Remixer. When this parameter is mandatory, this array must include an object for every supported store.
|
artistExternalIds.profileId required | string | One of the following:
|
artistExternalIds.distributorStoreId required | string | Revelator ID for the store. Currently supported for:
|
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
Parameter | Type | Description |
---|---|---|
filename required | string | Name of the file, including the extension. |
fileId required | string | The ID for a file that has already been uploaded to the Revelator server. See Uploading Files |
Used within the trackRecordingVersions.audioFiles
array.
Parameter | Type | Description |
---|---|---|
audioId required | string | The ID for a file that has already been uploaded to the Revelator server. See Uploading Files |
audioFilename required | string | Name of the audio file, including the extension. |
fileFormat required | string |
|
Parameter | Type | Description |
---|---|---|
name optional | string | Title of the track.
|
trackId optional | integer | ID for an existing track you want to assign to the release. This ID was returned in the response when the track was created. Note that you should not use the same trackId on more than one release. You should only provide an existing trackId in a case where you are editing an existing release or assigning a track that is not yet assigned to any release. In a case where the same track (same ISRC) is used on more than one release, you should create the track as new for the second release (generate a new trackId).
|
artistName optional | string | Name of the track’s primary artist/band.
|
artistId optional | integer | ID for an existing artist to assign as the primary artist for the track.
|
tracksLocals optional | array of objects | Track name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the track name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
tracksLocals.name required | string | Name in the indicated language. |
tracksLocals.version optional | string | Version in the indicated language. |
tracksLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
artistLocals.name required | string | Name in the indicated language. |
artistLocals.languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
contributors optional | array of objects | Additional key artists who should be given top level credit. Do not provide individual band member names. For example, “The Beatles” and, not John Lennon, Paul McCartney, George Harrison and Ringo Starr.
|
contributors.contributorId optional | GUID | ID for an existing contributor.
|
contributors.roleId required | integer | The artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles .
|
contributors.artist required | object | The contributing artist. Unlike all other artists in Revelator, contributing artists with any role other than Primary Artist, Featuring, or Remixer do not require external artist IDs. In other words, contributing artists with the roles Primary Artist, Featuring, or Remixer require Apple and Spotify IDs (same as primary artists); contributing artists with other roles do not require these IDs (they are optional). See Artist Object |
languageId required | integer | Language ID for the track’s lyrics. Lookup up the languageId using the GET /common/lookup/languages endpoint . English is 1. |
version optional | string | Version of the track. For example, Remix or Bonus Track. |
explicit required | boolean | Be sure that your user interface indicates the importance of properly identifying this content. Misidentifying this content can result in your distribution being disabled. Should be true when the song contains any of the following:
|
trackType required | integer | One of the following:
|
trackProperties required | array of integers | One or multiple of the following:
|
artistAppleId required | string | One of the following:
|
artistSpotifyId required | string | One of the following:
|
composerContentsDTO required | array of objects | A list of publishing contributors(composers) for the track . |
composerContentsDTO.composerName optional | string | Name of the composer.
|
composerContentsDTO.composerId optional | integer | ID for an existing composer to assign to the track.
|
composerContentsDTO.rightsId required | integer | Publishing type. One of the following:
|
composerContentsDTO.roleId required | integer | A role associated with the composer. Look up roleIds with GET /common/lookup/contributorRoles . Only roles with priority 5 are relevant for composers. |
composerContentsDTO.share optional | string | Share percentage for the composer. The total percentage for all composers must be 100%. Note that this has nothing to do with contract splits, and publisher royalties are never paid through the Revelator platform. |
composerContentsDTO.publisherName optional | string | Name of the publisher to assign to the composer.
|
composerContentsDTO.publisherId optional* | integer | ID for an existing publisher to assign to the composer.
publisherId to 0 (along with providing a publisherName) to create a new publisher whenever no existing publisher with the provided name exists. Omitting this parameter will cause the publisher (name and ID) to be null. |
lyrics optional | string | Lyrics for the track. Note that not all stores accept lyrics. |
isrc optional | string | This field is part of the old Track Recording model. See New track recording model for more information. ISRC code for the track. Hyphens and spaces will be automatically removed, and letters will be automatically capitalized.
|
wav optional | object | This field is part of the old Track Recording model. See New track recording model for more information. Audio file for the track in WAV format.
|
trackRecordingVersions optional | array of objects | This field is part of the new Track Recording model. See New track recording model for more information. If provided, this list needs to have
|
trackRecordingVersions.recordingVersionType required | integer | Type of the track version.
|
trackRecordingVersions.isrc required | string | A valid ISRC code for the track version.
null if the ISRC should be generated automatically (during distribution). |
trackRecordingVersions.audioFiles required | array of objects | When creating a new track, this array must contain a single object with a WAV (1 ) or a FLAC (2 ) fileFormat .
When editing an existing track:
|
With the release of support for Dolby Atmos, we have updated the track object adequately. The old model is going to remain supported with the goal of backwards compatibility; however, we strongly advise adapting to this new model (even if not utilizing Dolby Atmos).
New model (Supports Dolby Atmos)
Track object includes the following properties:
trackRecordingVersions[]
isrc
recordingVersionType
trackRecordingVersions.audioFiles[]
audioFiles.audioId
audioFiles.audioFilename
audioFiles.fileFormat
Old model (Does not support Dolby Atmos)
Track object includes the following properties:
isrc
wav
or flac
Only one of the two models should be used, failiure to do so will result in an error.
Refer to the track object table for coprehensive information on these fields
All files must be uploaded before being associated with a track or a release, This goes for both audio and image assets.
/media/audio/upload/wav
A recent change requires all audio files to be longer than 2 seconds. Invalid audio files will be rejected.
Content-type for this request must be multipart/form-data
Form Field | Type | Description |
---|---|---|
file required | binary | The audio file to upload |
Field | Type | Description |
---|---|---|
fileId | string | The ID of the uploaded file that’s going to be used to reference it across the application. |
filename | string | The filename of the uploaded file. |
/media/image/upload
Content-type for this request must be multipart/form-data
Parameter | Type | Description |
---|---|---|
cover optional | boolean | Is the image going to be used as a cover art |
Form Field | Type | Description |
---|---|---|
file required | binary | The image file to upload |
fileId - string |
/media/audio/pullexternal/wav
An alternative way to upload files. As long as those are publicly available on the web.
This might prove useful if you don’t want to handle the file upload yourself or already have the asset uploaded and accessible elsewhere.
A recent change requires all audio files to be longer than 2 seconds. Invalid audio files will be rejected.
You can use expiring links as a measure of security, as long as the file is accessible within the timeframe when this endpoint is invoked.
Parameter | Type | Description |
---|---|---|
externalUrl required | string | A valid URL to a publicly available audio file. |
filename required | string | The name of the file |
Field | Type | Description |
---|---|---|
fileId | string | The ID of the uploaded file that’s going to be used to reference it across the application. |
filename | string | The filename of the uploaded file. |
Use the following endpoints to retrieve release data.
By default, these endpoints will return all releases the user has permissions to view, not just the releases in the user’s account. A parent account user will receive all releases in every child.
/content/release/all
Retrieves list of all releases the user has permissions to view.
/content/release/all/summary
Retrieves a summary of all releases the user has permissions to view.
/content/release/{releaseId}
Retrieves the release with the releaseId
specified in the URL path.
An artist is a metadata entity that is referenced in assets (releases and tracks).
Due to DSP requirements, an artist cannot be listed as a primary artist twice, or listed as both a primary artist and a featuring artist on the same track or release.
The Revelator API prohibits this scenario with an error message when attempting to set an artist as both the main primary artist (indicated with the artistId
and artistName
) as well as a contributor with the role of primary or featuring.
/artists
Creates new or edits existing artists in the account associated with the access token.
For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.
Parameter | Type | Description |
---|---|---|
name optional | string | Name of the artist.
|
artistId optional | integer | ID for an existing artist.
|
artistExternalIds optional* | array of objects | External IDs for the artist. *For distribution, mandatory for all artists named as a main artist and all artists named as a contributor with the role Primary Artist, Featuring, or Remixer. When this parameter is mandatory, this array must include an object for every supported store.
|
artistExternalIds.profileId required | string | One of the following:
|
artistExternalIds.distributorStoreId required | integer | Revelator ID for the store. Currently supported for:
|
artistLocals optional | array of objects | Artist name in different languages. Only relevant if listeners may search for the release in a different language. For example, if you provided the artist name in Japanese, you may want to additionally provide the name in Latin characters. You can translate the name or provide it phonetically (no rules).
|
name required | string | Name in the indicated language. |
languageId required | integer | Language ID indicating the language of the name. Each language can be used only once in the array. Lookup up the languageId using the GET /common/lookup/languages resource. |
image optional | object | The image representing the artist. See File Object. |
Use the following endpoints to retrieve artist data.
For Child Account implementation models, you have the option to run requests in a child account while authenticated as a parent account user. See Running Requests in Child Accounts.
/artists
Retrieves list of all artists in the account.
curl -X GET -H 'Accept: text/plain'\
'http://staging-api.revelator.com/artists?labels=labelA&labels=labelB'
/artists/summary
Retrieves a summary of all artists in the account.
/artists/{artistId}
Retrieves the artist with the artistId
specified in the URL path.
Parameter | Type | Description |
---|---|---|
labels | array | One or more labels associated with artists |
name | string | Name of artist |
Some DSPs share their artist IDs with us, allowing us to tightly couple our artists with theirs. This enables us to avoid situations where two different artists with the same name are merged or a single artist’s catalog is split between two or more profiles.
If an artist is already on the DSP, we require you to provide this ID when creating releases for the artist. If an artist is not already on the DSP, we require you to indicate that we should generate an ID for the artist when (if ever) the artist is distributed to the DSP.
Distributing additional releases for artists with new IDs
You must retrieve newly generated IDs immediately before distributing additional releases for an artist.
If the ID for the artist has already been generated, but you continue to indicate that a new ID should be generated, you will delete the ID from the Revelator system and may cause a second ID to be generated for the artist!
artistId
parameter in the new release to ensure that the same Revelator artist is being assigned./content/artist/all
or GET /content/artist/{Id}
endpoint. The response will include the profileId
for each DSP. See Artist Object.
profileId
is still 0, the ID for the artist has not yet been generated.profileId
is >0, this is the generated ID.Do not continuously poll our system for the ID. Only run the GET request immediately before distributing a new release which requires the ID. There are many reasons that an ID may never be generated (for example, when a Spotify release does not ultimately go live).
Different DSPs generate new IDs at different times in the distribution process:
Specify the current values for the external IDs in the release metadata.
If the ID is still 0, the correct ID will be assigned to the artist (and on all releases for the artist) as soon as it is available.
Distribute the new release.