Catalog Management

Catalog management

Adding/Editing Releases

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:

  • Manage release metadata, including uploading relevant files
  • Create new tracks and assign them to the release
  • Assign existing tracks to a release, with or without editing them 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.

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.

POST /content/release/save

Request Body

ParameterTypeDescription
name
required
stringTitle of the Release.
  • Required for new releases.
  • When provided with an existing releaseId, updates the name of the release.
releaseId
optional
integerID for the existing release you want to edit. This ID was returned in the response when the release was created.
  • When set to 0, creates a new release. (Default)
  • Inline with the general behavior of this API, patching is not supported. Existing values for omitted parameters will be deleted or overwritten.
artistName
optional
stringName of the release’s primary artist/band.
  • Should be only the name of oneartist.
    • The artist named in this parameter will be the only artist named for the release in contracts and analytics.
    • Additional artists should be named as contributors. If there is more than one primary artist, additional primary artist should be listed as contributors with the role Primary Artist.
  • When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist.
  • When provided with an artistId, the artistName is ignored. The artist associated with the artistId will be assigned to the release and the name of the artist will not be updated.
  • Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations.
  • All artists in child enterprises automatically appear in the parent enterprise.
artistId
optional
integerID for an existing artist to assign as the primary artist for the release.
  • Should be omitted for compilations. Otherwise, either an artistName or artistId must be provided. If neither are provided, the artist will be null, and this is only valid for compilations.
releasesLocals
required
array of objectsRelease 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.
  • Parameter is mandatory even if the array is empty.
  • Each object in the array represents the name in a different language.
  • If name or languageId are omitted, the object will be ignored.
releasesLocals.name
required
stringName in the indicated language.
releasesLocals.version
optional
stringVersion in the indicated language.
releasesLocals.languageId
required
integerLanguage 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 objectsArtist 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).
  • Each object in the array represents the name in a different language
artistLocals.name
required
stringName in the indicated language.
artistLocals.languageId
required
integerLanguage 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 objectsAdditional 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.
  • Parameter is mandatory even if the array is empty.
  • Each object in the array represents a contributor.
  • Legacy contributors: Prior to July 2021, contributors were not added as artists. The contributor object included a name parameter and did not include an artist object. The name parameter directly in the contributor object is deprecated, and should never be used for new contributors. When editing an existing release with legacy contributors, we recommend prompting users for the data required by the artist object and providing the contributor object according to the current standard.
contributors.contributorId
optional
GUIDID for an existing contributor.
  • Not relevant for new releases. Should be provided when editing existing releases.
contributors.roleId
required
integerThe artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles.
  • The “primary artist” role (roleId 49) should only be used to name additional primary artists. The first (or only) primary artist should only be indicated as the main artist with the artistName parameter.
  • Any role with priority 5 should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. Priority 5 indicates the role is a publishing role, which should be provided provided per track in the composerContentsDTO array.
  • It is strongly encouraged to use a reduced set of contributor roles, such as those visible in the Revelator web interface. Many users will be tempted to add extraneous roles which will result in the release being rejected by top tier DSPs.
contributors.artist
required
objectThe 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
stringTitle version. For example, Remastered or Deluxe edition.
Typically omitted unless the release is a new version of a previously released release.
copyrightP
required
stringThe 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
stringThe 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
  • true - The release has a record label. (See additional required parameters below).
  • false - The release does not have a record label. (Default)
    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.
    • If the primary artist for the release is new or is an existing artist not associated with a label, a new label will be created and assigned to the release with the same name as the artist.
labelName
optional
string
  • Should never be provided when hasRecordLabel is false.
  • When provided without labelId, tries to find an existing label with the same name (case-insensitive). If no such label is found, creates a new label and assigns it to the release.
  • When provided with labelId, the labelName is ignored. The label associated with the labelId will be assigned to the release and the name of the label will not be updated.
  • If neither a labelId nor a labelName are provided and hasRecordLabel is true:
    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.
    • If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.
labelId
optional
integerID for an existing label to assign to the release.
  • Should never be provided when hasRecordLabel is false.
  • If neither a labelId nor a labelName are provided and hasRecordLabel is true:
    • If the primary artist for the release is an existing artist associated with a label, that label is assigned to the release.
    • If the primary artist for the release is new or is an existing artist not associated with a label, throws an exception.
artistAppleId
required
stringOne of the following:
  • For artists already on Apple Music, existing Apple ID for the artist.
    To find this ID, go to your Apple Music artist page, and copy-paste the numeric part of the URL. Example 1249595
  • For artists not already on Apple Music, 0.
    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
