Developer Help Center

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

Warning

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 release you want to edit and modify the JSON object to avoid partial update problems.

POST /content/release/save

Table 1. Query String Parameters

Parameter

Description

token

Optional*

Access token returned upon authentication.

*Providing a token is mandatory, but alternatively, it can be provided as a header. See Authentication and Headers.



Table 2. Request Body Parameters

Parameter

Type

Description

name

Mandatory

string

Title of the Release.

  • Required for new releases.

  • When provided with an existing releaseId, updates the name 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.

  • 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

string

Name of the release’s primary artist/band.

  • Should be only the name of one artist.

    • 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 (ASCII SQL). 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 as Rights Holders in the parent enterprise.

artistId

Optional

integer

ID 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

Mandatory

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.

  • Each object in the array represents the name in a different language.

  • If name or languageId are omitted, the object will be ignored.

Parameter

Type

Description

name

Mandatory

string

Name in the indicated language.

version

Optional

string

Version in the indicated language.

languageId

Mandatory

integer

Language ID indicating the language of the name.

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

  • Each object in the array represents the name in a different language

Parameter

Type

Description

name

string

Name in the indicated language.

languageId

integer

Language ID indicating the language of the name.

Lookup up the languageId using the GET /common/lookup/languages resource.

contributors

Mandatory

array of objects

Additional key artists who should be given top level credit. Do not provide individual band member names or supporting musicians.

  • 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.

Parameter

Type

Description

contributorId

Optional

GUI ID

ID for an existing contributor.

  • Not relevant for new releases. Should be provided when editing existing releases.

roleId

Mandatory

integer

  • 5 - Featuring

  • 49 - Primary Artist*

  • 34 - Producer

  • 6 - Remixer

  • 7 - With

*Should only be used to name additional primary artists. The first (or only) primary artist should only be indicated with the artistName parameter.

For information about additional roles, use the GET /common/lookup/contributorRoles resource.

Note that 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. Furthermore, even though publishing roles do exist for this attribute, they should never be used; publishing credits should be provided per track in the composerContentsDTO array.

artist

Mandatory

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

Mandatory

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

Mandatory

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

  • 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

Name of the label.

  • Should never be provided when hasRecordLabel is false.

  • When provided without labelId, tries to find an existing label with the same name (ASCII SQL). 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

integer

ID 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

Mandatory

integer

One 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

Mandatory

integer

One 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.

    In this case, upc and releaseDate are required parameters.

  • false - The release has not been released previously. (Default)

upc

Optional

integer

UPC/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

string

Official date the release was previously released in the format "mm/dd/yyyy".

  • Should only be provided when previouslyReleased is true (and in this case, it is required). For releases that have not yet been released, this parameter is automatically set according to the saleStartDate parameter in the distribution options endpoint. See Setting Distribution Options.

primaryMusicStyleId

Mandatory

integer

ID for the release's primary music style.

Lookup music style IDs using the GET /common/lookup/musicstyles resource.

releaseTypeId

Mandatory

integer

  • 1 - Album

  • 2 - Single Singles should contain one track, and the name of the release and name of the track should be identical.

  • 4 - EP

languageId

Mandatory

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

Optional

array of objects

Tracks 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

object

Cover 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 PNG, GIF, BMP, TIF, JPG or JPEG

      • 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.



curl -X POST 'http://staging-api.revelator.com/content/release/save?token=2ec6ba54-3199-473a-a129-296bf672a759'\
--header 'Content-Type: application/json'\ 
--header 'Accept: application/json'\
-d '{ "artistName":"Release_artist",  
      "contributors": [], 
      "copyrightC": "2018 companyC",
      "copyrightP": "2018 companyP", 
      "hasRecordLabel": false,  
      "previouslyReleased": false,  
      "languageId": 1,  
      "name": "Single",  
      "primaryMusicStyleId": 60,   
      "releaseTypeId": 1,  
      "releasesLocals": [], 
      "image": { "externalUrl":"https://www.dropbox.com/s/24ky6wvnu2ksv7f/sourceFileName.jpg?dl=1", 
                 "filename":"file123.jpg" }, 
      "tracks": [ {"artistName": "TRACK_ARTIST", 
                   "languageId": 1, 
                   "name":"Single",  
                   "explicit": false,
                   "trackType": 1,                 
                   "wav": { "filename":"file123.wav", 
                            "externalUrl" :"https://www.dropbox.com/s/3telykbgq2tf3ln/ sourceFileName.wav?dl=1" }, 
                   "trackLength": 267, \ 
                   "sampleRate": 44100, \
                   "composerContentsDTO":[{ "composerName": "John Doe",
                   	                    "rightsId": 1, 
		                            "roleId": 2, 
	                                    "share":100 }]} 
              ] 
     }'