artistSpotifyId
required
stringOne of the following:
  • For artists already on Spotify, existing Spotify ID for the artist.
    To find this ID, go to your Spotify artist page, and copy-paste the numeric part of the URL. Example: 22bE4uQ6baNwSHPVcDxLCe
  • For artists not already on Spotify, 0.
    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
previouslyReleased
optional
boolean
  • true - The release has been released previously to being added to the Revelator system.
    • When true, upc and releaseDate are required parameters.
    • You should not manually update this parameter after distributing the release in the Revelator system.
  • false - The release has not been released previously. (Default)
upc
optional
integerUPC/EAN/JAN code for the release.
  • The UPC is a unique code that every release must have. The system will automatically generate one upon distribution (free of charge) if you omit this parameter. You should never generate a new UPC for a release that already has one.
  • Required when previouslyReleased is true.
releaseDate
optional
stringOfficial date the release was previously released in the format “mm/dd/yyyy”.
  • Required when previouslyReleased is true; otherwise should not be provided.
  • When distributing the release with the Revelator system, you should not manually update this parameter; you should only set the saleStartDate parameter in the distribution options endpoint. See Setting Distribution Options.
primaryMusicStyleId
required
integerID for the release’s primary music style.
Lookup music style IDs using the GET /common/lookup/musicstyles resource.
languageId
required
integerLanguage 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 objectsTracks for the release.
  • Each object in the array represents a track.
  • Unlike the behavior for most parameters, completely omitting the tracks parameter when editing an existing release will not remove all existing tracks from the release.
  • Although tracks are not required when creating a release, they are required to distribute the release.
See Track Object.
image
optional
objectCover image for the release.
  • Although a cover image is not required when creating a release, it is required to distribute the release.
  • Stores and services will reject images that do not conform to the following standards:
    • Technical specifications:
      • File format must be JPG
      • Color space must be RGB
      • Minimum dimensions of 1400x1400 pixels; 3000x3000 pixels recommended
      • Must be a square image (width and height the same)
      • May not contain more than 50 megapixels or be larger than 10 Mb
      • Cannot be stretched, upscaled, or appear to be low-resolution
    • Content:
      • Information must match album title and artist name
      • No website addresses, social media links or contact information
      • No sexually explicit imagery
      • Cannot be misleading by figuring a different artist’s name more prominently
      • No third-party logo or trademarks without express written permission from the trademark holder
  • In line with the general behavior of this API, patching is not supported. When editing an existing release associated with an existing file, you must include this object (with the existing fileId and fileName) to prevent the file from being deleted.
See File Object.

Example

Request
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 }]} 
              ] 
     }'

Artist Object

ParameterTypeDescription
name
optional
stringName of the artist.
  • When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist.
  • When provided with an artistId, updates the name of the artist.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
  • All artists in child enterprises automatically appear in the parent enterprise.
artistId
optional
integerID for an existing artist.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
artistExternalIds
optional*
array of objectsExternal 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.
  • These IDs are used by the stores to make sure that all of an artist’s content stays together. For artists who have not yet distributed to a specific store, we will generate a new ID if/when a release for the artist is distributed to the store.
  • Each object in the array represents an external ID for the artist at a specific store.
artistExternalIds.profileId
required
stringOne of the following:
  • For an artist already on the store, external ID for the artist at the specified store.
  • To find this ID go to the artist’s page at the store, and copy-paste the numeric part of the URL
  • For artists not already on the store, 0.
  • This indicates we should generate an ID for the artist if/when a release for the artist is distributed to the store.
  • This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
artistExternalIds.distributorStoreId
required
stringRevelator ID for the store.
Currently supported for:
  • Apple Music - 1
  • Spotify - 9
artistLocals
optional
array of objectsArtist 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).
  • Each object in the array represents the name in a different language
artistLocals.name
required
stringName in the indicated language.
artistLocals.languageId
required
integerLanguage 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.

File Object

ParameterTypeDescription
filename
required
stringName of the file, including the extension.
fileId
required
stringThe ID for a file that has already been uploaded to the Revelator server.
See Uploading Files

Audio File Object

Used within the trackRecordingVersions.audioFiles array.

ParameterTypeDescription
audioId
required
stringThe ID for a file that has already been uploaded to the Revelator server.
See Uploading Files
audioFilename
required
stringName of the audio file, including the extension.
fileFormat
required
string
  • 1 - WAV
  • 2 - FLAC
  • 3 - MP3

Track Object

ParameterTypeDescription
name
optional
stringTitle of the track.
  • Required for new tracks.
  • When provided with an existing trackId, updates the name of the track.
  • Do not include additional information, like “Remix” or “Uncut”. This should be specified in the version.
trackId
optional
integerID 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).
  • When set to 0, creates a new track. (Default)
  • In line with the general behavior of this API, patching is not supported. When assigning an existing track to a release, the track will be updated according to the data provided; any existing values for omitted parameters will be deleted.
artistName
optional
stringName of the track’s primary artist/band.
  • Should be only the name of oneartist.
    • The artist named in this parameter will be the only artist named for the release in contracts and analytics.
    • Additional artists should be named as contributors. If there is more than one primary artist, additional primary artist should be listed as contributors with the role Primary Artist.
  • When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist.
  • When provided with an artistId, the artistName is ignored. The artist associated with the artistId will be assigned to the release and the name of the artist will not be updated.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
  • All artists in child enterprises automatically appear in the parent enterprise.
artistId
optional
integerID for an existing artist to assign as the primary artist for the track.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
tracksLocals
optional
array of objectsTrack 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).
  • Each object in the array represents the name in a different language.
  • If name or languageId are omitted, the object will be ignored.
tracksLocals.name
required
stringName in the indicated language.
tracksLocals.version
optional
stringVersion in the indicated language.
tracksLocals.languageId
required
integerLanguage 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 objectsArtist 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).
  • Each object in the array represents the name in a different language
artistLocals.name
required
stringName in the indicated language.
artistLocals.languageId
required
integerLanguage 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 objectsAdditional 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.
  • Each object in the array represents a contributor.
  • Legacy contributors: Prior to July 2021, contributors were not added as artists. The contributor object included a name parameter and did not include an artist object. The name parameter directly in the contributor object is deprecated, and should never be used for new contributors. When editing an existing release with legacy contributors, we recommend prompting users for the data required by the artist object and providing the contributor object according to the current standard.
contributors.contributorId
optional
GUIDID for an existing contributor.
  • Not relevant for new releases. Should be provided when editing existing releases.
contributors.roleId
required
integerThe artist’s role as a contributor. Look up roleIds with GET /common/lookup/contributorRoles.
  • The “primary artist” role (roleId 49) should only be used to name additional primary artists. The first (or only) primary artist should only be indicated as the main artist with the artistName parameter.
  • Any role with priority 5 should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. Priority 5 indicates the role is a publishing role, which should be provided provided per track in the composerContentsDTO array.
  • It is strongly encouraged to use a reduced set of contributor roles, such as those visible in the Revelator web interface. Many users will be tempted to add extraneous roles which will result in the release being rejected by top tier DSPs.
contributors.artist
required
objectThe 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
integerLanguage ID for the track’s lyrics.
Lookup up the languageId using the GET /common/lookup/languages endpoint. English is 1.
version
optional
stringVersion of the track. For example, Remix or Bonus Track.
explicit
required
booleanBe 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:
  • Anything unsuitable for children
  • Strong language
  • References to violence or abuse
  • Sexual content
  • Anything that might be regarded as racist, homophobic, discriminatory or misogynistic
  • Anything that encourages or celebrates criminal behavior
trackType
required
integerOne of the following:
  • 1 - Original song
  • 2 - Cover song
  • 3 - Public domain song
For detailed information, see Track Origin & Track Properties.
trackProperties
required
array of integersOne or multiple of the following:
  • 1 - None (If included, no other value should be provided)
  • 2 - Remix
  • 3 - Samples or Stock
  • 4 - Mix or Compilation
  • 5 - Alternate version
  • 6 - Special Genre
  • 7 - Non-Musical Content
  • 8 - Includes AI
For detailed information, see Track Origin & TrackProperties.
artistAppleId
required
stringOne of the following:
  • For artists already on Apple Music, existing Apple ID for the artist. To find this ID, go to your Apple Music artist page, and copy-paste the numeric part of the URL. Example 1249595
  • For artists not already on Apple Music, 0.
    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
artistSpotifyId
required
stringOne of the following:
  • For artists already on Spotify, existing Apple ID for the artist. To find this ID, go to your Spotify artist page, and copy-paste the numeric part of the URL. Example 22bE4uQ6baNwSHPVcDxLCe
  • For artists not already on Spotify, 0.
    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
composerContentsDTO
required
array of objectsA list of publishing contributors(composers) for the track .
composerContentsDTO.composerName
optional
stringName of the composer.
  • When provided without composerId, tries to find an existing composer with the same name (case-insensitive). If no such composer is found, creates a new composer and assigns it to the track.
  • When provided with composerId, the name of the existing composer will be updated.
  • When no composerId nor composerName is provided, the entire object in the composerContentsDTO array is ignored. No data in the object will be updated or deleted.
composerContentsDTO.composerId
optional
integerID for an existing composer to assign to the track.
  • When no composerId nor composerName is provided, the entire object in the composerContentsDTO array is ignored. No data in the object with be updated or deleted.
composerContentsDTO.rightsId
required
integerPublishing type. One of the following:
  • 1 - Copyright control (self-published)
  • 2 - Published (managed by a publisher)
See additional required parameters below.
  • 3 - Public domain (no publisher)
composerContentsDTO.roleId
required
integerA 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
stringShare 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
stringName of the publisher to assign to the composer.
  • Only relevant when rightsId is 2.
  • When provided without an existing publisherId, tries to find an existing publisher with the same name (case-insensitive). If no such publisher is found, creates a new publisher.
  • When provided with publisherId, the name of the existing publisher will be updated.
  • Either a publisherId or a publisherName must be provided (when rightsId is 2). Otherwise, no publisher is specified (and the metadata for the track will be incomplete).
composerContentsDTO.publisherId
optional*
integerID for an existing publisher to assign to the composer.
  • Only relevant when rightsId is 2.
  • Either a publisherId or a publisherName must be provided (when rightsId is 2). Otherwise, no publisher is specified (and the metadata for the track will be incomplete).
*Set the 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
stringLyrics for the track. Note that not all stores accept lyrics.
isrc
optional
stringThis 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.
  • The ISRC is a unique code that every track must have. The system will automatically generate one upon distribution (free of charge) if you omit this parameter. You should never generate a new ISRC for a track that already has one.
  • The format of the ISRC code is CCXXXYYNNNNN, where CC is the country code (letters), XXX is your registrant code (letters and numbers), YY is the year (numbers), and NNNNN is the unique identifier (numbers).
wav
optional
objectThis 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.
  • Although the audio file is optional when creating a track, it is required to distribute it.
  • The audio file must be a stereo WAV file. A minimum bit depth of 16 bit and minimum sample rate of 44.1 kHz are recommended.
  • In line with the general behavior of this API, patching is not supported. When editing an existing release associated with an existing file, you must include this object (with the existing fileId and fileName) to prevent the file from being deleted.
See File Object
trackRecordingVersions
optional
array of objectsThis field is part of the new Track Recording model. See New track recording model for more information.

If provided, this list needs to have
  • A mandatory stereo version (recordingVersionType - 1)
  • An optional Dolby Atmos version (recordingVersionType - 2).
    • Sample rate needs to be 48000 Hz
    • The number of channels needs to be at least 3
    • The file size needs to be less than 2GB
    • The length of the recording must match the length of the stereo version.
    • The ISRCs must be different between the two versions.
Once a Track Version is created, it cannot be removed (only edited, but even then limited)
trackRecordingVersions.recordingVersionType
required
integerType of the track version.
  • 1 - Stereo
  • 2 - Dolby Atmos
trackRecordingVersions.isrc
required
stringA valid ISRC code for the track version.
  • If Dolby Atmos version exists, it’s ISRC cannot match the stereo version. These need to be unique.
Leave as null if the ISRC should be generated automatically (during distribution).
trackRecordingVersions.audioFiles
required
array of objectsWhen creating a new track, this array must contain a single object with a WAV (1) or a FLAC (2) fileFormat.
  • If multiple objects are provided, only one will be used, where WAV has the priority over FLAC.
  • if neither are provided the track will be created without an audio file.

When editing an existing track:
  • If the request is to replace the audio file - The list must contain only one object specifying the new audio file. (This only works for stereo files. Due to DSP restrictions, we DO NOT support updating Dolby Atmos files)
  • If the request is to edit an unrelated field - The list must have the exact same values returned by the GET /content/track/{trackId} endpoint.
See Audio File Object

New track recording model (Dolby Atmos Support)

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

Uploading Files

All files must be uploaded before being associated with a track or a release, This goes for both audio and image assets.

POST /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 Data

Form FieldTypeDescription
file
required
binaryThe audio file to upload

Response

FieldTypeDescription
fileIdstringThe ID of the uploaded file that’s going to be used to reference it across the application.
filenamestringThe filename of the uploaded file.

POST /media/image/upload

Content-type for this request must be multipart/form-data

Query Params

ParameterTypeDescription
cover
optional
booleanIs the image going to be used as a cover art

Form Data

Form FieldTypeDescription
file
required
binaryThe image file to upload

Response

fileId - string

POST /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.

Request Body

ParameterTypeDescription
externalUrl
required
stringA valid URL to a publicly available audio file.
filename
required
stringThe name of the file

Response

FieldTypeDescription
fileIdstringThe ID of the uploaded file that’s going to be used to reference it across the application.
filenamestringThe filename of the uploaded file.

Retrieving Releases

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.

GET /content/release/all

Retrieves list of all releases the user has permissions to view.

GET /content/release/all/summary

Retrieves a summary of all releases the user has permissions to view.

GET /content/release/{releaseId}

Retrieves the release with the releaseId specified in the URL path.

Adding/Editing Artists

An artist is a metadata entity that is referenced in assets (releases and tracks).

  • It is not necessary to create artists before creating an asset, unless you are running an ingestion script, while importing/creating a catalog; see Workflow: Importing an Existing Catalog or Creating New Release for more information about this issue.
  • Artists can be created with the same API call that creates the asset (Adding/Editing Releases). When creating or editing an asset, the options for editing existing artists associated with the asset are limited.
  • When editing an artist that is already associated with assets, all associated assets will be updated automatically.

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.

POST /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.

Request Body

ParameterTypeDescription
name
optional
stringName of the artist.
  • When provided without an artistId, tries to find an existing artist with the same name (case-insensitive). If no such artist is found, creates a new artist.
  • When provided with an artistId, updates the name of the artist.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
  • All artists in child enterprises automatically appear in the parent enterprise.
artistId
optional
integerID for an existing artist.
  • Either an artistName or artistId must be provided. If neither are provided, the artist will be null and the metadata for the track will be invalid.
artistExternalIds
optional*
array of objectsExternal 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.
  • These IDs are used by the stores to make sure that all of an artist’s content stays together. For artists who have not yet distributed to a specific store, we will generate a new ID if/when a release for the artist is distributed to the store.
  • Each object in the array represents an external ID for the artist at a specific store.
artistExternalIds.profileId
required
stringOne of the following:
  • For an artist already on the store, external ID for the artist at the specified store.
    To find this ID go to the artist’s page at the store, and copy-paste the numeric part of the URL
  • For artists not already on the store, 0.
    This indicates we should generate an ID for the artist if/when a release for the artist is distributed to the store.
    This indicates we should generate an ID for the artist. The second time you distribute a release for a new artist, you must retrieve the artist ID and provide it in the release. See Managing External Artist IDs.
artistExternalIds.distributorStoreId
required
integerRevelator ID for the store.
Currently supported for:
  • Apple Music - 1
  • Spotify - 9
artistLocals
optional
array of objectsArtist 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).
  • Each object in the array represents the name in a different language
name
required
stringName in the indicated language.
languageId
required
integerLanguage 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
objectThe image representing the artist.

See File Object.

Retrieving Artists

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.

GET /artists

Retrieves list of all artists in the account.

Example

Request
curl -X GET -H 'Accept: text/plain'\ 
'http://staging-api.revelator.com/artists?labels=labelA&labels=labelB'

GET /artists/summary

Retrieves a summary of all artists in the account.

GET /artists/{artistId}

Retrieves the artist with the artistId specified in the URL path.

Query params

ParameterTypeDescription
labelsarrayOne or more labels associated with artists
namestringName of artist

Managing External Artist IDs

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.

  • Currently, this is supported for Apple Music and Spotify, only.
  • These IDs must be provided when creating releases, even if you are not sending releases to DSPs via the Revelator system. In this case, the IDs can be assigned the value “0” and will remain with this value.

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!

  1. Specify the Revelator artistId parameter in the new release to ensure that the same Revelator artist is being assigned.
  2. Immediately before distributing the new release, retrieve the ID with the GET /content/artist/all or GET /content/artist/{Id} endpoint. The response will include the profileId for each DSP. See Artist Object.
    • If the value of the profileId is still 0, the ID for the artist has not yet been generated.
    • If the value of the 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:

  • For Apple Music, this ID is generated immediately upon distributing the original release. Therefore, as soon as the original release is distributed, the apple ID will be available.
  • For Spotify, this ID is generated when the original release goes live. When relevant, Spotify uses our internal ID to ensure the artist is merged with the correct profile.
  1. 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.

  2. Distribute the new release.