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.

Important Considerations for Creating Releases

Before detailing the request body, please review these important rules regarding UPCs and the creation of compilation releases.

Track Association and Uniqueness (Single Release per Track ID)

Currently, a single trackId can only be associated with one release at a time.

If you need to include the same underlying recording (i.e., the same ISRC) on multiple releases (e.g., a single and a later album), you must treat it as a new track for each release. This means you should create a new track entity (which will generate a new, unique trackId) for each release it appears on.

We are actively working on removing this constraint to allow a single track entity to be associated with multiple releases. This documentation will be updated when that functionality is available.

Global UPC Uniqueness

To ensure data integrity and prevent content conflicts, UPCs must be unique across the entire Revelator system.

UPCs used in sandbox account can be used again in production account.

Creating Compilation Releases

A compilation is a release that features multiple primary artists. Our system has specific validation rules to correctly identify and process these releases.

Artists Must Exist and Be Provided For a compilation release to validate properly, all contributors (especially primary artists using roleId = 49) must be provided as an object containing their existing artistId. You cannot create new artists implicitly within a compilation release payload.
Compilation Validation Logic Our system determines if a release is a “Various Artists” compilation based on the presence of a main artistId at the release level and the count of primary artist contributors (roleId = 49) across the entire release (at both the release and track levels).
- If you provide a main artistId at the release level: The release is treated as a standard release by a primary artist. You will receive an error if you also include more than four primary artist contributors (roleId = 49).
- If you do NOT provide a main artistId at the release level: The release is treated as a “Various Artists” compilation. You will receive an error if you include less than four primary artist contributors (roleId = 49). This ensures the release meets the criteria for a compilation.

POST `/content/release/save`

Request Body

Parameter	Type	Description
`name` required	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 (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	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` 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. 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	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). Each object in the array represents the name in a different language
`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. Parameter is mandatory even if the array is empty. Each object in the array represents a contributor. Duplicate contributors are not allowed. The system prevents adding the same artist with the same role more than once on a single track or release. The uniqueness is checked based on the combination of (`artistId` or `artist.name`) and `roleId`. 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	UUID	ID for an existing contributor. Not relevant for new releases. Should be provided when editing existing releases.
`contributors.roleId` required	integer	The 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 from `contributorRoleGroupId = 4` should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. `contributorRoleGroupId = 4` 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	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	`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	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.
`artistExternalIds` optional	array of objects	An array of external DSP profile IDs for the main primary artist of the release. This structured array is the required method for providing DSP profile IDs. See the comprehensive guide at Managing External Artist IDs.
`artistAppleId` *DEPRECATED*	string	(DEPRECATED) This field is obsolete. Provide Apple Music profile IDs using the `release.artistExternalIds` array with `distributorStoreId: 1` instead. See Managing External Artist IDs.
`artistSpotifyId` *DEPRECATED*	string	(DEPRECATED) This field is obsolete. Provide Spotify profile IDs using the `release.artistExternalIds` array with `distributorStoreId: 9` instead. 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	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`. The value needs to be unique across the system
`releaseDate` optional	string	Official date the release was previously released in the ISO format `YYYY-MM-DD` 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. Release date year cannot be more than 1 year different than your P & C line year.
`primaryMusicStyleId` required	integer	The primary music style ID for the release. See Music Style ID.
`secondaryMusicStyleId` optional	integer	The secondary music style ID for the release. See Music Style ID.
`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.
`description` optional	string	Release description.
`tracks` required	array of objects	Tracks for the release. Each object in the array represents a track. 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 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://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": [],
    "artistExternalIds: []",
    "copyrightC": "2025 companyC",
    "copyrightP": "2025 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",
            "contributors: []",
            "artistExternalIds": [],
            "explicit": false,
            "wav": {
                "filename": "file123.wav",
                "fileId": "00000000-0000-0000-0000-000000000000"
            },
            "trackLength": 267,
            "sampleRate": 44100,
            "composerContentsDTO": [
                {
                    "composerName": "John Doe",
                    "rightsId": 1,
                    "roleId": 2,
                    "share": 100,
                    "composerImageId": "00000000-0000-0000-0000-000000000000"
                }
            ]
        }
    ]
}'

Artist Object

Parameter	Type	Description
`name` optional	string	Name 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	integer	ID 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 objects	External IDs for the artist. See the comprehensive guide at Managing External Artist IDs.
`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
`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.

File Object

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

Audio File Object

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	`1` - WAV `2` - FLAC `3` - MP3

Track Object

Parameter	Type	Description
`name` optional	string	Title 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	integer	The ID of an existing track to associate with the release. This ID was returned when the track was created. When set to `0` or omitted, a new track is created based on the provided track data. When providing an existing `trackId`, please be aware of the system’s current limitation regarding track uniqueness. See Track Association and Uniqueness for critical details Note on Updates: In line with the general behavior of this API, patching is not supported. When assigning an existing track, it will be updated with the data provided; any existing values for omitted parameters will be deleted.
`artistName` optional	string	Name 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	integer	ID 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 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). 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	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). Each object in the array represents the name in a different language
`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. Parameter is mandatory even if the array is empty. Each object in the array represents a contributor. Duplicate contributors are not allowed. The system prevents adding the same artist with the same role more than once on a single track or release. The uniqueness is checked based on the combination of (`artistId` or `artist.name`) and `roleId`. 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	UUID	ID for an existing contributor. Not relevant for new releases. Should be provided when editing existing releases.
`contributors.roleId` required	integer	The 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 from `contributorRoleGroupId = 4` should not be used in the contributors array, except in the case of classical music where the “composer” role (roleId 2) is required. `contributorRoleGroupId = 4` 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	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: 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	integer	One 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 integers	One 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.
`artistExternalIds` optional	array of objects	An array of external DSP profile IDs for the main primary artist of the release. This structured array is the required method for providing DSP profile IDs. See the comprehensive guide at Managing External Artist IDs.
`artistAppleId` *DEPRECATED*	string	(DEPRECATED) This field is obsolete. Provide Apple Music profile IDs using the `track.artistExternalIds` array with `distributorStoreId: 1` instead. See Managing External Artist IDs.
`artistSpotifyId` *DEPRECATED*	string	(DEPRECATED) This field is obsolete. Provide Spotify profile IDs using the `track.artistExternalIds` array with `distributorStoreId: 9` instead. See Managing External Artist IDs.
`copyrightP` optional	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` optional	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.
`primaryMusicStyleId` optional	integer	The primary music style ID for the track. See Music Style ID.
`secondaryMusicStyleId` optional	integer	The secondary music style ID for the track. See Music Style ID.
`previewStartSeconds` optional	integer	Preview/Clip Start Time. Indicate where your clip should start when people preview your track. If no value is entered, your clip will start at the 15th second.
`composerContentsDTO` required	array of objects	A list of publishing contributors(composers) for the track . The same composer cannot be added with the same role more than once. The uniqueness of each entry is validated by the combination of the composer’s identity (`composerName` or `composerId`) and their `roleId`.
`composerContentsDTO.composerName` optional	string	Name 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	integer	ID 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	integer	Publishing 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	integer	A role associated with the composer. Look up roleIds with GET `/common/lookup/contributorRoles`. Only roles from `contributorRoleGroupId = 4` 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. 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*	integer	ID 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.
`composerContentsDTO.composersLocals` optional	array of objects	Composer name in different languages. If `name` or `languageId` are omitted, the object will be ignored.
`composerContentsDTO.composersLocals.name` optional	string	Name in the indicated language.
`composerContentsDTO.composersLocals.version` optional	string	Version in the indicated language.
`composerContentsDTO.composersLocals.languageId` optional	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.
`lyrics` optional	string	Lyrics for the track. Note that not all stores accept lyrics.
`compositions` optional	array of objects	An array of Composition objects representing the underlying musical works for the track. This field is relevant for tracks of all types (Original, Cover, Public Domain) as it describes the fundamental composition. Important behavior during track type change: When updating a track and changing its `trackType` from `2` (Cover song) to `1` (Original song) or `3` (Public domain song), any existing `compositions` array will be automatically cleared. This indicates that for these `trackType` changes, the `compositions` data cannot be directly carried over or updated in the same request; it will be cleared.
`compositions.originalTitle` optional	string	The original title of the musical work/composition.
`compositions.originalComposers` optional	string	The names of the original composer(s) of the musical work.
`compositions.originalRecordingArtist` optional	string	The name(s) of the artist(s) who originally recorded this musical work.
`compositions.sourceAlbumTitle` optional	string	The title of the original album from which this musical work originates, if applicable.
`compositions.sourceMaterialTitle` optional	string	The title of the original source material (e.g., film, play, book) from which this musical work originates, if applicable.
`compositions.iswc` optional	string	International Standard Musical Work Code (ISWC). A unique, international identifier for musical works. Format: `T` followed by 10 digits (e.g., T1234567890). Issued by national or regional ISWC agencies.
`compositions.url` optional	string	A URL relevant to the composition (e.g., a link to its original publisher or details).
`compositions.notes` optional	string	Internal notes or comments related to the composition.
`compositions.isPaid` optional	boolean	Indicates if royalties/payments for this composition have been settled or paid.
`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. 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	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. 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 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 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	integer	Type of the track version. `1` - Stereo `2` - Dolby Atmos
`trackRecordingVersions.isrc` required	string	A 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 objects	When 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`

Uploads WAV or FLAC audio files.

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 Field	Type	Description
`file` required	binary	The audio file to upload

Response

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.

POST `/media/audio/upload/wav`

Uploads WAV audio files.

This endpoint has the same request, response, and requirements as POST /media/audio/upload. The file field in the Form Data should contain the WAV audio file.

POST `/media/audio/upload/flac`

Uploads FLAC audio files.

This endpoint has the same request, response, and requirements as POST /media/audio/upload. The file field in the Form Data should contain the FLAC audio file.

POST `/media/image/upload`

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

If the uploaded image is a PNG and the cover query parameter is set to true, the image will be automatically converted to JPG.

Query Params

Parameter	Type	Description
`cover` optional	boolean	Is the image going to be used as a cover art

Form Data

Form Field	Type	Description
`file` required	binary	The image file to upload

Response


`fileId` - string

POST `/media/audio/pullexternal/wav`

An alternative way to upload files by providing a publicly available URL. This endpoint can be useful if you don’t want to handle the file upload yourself or if the asset is already hosted 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

Parameter	Type	Description
`externalUrl` required	string	A valid URL to a publicly available audio file.
`filename` required	string	The name of the file. You must include the file extension (e.g., `my-track.wav`).

Response

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.

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.

In response you will receive releaseTypeId which is automatically set based on provided data across release and it’s tracks.

1 - Album
2 - Single
4 - EP

Some endpoint will return additionalCounters. This object contains number of release types that were not included in retuned list but match searched conditions.

GET `/content/release/all`

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

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve. Default is `1`.
`pageSize` optional	integer	The number of items to return per page. Requires `pageNumber` query parameter to work properly.
`orderByProperty` optional	string	The property to sort the results by. Available options: `name` `releaseId` `upc` `releaseDate`
`orderByDescending` optional	boolean	If `false`, orders the results in ascending order. If `true` or omitted, orders in descending order.
`searchText` optional	string	A search term to filter releases by name. The search is case-insensitive.
`selectAll` optional	boolean	If true, the response will only contain an array of `releaseId` values for all matching releases.
`fromDate` optional	date-time	Filters for releases created on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`toDate` optional	date-time	Filters for releases created on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`releaseFromDate` optional	date-time	Filters for releases with a `releaseDate` on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`releaseToDate` optional	date-time	Filters for releases with a `releaseDate` on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`musicStyles` optional	array	An array of Music Style IDs to filter releases associated with any of the specified music styles.
`languages` optional	array	An array of language IDs to filter releases.
`labels` optional	array	An array of label IDs to filter releases.
`stores` optional	array	An array of store IDs to filter releases distributed to any of the specified stores.
`enterprises` optional	array	An array of enterprise IDs to filter releases. Only relevant for parent account users.
`releaseTypes` optional	array	An array of release type IDs (`1`: Album, `2`: Single, `4`: EP) to filter releases.
`artists` optional	array	An array of artist IDs. If provided, returns only releases where the provided artist ID is the main primary artist of the release.
`upc` optional	string	Filters for a release with a specific UPC. The match must be exact.

Example

↓

Request

curl -X GET
'https://api.revelator.com/content/release/all?pageNumber=1&pageSize=10&orderByDescending=false&searchText=you'

Response

{
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "upc": "198009123456",
            "isrc": null,
            "trackISRC": null,
            "trackRecordingVersions": [],
            "artistId": 12345,
            "artistName": "Example Artist",
            "version": "Remix",
            "labelName": "Example Label",
            "releaseDate": "2024-10-26T00:00:00",
            "creationDate": "2024-06-14T10:58:58Z",
            "featureFmSmartLink": null,
            "tracksCount": 1,
            "albumLength": 180,
            "releaseId": 54321,
            "name": "Example Release",
            "releaseTypeId": 2,
            "isLockedForDistribution": false,
            "isDolbyAtmosReadOnly": false,
            "isIngested": true,
            "enterpriseName": "Sample Child Enterprise",
            "enterpriseId": 67890,
            "assetId": 98765,
            "image": {
                "fileId": "00000000-0000-0000-0000-000000000001",
                "isTemp": false,
                "filename": "cover-art.jpg",
                "externalUrl": null,
                "lastUpdateDate": "2024-06-14T10:58:58.833Z"
            },
            "artist": null,
            "contributors": []
        }
    ],
    "additionalCounters": {
        "album": 5,
        "ep": 10,
        "ringtone": 0,
        "single": 53,
        "video": 0
    }
}

GET `/content/release/all/summary`

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

Query params

Parameter	Type	Description
`searchText` optional	string	A search term to filter releases by name. The search is case-insensitive.
`fromDate` optional	date-time	Filters for releases created on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`toDate` optional	date-time	Filters for releases created on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`releaseFromDate` optional	date-time	Filters for releases with a `releaseDate` on or after this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`releaseToDate` optional	date-time	Filters for releases with a `releaseDate` on or before this date (ISO 8601 format: YYYY-MM-DDTHH:MM:SS).
`musicStyles` optional	array	An array of Music Style IDs to filter releases associated with any of the specified music styles.
`languages` optional	array	An array of language IDs to filter releases.
`labels` optional	array	An array of label IDs to filter releases.
`stores` optional	array	An array of store IDs to filter releases distributed to any of the specified stores.
`enterprises` optional	array	An array of enterprise IDs to filter releases. Only relevant for parent account users.
`releaseTypes` optional	array	An array of release type IDs (`1`: Album, `2`: Single, `4`: EP) to filter releases.
`artists` optional	array	An array of artist IDs. If provided, returns only releases where the provided artist ID is the main primary artist of the release.

Example

↓

Request

curl -X GET
'https://api.revelator.com/content/release/all/summary?searchText=you'

Response

[
    {
        "releaseId": 0,
        "name": "Release name",
        "version": "Remix",
        "releaseDate": "2020-10-26T00:00:00",
        "releaseTypeId": 2,
        "upc": 0,
        "isLockedForDistribution": false,
        "isDolbyAtmosReadOnly": false,
        "isIngested": false,
        "enterpriseName": "Child enterprise name",
        "enterpriseId": 0,
        "assetId": 0,
        "image": {
            "fileId": "00000000-0000-0000-0000-000000000001",
            "isTemp": false,
            "filename": "cover.jpg",
            "externalUrl": null,
            "lastUpdateDate": "2020-12-20T22:53:41.687"
        },
        "artist": {
            "artistId": 0,
            "name": "Artist name",
            "firstName": null,
            "lastName": null,
            "middleName": null,
            "isni": null,
            "releasesCount": 0,
            "tracksCount": 0,
            "image": {
                "fileId": "00000000-0000-0000-0000-000000000002",
                "isTemp": false,
                "filename": "profile.jpg",
                "externalUrl": null,
                "lastUpdateDate": "2024-10-02T14:12:01.873"
            }
        },
        "tracksCount": 1,
        "contributors": []
    },
]

GET `/content/release/{releaseId}`

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

July 23, 2025

Upcoming Change: The SpotifyId, AppleId, and RdioId fields on the Track object are deprecated and will be removed in a future update.

Please use the new ReleaseTracks field for DSP identifiers going forward. This new structure provides a more consistent and scalable way to associate tracks with external DSP identifiers across releases.

Example of the new ReleaseTracks field within the Track object:

{
  // Existing fields
  "tracks": [
    {
      // Existing fields
      "releaseTracks": [
        {
          "releaseId": 0,
          "spotifyId": "string",
          "appleId": 0,
          "rdioId": "string",
          "deezerId": "string"
        }
      ]
    }
  ]
}

Example

↓

Request

curl -X GET 'https://api.revelator.com/content/release/123456'

Response

{
    "createdBy": "00000000-0000-0000-0000-000000000000",
    "createdByEmail": "[email protected]",
    "createdByUserId": "00000000-0000-0000-0000-000000000000",
    "enterpriseEmail": "[email protected]",
    "enterpriseOwnerId": "00000000-0000-0000-0000-000000000000",
    "lastPayeePaymentDate": "2023-10-23",
    "lastPayeePaymentAmount": 0.00,
    "isEnterpriseVip": true,
    "isEnterpriseWhiteListed": true,
    "payeeReferrerName": null,
    "description": null,
    "descriptionTitle": null,
    "tags": null,
    "languageId": 0,
    "copyrightC": "2025 Example Artist",
    "copyrightP": "2025 Example Artist",
    "recordingLocation": null,
    "recordingDate": null,
    "parentalAdvisory": null,
    "producedBy": null,
    "mixedBy": null,
    "masteredBy": null,
    "masteredDate": null,
    "productionCredits": null,
    "totalSales": 0.0,
    "enterpriseId": 0,
    "payeeOwner": 0,
    "hasRecordLabel": true,
    "previouslyReleased": false,
    "releasesLocals": [],
    "contributors": [
        {
            "contributorId": "00000000-0000-0000-0000-000000000000",
            "roleId": 0,
            "isPrimary": false,
            "trackId": null,
            "releaseId": 0,
            "contributorRoleGroupId": 0,
            "artist": {
                "labelId": null,
                "labelName": "Example Label Name",
                "contactId": null,
                "contact": null,
                "biography": null,
                "yearsActive": [],
                "influencers": [],
                "contemporaries": [],
                "tags": [],
                "isSigned": false,
                "musicStyles": [],
                "artistExternalIds": [],
                "socialUrls": [],
                "artistLocals": [],
                "artistsWebsites": [],
                "webAlias": null,
                "enterpriseId": 0,
                "activeFromDate": null,
                "activeToDate": null,
                "artistId": 0,
                "name": "Artist Name",
                "firstName": null,
                "lastName": null,
                "middleName": null,
                "isni": null,
                "releasesCount": 0,
                "tracksCount": 0,
                "image": null
            }
        }
    ],
    "artistLocals": [],
    "tracks": [
        {
            "enterpriseName": "Example Enterprise Name",
            "enterpriseId": 0,
            "trackId": 0,
            "name": "Track Name",
            "spotifyId": null,
            "artistId": 0,
            "artistName": "Artist Name",
            "artistAppleId": null,
            "artistSpotifyId": null,
            "artistExternalIds": [],
            "labelId": 0,
            "labelName": "Example Label Name",
            "discNumber": null,
            "trackLength": 0,
            "channels": 0,
            "sampleRate": 0,
            "bitDepth": 0,
            "bitrate": 0,
            "trackVendorId": null,
            "isrc": null,
            "version": null,
            "copyrightC": "2021 Example Artist",
            "copyrightP": "2024 Example Artist",
            "description": null,
            "languageId": 0,
            "explicit": true,
            "lyrics": null,
            "playingCount": 0,
            "appleId": null,
            "priceTierId": null,
            "rdioId": null,
            "previewStartSeconds": 0,
            "totalSales": 0.0,
            "image": null,
            "wav": null,
            "flac": {
                "fileId": "00000000-0000-0000-0000-000000000000",
                "isTemp": false,
                "filename": "ExampleFlac.flac",
                "externalUrl": null,
                "lastUpdateDate": "0001-01-01T00:00:00Z"
            },
            "trackRecordingVersions": [
                {
                    "isrc": null,
                    "recordingVersionType": 0,
                    "audioFiles": [
                        {
                            "audioId": "00000000-0000-0000-0000-000000000000",
                            "fileFormat": 0,
                            "audioFilename": "ExampleFlac.flac",
                            "audioChannels": 0,
                            "audioBitDepth": 0,
                            "audioSampleRate": 0,
                            "audioBitrate": 0,
                            "audioSeconds": 0,
                            "audioSize": 0
                        }
                    ]
                }
            ],
            "fileExtension": ".flac",
            "isLockedForDistribution": false,
            "isDolbyAtmosReadOnly": false,
            "primaryMusicStyleId": 0,
            "secondaryMusicStyleId": 0,
            "previouslyReleased": false,
            "trackType": 0,
            "licenseRequestStatus": null,
            "isAudioValid": null,
            "tracksLocals": [],
            "artistLocals": [],
            "contributors": [
                {
                    "contributorId": "00000000-0000-0000-0000-000000000000",
                    "roleId": 0,
                    "isPrimary": false,
                    "trackId": 0,
                    "releaseId": null,
                    "contributorRoleGroupId": 0,
                    "artist": {
                        "labelId": null,
                        "labelName": "Example Label Name",
                        "contactId": null,
                        "contact": null,
                        "biography": null,
                        "yearsActive": [],
                        "influencers": [],
                        "contemporaries": [],
                        "tags": [],
                        "isSigned": false,
                        "musicStyles": [],
                        "artistExternalIds": [],
                        "socialUrls": [],
                        "artistLocals": [],
                        "artistsWebsites": [],
                        "webAlias": null,
                        "enterpriseId": 0,
                        "activeFromDate": null,
                        "activeToDate": null,
                        "artistId": 0,
                        "name": "Artist Name",
                        "firstName": null,
                        "lastName": null,
                        "middleName": null,
                        "isni": null,
                        "releasesCount": 0,
                        "tracksCount": 0,
                        "image": null
                    }
                }
            ],
            "catalog": null,
            "compositions": [
                {
                    "compositionId": 0,
                    "trackId": 0,
                    "originalTitle": "Example Original Title",
                    "originalComposers": "Example Composer Names",
                    "originalRecordingArtist": null,
                    "sourceAlbumTitle": null,
                    "sourceMaterialTitle": null,
                    "iswc": "T1234567890",
                    "url": "http://example.com/composition-url",
                    "notes": null,
                    "isPaid": false
                }
            ],
            "releaseIds": [
                0
            ],
            "releases": [
                {
                    "releaseId": 0,
                    "name": "Example Release Name",
                    "version": null,
                    "releaseDate": "2025-07-18T00:00:00Z",
                    "releaseTypeId": 0,
                    "upc": null,
                    "isLockedForDistribution": false,
                    "isDolbyAtmosReadOnly": false,
                    "isIngested": false,
                    "enterpriseName": "Example Enterprise Name",
                    "enterpriseId": 0,
                    "assetId": 0,
                    "image": {
                        "fileId": "00000000-0000-0000-0000-000000000000",
                        "isTemp": false,
                        "filename": "example-image.jpg",
                        "externalUrl": null,
                        "lastUpdateDate": "2025-05-29T10:18:47.997Z"
                    },
                    "artist": {
                        "artistId": 0,
                        "name": "Artist Name",
                        "firstName": null,
                        "lastName": null,
                        "middleName": null,
                        "isni": null,
                        "releasesCount": 0,
                        "tracksCount": 0,
                        "image": null
                    },
                    "tracksCount": 0,
                    "contributors": []
                }
            ],
            "composerContentsDTO": [
                {
                    "contributorId": 0,
                    "composerId": 0,
                    "composerName": "Composer Name",
                    "composerImageId": "00000000-0000-0000-0000-000000000000",
                    "share": 0.00,
                    "publisherId": null,
                    "publisherName": "Publisher Name",
                    "publisherAdminId": null,
                    "publisherAdminName": null,
                    "proId": null,
                    "rightsId": 0,
                    "proRegistrationId": null,
                    "roleId": 0,
                    "composersLocals": []
                }
            ],
            "isFullyLocked": false,
            "copyTrackId": null,
            "isIngested": false,
            "isLicensePaid": false,
            "distributorStoreGenreIds": [],
            "assetId": 0,
            "monetizations": [
                {
                    "trackId": 0,
                    "distributorStoreId": 0,
                    "policyId": 0,
                    "isEligible": null,
                    "optIn": null,
                    "isPaid": null,
                    "isLive": null,
                    "transactionId": null,
                    "transactionDate": null
                }
            ],
            "acrCloud": {
                "timestampUtc": "2025-07-18T09:25:48.871Z",
                "scans": [],
                "coverSongs": [],
                "derivativeWorks": [],
                "speechDetection": [],
                "musicDetected": 0,
                "duration": 0,
                "error": null,
                "status": 0,
                "isrc": null
            },
            "royaltyToken": null,
            "trackProperties": [],
            "releasesCount": 0,
            "releaseTracks": [
                {
                    "releaseId": 0,
                    "spotifyId": "spotifyIdExample",
                    "appleId": 123456,
                    "rdioId": "rdioIdExample",
                    "deezerId": "deezerIdExample"
                }
            ]
        }
    ],
    "enterpriseImageId": "00000000-0000-0000-0000-000000000000",
    "featureFmSmartLink": null,
    "distributorStoreGenreIds": [],
    "upc": "123456789012",
    "isrc": null,
    "trackISRC": null,
    "trackRecordingVersions": [
        {
            "isrc": null,
            "recordingVersionType": 0,
            "audioFiles": [
                {
                    "audioId": "00000000-0000-0000-0000-000000000000",
                    "audioFilename": "ExampleAudio.flac",
                    "fileFormat": 0
                }
            ]
        }
    ],
    "artistId": 0,
    "artistName": "Artist Name",
    "artistAppleId": null,
    "artistSpotifyId": null,
    "artistExternalIds": [],
    "catalog": null,
    "version": null,
    "artistImageId": "00000000-0000-0000-0000-000000000000",
    "labelId": 0,
    "labelName": "Example Label Name",
    "releaseDate": "2025-07-18T00:00:00Z",
    "creationDate": "2025-07-16T13:18:00Z",
    "primaryMusicStyleId": 0,
    "secondaryMusicStyleId": 0,
    "notesCount": 0,
    "payeeNotesCount": 0,
    "approvedDate": null,
    "kountStatusId": null,
    "kountStatusName": null,
    "isFullyLocked": false,
    "releaseId": 0,
    "name": "Example Release Name",
    "releaseTypeId": 0,
    "isLockedForDistribution": false,
    "isDolbyAtmosReadOnly": false,
    "isIngested": false,
    "enterpriseName": "Example Enterprise Name",
    "assetId": 0,
    "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": false,
        "filename": "example-cover.jpg",
        "externalUrl": null,
        "lastUpdateDate": "2025-05-29T10:18:47.997Z"
    },
    "artist": null,
    "tracksCount": 0
}

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

Parameter	Type	Description
`name` optional	string	Name 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	integer	ID 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 objects	External IDs for the artist for each store. Each supported store should have one or zero entries. These IDs are used by the stores to make sure that all of an artist’s content stays together. Each object in the array represents an external ID for the artist at a specific store. `0`, `null` or no entry will result in different behavior for each store during distribution Apple Music (1): A new profile will be created during distribution Spotify (9): A new profile will be created when the release goes live SoundCloud (68): Soundclound will map the artist to a profile of their choosing or create a new profile if unsuccessful. Meta (309): Meta will map the artist to a profile of their choosing. New profile cannot be created automatically.
`artistExternalIds.profileId` required	string	External ID for the artist at the specified store. To find this ID go to the artist’s page at the store, and copy the numeric part of the URL For an artist not on the store, provide `0`, `null` or omit this array entry. Behavior will differ depending on the store.
`artistExternalIds.distributorStoreId` required	string	Revelator ID for the store. Currently supported for: Apple Music - 1 Spotify - 9 Soundcloud - 68 Meta - 309
`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
`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.
`image` optional	object	The image representing the artist. See File Object.
`additionalContacts` optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
`activeFromDate` optional	string	The specific date when the artist began their activity. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS).
`activeToDate` optional	string	The specific date when the artist ended their activity (or null if still active). ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS).
`firstName` optional	string	Legal first name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive).
`middleName` optional	string	Legal middle name(s) of the artist.
`lastName` optional	string	Legal last name of the artist. Must consist only of Unicode letters, hyphens (-), single quotes (’), or dots (.). Must have a total length between 1 and 100 characters (inclusive).
`isni` optional	string	The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’.
`artistLabels` optional	array of objects	An array of objects, each representing an association with a Label. See nested fields below for structure and requirements.
`artistLabels.labelId` required	integer	The ID of an existing Label to associate with the artist.
`artistLabels.contractStartYear` required	string	The start date of the contract between the artist and this label. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ).
`artistLabels.contractEndYear` optional	string	The end date of the contract between the artist and this label. If provided, must be after `contractStartYear`. ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ).

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.

Query params

Parameter	Type	Description
`labels` optional	array	An array of label IDs to filter artists associated with any of the specified labels.
`name` optional	string	Name of artist, case-sensitive, exact match.
`isni` optional	string	Filters artists by their International Standard Name Identifier (ISNI).
`contributorGroupId` optional	integer	Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to `/common/lookup/ContributorRolesGroups` for available group IDs.

Example

↓

Request

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

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "artistId": 0,
      "name": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "isni": "string",
      "releasesCount": 0,
      "tracksCount": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-12T12:38:18.124Z"
      }
    }
  ],
  "additionalCounters": {}
}

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

Parameter	Type	Description
`labels` optional	array	One or more labels associated with artists
`name` optional	string	Name of artist

GET `/content/artist/all`

Retrieves paginated list of all artists in the account.

Query params

Parameter	Type	Description
`labels` optional	array	An array of label IDs to filter artists associated with any of the specified labels.
`name` optional	string	Filters artists by name (case-insensitive, exact match).
`fromDate` optional	date-time	Filters for artists created on or after the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone).
`toDate` optional	date-time	Filters for artists created on or before the provided date. Expected format: YYYY-MM-DDTHH:MM:SS (e.g., ISO 8601 without timezone).
`musicStyles` optional	array	An array of music style IDs to filter artists associated with any of the specified music styles.
`isni` optional	string	Filters artists by their International Standard Name Identifier (ISNI).
`contributorGroupId` optional	integer	Filters artists who have contributed to tracks/releases using a role that belongs to the specified Contributor Role Group ID. Refer to `/common/lookup/ContributorRolesGroups` for available group IDs.
`pageNumber` optional	integer	The page number of the results to retrieve. Default is `1`.
`pageSize` optional	integer	The number of items per page. Default is a system-defined value. Requires `pageNumber` query parameter to work properly.
`orderByProperty` optional	string	The property to sort the results by. Available options: - `artistId` - `isni` - `name` - `firstName` - `middleName` - `lastname`
`orderByDescending` optional	boolean	If `true` or omitted, orders the results in descending order. If `false`, orders in ascending order.
`searchText` optional	string	Allows to search by client’s name.

Example

↓

Request

curl -X GET -H 'Accept: text/plain'\
'http://api.revelator.com/content/artist/all?orderByProperty=middleName&pageSize=10&pageNumber=1'

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "additionalContacts": [
        {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "phone": "string",
          "email": "string",
          "address": "string",
          "address2": "string",
          "zipcode": "string",
          "countryId": 0,
          "imageId": "00000000-0000-0000-0000-000000000000",
          "image": {
            "fileId": "00000000-0000-0000-0000-000000000000",
            "isTemp": true,
            "filename": "string",
            "externalUrl": "string",
            "lastUpdateDate": "2025-08-26T07:20:39.247Z"
          },
          "isActive": true,
          "labelId": 0,
          "publisherId": 0,
          "artistId": 0,
          "city": "string",
          "state": "string",
          "location": "string",
          "contactRoleId": 0
        }
      ],
      "musicStyles": [
        {
          "musicStyleId": 0,
          "name": "string"
        }
      ],
      "creationDate": "2025-08-26T07:20:39.247Z",
      "hasPortal": true,
      "artistId": 0,
      "name": "string",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "isni": "string",
      "releasesCount": 0,
      "tracksCount": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-08-26T07:20:39.247Z"
      }
    }
  ],
  "additionalCounters": {}
}

Managing External Artist IDs

External Artist IDs (also known as profile IDs) are identifiers used by DSPs (Digital Service Providers) to group an artist’s content under a single profile. Providing these IDs is crucial for preventing situations where artists with the same name are merged or a single artist’s catalog is split across multiple profiles.

This is managed through the artistExternalIds array, which can be provided in the following contexts:

When creating or updating an artist.
When adding or updating an artist as a contributor to a release or a track.
Directly on a release or a track for the main primary artist.

Currently, providing external artist IDs is supported for:

Apple Music (distributorStoreId: 1)
Spotify (distributorStoreId: 9)
SoundCloud (distributorStoreId: 68)
Meta (distributorStoreId: 309 & 310)

Providing `artistExternalIds`

The artistExternalIds is an array of objects. Each object links a profileId (the artist’s ID on the DSP) with a distributorStoreId (our internal ID for the DSP).

Parameter	Type	Description
`artistExternalIds` optional	array of objects	An array of objects, each representing an external ID for the artist at a specific store. Each supported store should have one or zero entries.
`artistExternalIds.profileId` required	string	The artist’s profile ID at the specified store. To find this ID, go to the artist’s page at the store and copy the unique identifier from the URL.
`artistExternalIds.distributorStoreId` required	integer	The Revelator ID for the store. See the “Supported DSPs” callout above for current values.

Handling New Artists (Empty or Missing Profile IDs)

Always provide a profileId if one exists for the artist. If the artist is new to a DSP, you should omit the entry for that DSP from the artistExternalIds array. Each DSP has different behavior when an artist’s profile ID is not provided:

Apple Music (1): A new profile will be generated during distribution.
Spotify (9): A new profile will be generated when a release goes live.
SoundCloud (68): SoundCloud will attempt to map the artist to an existing profile or create a new one if unsuccessful. Please contact Support if you notice your release mapped to the wrong page.
Meta (309 & 310): Meta will attempt to map the artist to an existing profile. New profiles cannot be created automatically. Please contact Support if you notice your release mapped to the wrong page.

Profiles for Facebook Audio Library (309) and Facebook Rights Manager (310) are connected. When you assign an artist’s profile for one, we will automatically create the other. When updating, you must provide the same profileId for both distributorStoreId: 309 and distributorStoreId: 310 simultaneously.

Retrieving and Re-using New IDs

If a profileId for an artist has already been generated by a DSP, you must retrieve and use it for all subsequent releases. Failing to provide the existing ID will cause a second, duplicate profile to be generated for the artist, splitting their catalog.

Before distributing a new release for an artist who was previously new to a DSP, follow these steps:

Retrieve the Artist’s Current Data: Use the GET /content/artist/{artistId} endpoint. The response will include the most up-to-date artistExternalIds array, including any newly generated IDs. See Artist Object.
Use the Current IDs: Provide the full, current artistExternalIds array in your POST /content/release/save request.

Do not continuously poll our system for new IDs. Only run the GET request immediately before distributing a new release that requires the ID. A profileId may never be generated for various reasons (e.g., a Spotify release does not go live).

Adding/Editing Publishers

A publisher is a metadata entity that is referenced in assets (releases and tracks).

POST `/content/publisher/save`

Creates a new publisher or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.

June 25, 2025

When a new Publisher is created implicitly as part of saving a Release or Track, its enterpriseId will automatically be set to match the enterpriseId of that Release or Track.

This is a change from previous behavior where the new publisher would inherit the enterpriseId of the currently authenticated user’s session. This new behavior ensures that implicitly created publishers are correctly associated with the enterprise context of the asset they are first introduced with.

When managing Publishers directly via the /content/publisher/save endpoint, you have more explicit control over the enterpriseId as described in the parameters for this endpoint.

When assigning existing contact, only contactId on additionalContacts object is required.

Request Body

Parameter	Type	Description
`publisherId` optional	Integer	ID for an existing publisher. Required when editing publisher, should be ommited or set to `0` when creating new publisher.
`name` required	string	Full name of the publisher.
`ipiCae` optional	string	IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations.
`image` optional	object	The image representing the publisher. See File Object.
`image.fileId` required	string	The ID of the previously uploaded file. Required when image object is present.
`image.filename` required	string	Name of the previously uploaded file with extension.
`proAffiliations` optional	array of objects	A list detailing the Performance Rights Organizations (PROs) affiliations.
`proAffiliations.proId` required	integer	Our internal ID linking to the `mechanicalPros` entity.
`proAffiliations.memberId` required	string	Unique ID issued by PRO. Unique across composers and publishers for the same tenant.
`additionalContacts` optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
`website` optional	string	Publisher’s website.
`countryId` optional	integer	Country where this publisher administers publishing rights and collects royalties.
`enterpriseId` optional	integer	Specifies the target enterprise ID for the publisher. Usage Context: Primarily used by parent enterprise users to manage publishers within one of their child enterprises. During Creation (when `publisherId` is omitted or 0): If the authenticated user is from a child enterprise: This field is optional. If omitted, the publisher is created in the user’s own enterprise. If provided, it must match the user’s enterprise ID. If the authenticated user is from a parent enterprise: This field is required to specify the target child enterprise for creation. Omitting it will result in an error. During Update (when a valid `publisherId` is provided): If the authenticated user is from a child enterprise: This field is generally ignored, as the update targets the specific publisher ID which already exists within their enterprise. If the authenticated user is from a parent enterprise: This field is ignored. The update targets the publisher identified by `publisherId` regardless of which child enterprise it belongs to (assuming the parent has access).

Example

↓

Request

curl -X POST 'http://api.revelator.com/content/publisher/save' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-d '{
  "publisherId": 0,
  "name": "Example Publisher",
  "ipiCae": "0000000111",
  "image": {
    "fileId": "00000000-0000-0000-a7d1-aaab06776049",
    "filename": "photo.jpg"
  },
  "proAffiliations": [],
  "additionalContacts": [
    {
        "contactId": 796718
    },
    {
        "name": "Booking Manager",
        "email": "[email protected]",
        "contactRoleId": 5
    }
  ],
  "website": "https://hello.com",
  "countryId": 875
}'

Retrieving Publishers

Use the following endpoints to retrieve publisher data.

GET `/content/publisher/all`

Retrieves a paginated list of all publishers in the account, with options for sorting and searching.

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve. Default is `1`.
`pageSize` optional	integer	The number of items to return per page. Default is `24`. Requires `pageNumber` query parameter to work properly.
`orderByProperty` optional	string	The property to sort the results by. Available options: name publisherId ipiCae creationDate
`orderByDescending` optional	boolean	If `false`, orders the results in ascending order. If `true` or omitted, orders in descending order.
`searchText` optional	string	A search term to filter publishers by name. The search is case-insensitive.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/publisher/all?pageNumber=1&pageSize=10&orderByProperty=name&orderByDescending=true'

Response

{
    "totalItemsCount": 24,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "publisherId": 1,
            "name": "Example Publisher",
            "ipiCae": "11111111111",
            "image": {
                "fileId": "00000000-0000-0000-0000-00000000",
                "isTemp": false,
                "filename": "photo.jpg",
                "externalUrl": null,
                "lastUpdateDate": "2032-04-14T14:12:37.097"
            },
            "proAffiliations": [],
            "additionalContacts": [],
            "worksCount": 0,
            "creationDate": "2020-05-23T19:06:44",
            "website": null,
            "countryId": 875
        },
        {
            "publisherId": 2,
            "name": "Example Publisher 2",
            "ipiCae": null,
            "image": null,
            "proAffiliations": [],
            "additionalContacts": [],
            "worksCount": 17,
            "creationDate": "2032-10-17T05:59:42",
            "website": "https://example.com",
            "countryId": 443
        },
    ],
    "additionalCounters": null
}

GET `/content/publisher/all/summary`

Retrieves a summarized list of publishers. Allows for searching and limiting results.

Query params

Parameter	Type	Description
`query` optional	string	A search term to filter publishers by name. The search is case-insensitive.
`limit` optional	integer	The maximum number of summary items to return.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/publisher/all/summary?query=Publi&limit=1'

Response

[
    {
        "publisherId": 1111,
        "name": "Publisher",
        "ipiCae": null,
        "image": null,
        "proAffiliations": [],
        "additionalContacts": [],
        "worksCount": 10,
        "creationDate": "2021-10-06T10:46:16.483",
        "website": null,
        "countryId": 875
    }
]

GET `/content/publisher/{publisherId}`

Retrieves detailed information for a specific publisher by its publisherId.

Path Parameters

Parameter	Type	Description
`publisherId`	integer	The unique ID of the publisher to retrieve.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/publisher/12345'

Response

{
    "publisherId": 12345,
    "name": "Publisher Name",
    "ipiCae": "111111111",
    "image": null,
    "proAffiliations": [],
    "additionalContacts": [],
    "worksCount": 0,
    "creationDate": "2020-05-23T19:06:44",
    "website": null,
    "countryId": 875
}

Adding/Editing Composers

A composer(writer) is a metadata entity that is referenced in assets (releases and tracks).

POST `/content/composer/save`

Creates a new composer or updates an existing one. The target enterprise for the operation can be specified if the authenticated user has appropriate parent/child account permissions.

When a new Composer is created implicitly as part of saving a Release or Track, its enterpriseId will automatically be set to match the enterpriseId of that Release or Track.

This is a change from previous behavior where the new composer would inherit the enterpriseId of the currently authenticated user’s session. This new behavior ensures that implicitly created composers are correctly associated with the enterprise context of the asset they are first introduced with.

When managing Composers directly via the /content/composer/save endpoint, you have more explicit control over the enterpriseId as described in the parameters for this endpoint.

When assigning existing contact, only contactId on additionalContacts object is required.

Request Body

Parameter	Type	Description
`composerId` optional	Integer	ID for an existing composer. Required when editing composer, should be ommited or set to `0` when creating new composer.
`name` required	string	Composer’s full legal name exactly as shown on official paperwork (e.g., contracts, copyright registrations).
`isni` optional	string	The International Standard Name Identifier (ISNI) for the artist. Must be exactly 16 alphanumeric characters, where the last character can also be ‘X’.
`ipiCae` optional	string	IPI (Interested Parties Information) - CAE (Composer, Author, and Publisher) number. Exactly 9 digits (IPI) or 11 digits (CAE). Unique across publishers and composers (writers) in the same tenant if present. Used to identify publishers across rights organizations.
`biography` optional	string	Composers’s biography.
`countryOfResidenceId` optional	integer	The country in which this contributor officially resides. Used for legal and payout requirements.
`composersLocals` optional	array of objects	A list of Composer’s name in different languages.
`composersLocals.name` required	string	Composer’s name in the indicated language.
`composersLocals.languageId` required	integer	Language ID indicating the language of the name. Each language can be used only once in the array. Updates to local names are based on this field. If you don’t inclde object with specified `languageId` entry with it will be deleted.
`image` optional	object	The image representing the publisher. See File Object.
`image.fileId` required	string	The ID of the previously uploaded file. Required when image object is present.
`image.filename` required	string	Name of the previously uploaded file with extension.
`proAffiliations` optional	array of objects	A list detailing the Performance Rights Organizations (PROs) affiliations.
`proAffiliations.proId` required	integer	Our internal ID linking to the `mechanicalPros` entity.
`proAffiliations.memberId` required	string	Unique ID issued by PRO. Unique across composers and publishers for the same tenant.
`additionalContacts` optional	array of objects	Array of Contact objects. Details about contacts can be found in the Adding/Editing Contacts section.
`enterpriseId` optional	integer	Specifies the target enterprise ID for the composer. Usage Context: Primarily used by parent enterprise users to manage composers within one of their child enterprises. During Creation (when `composerId` is omitted or 0): If the authenticated user is from a child enterprise: This field is optional. If omitted, the composer is created in the user’s own enterprise. If provided, it must match the user’s enterprise ID. If the authenticated user is from a parent enterprise: This field is required to specify the target child enterprise for creation. Omitting it will result in an error. During Update (when a valid `composerId` is provided): If the authenticated user is from a child enterprise: This field is generally ignored, as the update targets the specific composer ID which already exists within their enterprise. If the authenticated user is from a parent enterprise: This field is ignored. The update targets the composer identified by `composerId` regardless of which child enterprise it belongs to (assuming the parent has access).

Example

↓

Request

curl -X POST 'http://api.revelator.com/content/publisher/save' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer c1234562-5f45-4ab6-b8fb-812345c3e4d4' \
-d '{
  "composerId": 0,
  "name": "Example Composer",
  "isni": "123456789098765X",
  "ipiCae": "00000001111",
  "biography": "Composer's biography",
  "countryOfResidenceId": 244,
  "composersLocals":[
    {
      "name": "Local Composer Name",
      "languageId": 4
    }
  ],
  "image": {
    "fileId": "00000000-0000-0000-a7d1-aaab06776049",
    "filename": "photo.jpg"
  },
  "proAffiliations": [],
  "additionalContacts": [
    {
        "contactId": 796718
    },
    {
        "name": "Booking Manager",
        "email": "[email protected]",
        "contactRoleId": 5
    }
  ]
}'

Response

{
  "composerId": 0,
  "name": "string",
  "isni": "string",
  "ipiCae": "string",
  "biography": "string",
  "countryOfResidenceId": 0,
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-13T06:52:11.114Z"
  },
  "worksCount": 0,
  "contributorRoleIds": [
    0
  ],
  "creationDate": "2025-06-13T06:52:11.114Z",
  "publishersCount": 0,
  "composersLocals": [
    {
      "composerId": 0,
      "name": "string",
      "languageId": 0
    }
  ],
  "additionalContacts": [
    {
      "contactId": 0,
      "name": "string",
      "currencyCode": "string",
      "phone": "string",
      "email": "string",
      "address": "string",
      "address2": "string",
      "zipcode": "string",
      "countryId": 0,
      "imageId": "00000000-0000-0000-0000-000000000000",
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.114Z"
      },
      "isActive": true,
      "labelId": 0,
      "publisherId": 0,
      "artistId": 0,
      "city": "string",
      "state": "string",
      "location": "string",
      "contactRoleId": 0
    }
  ],
  "proAffiliations": [
    {
      "proId": 0,
      "memberId": "string"
    }
  ]
}

Retrieving Composers

Use the following endpoints to retrieve composer data.

GET `/content/composer/all`

Retrieves a paginated list of all composers in the account, with options for sorting and searching.

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve. Default is `1`.
`pageSize` optional	integer	The number of items to return per page.
`orderByProperty` optional	string	The property to sort the results by. Available options: name composerId ipiCae isni creationDate email
`orderByDescending` optional	boolean	If `false`, orders the results in ascending order. If `true` or omitted, orders in descending order.
`searchText` optional	string	A search term to filter composer by name. The search is case-insensitive.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/composer/all?pageNumber=1&pageSize=10&orderByProperty=name&orderByDescending=true'

Response

{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "composerId": 0,
      "name": "string",
      "isni": "string",
      "ipiCae": "string",
      "biography": "string",
      "countryOfResidenceId": 0,
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.111Z"
      },
      "worksCount": 0,
      "contributorRoleIds": [
        0
      ],
      "creationDate": "2025-06-13T06:52:11.111Z",
      "publishersCount": 0,
      "composersLocals": [
        {
          "composerId": 0,
          "name": "string",
          "languageId": 0
        }
      ],
      "additionalContacts": [
        {
          "contactId": 0,
          "name": "string",
          "currencyCode": "string",
          "phone": "string",
          "email": "string",
          "address": "string",
          "address2": "string",
          "zipcode": "string",
          "countryId": 0,
          "imageId": "00000000-0000-0000-0000-000000000000",
          "image": {
            "fileId": "00000000-0000-0000-0000-000000000000",
            "isTemp": true,
            "filename": "string",
            "externalUrl": "string",
            "lastUpdateDate": "2025-06-13T06:52:11.111Z"
          },
          "isActive": true,
          "labelId": 0,
          "publisherId": 0,
          "artistId": 0,
          "city": "string",
          "state": "string",
          "location": "string",
          "contactRoleId": 0
        }
      ],
      "proAffiliations": [
        {
          "proId": 0,
          "memberId": "string"
        }
      ]
    }
  ],
  "additionalCounters": {}
}

GET `/content/composer/all/summary`

Retrieves a summarized list of composers. Allows for searching and limiting results.

Query params

Parameter	Type	Description
`query` optional	string	A search term to filter composers by name. The search is case-insensitive.
`limit` optional	integer	The maximum number of summary items to return.
`enterpriseId` optional	integer	Used when executing from parent account to return composers from intended child account.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/composer/all/summary?query=Test&limit=1&enterpriseId=12'

Response

[
  {
    "composerId": 0,
    "name": "string",
    "composersLocals": [
      {
        "composerId": 0,
        "name": "string",
        "languageId": 0
      }
    ],
    "imageId": "00000000-0000-0000-0000-000000000000"
  }
]

GET `/content/composer/{composerId}`

Retrieves detailed information for a specific composer by its composerId.

Path Parameters

Parameter	Type	Description
`composerId`	integer	The unique ID of the composer to retrieve.

Example

↓

Request

curl -X GET 'http://api.revelator.com/content/composer/12345'

Response

{
  "composerId": 0,
  "name": "string",
  "isni": "string",
  "ipiCae": "string",
  "biography": "string",
  "countryOfResidenceId": 0,
  "image": {
    "fileId": "00000000-0000-0000-0000-000000000000",
    "isTemp": true,
    "filename": "string",
    "externalUrl": "string",
    "lastUpdateDate": "2025-06-13T06:52:11.117Z"
  },
  "worksCount": 0,
  "contributorRoleIds": [
    0
  ],
  "creationDate": "2025-06-13T06:52:11.117Z",
  "publishersCount": 0,
  "composersLocals": [
    {
      "composerId": 0,
      "name": "string",
      "languageId": 0
    }
  ],
  "additionalContacts": [
    {
      "contactId": 0,
      "name": "string",
      "currencyCode": "string",
      "phone": "string",
      "email": "string",
      "address": "string",
      "address2": "string",
      "zipcode": "string",
      "countryId": 0,
      "imageId": "00000000-0000-0000-0000-000000000000",
      "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": true,
        "filename": "string",
        "externalUrl": "string",
        "lastUpdateDate": "2025-06-13T06:52:11.117Z"
      },
      "isActive": true,
      "labelId": 0,
      "publisherId": 0,
      "artistId": 0,
      "city": "string",
      "state": "string",
      "location": "string",
      "contactRoleId": 0
    }
  ],
  "proAffiliations": [
    {
      "proId": 0,
      "memberId": "string"
    }
  ]
}

Getting Started

Distribution

Catalog management

Adding/Editing Releases

Important Considerations for Creating Releases

Track Association and Uniqueness (Single Release per Track ID)

Global UPC Uniqueness

Creating Compilation Releases

POST /content/release/save

Request Body

Request

Artist Object

File Object

Audio File Object

Track Object

New track recording model (Dolby Atmos Support)

Uploading Files

POST /media/audio/upload

Form Data

Response

POST /media/audio/upload/wav

POST /media/audio/upload/flac

POST /media/image/upload

Query Params

Form Data

Response

POST /media/audio/pullexternal/wav

Request Body

Response

Retrieving Releases

GET /content/release/all

Query params

Request

Response

GET /content/release/all/summary

Query params

Request

Response

GET /content/release/{releaseId}

Request

Response

Adding/Editing Artists

POST /artists

Request Body

Retrieving Artists

GET /artists

Query params

Request

Response

GET /artists/summary

GET /artists/{artistId}

Query params

GET /content/artist/all

Query params

Request

Response

Managing External Artist IDs

Providing artistExternalIds

Handling New Artists (Empty or Missing Profile IDs)

Retrieving and Re-using New IDs

Adding/Editing Publishers

POST /content/publisher/save

Request Body

Request

Retrieving Publishers

GET /content/publisher/all

Query params

Request

Response

GET /content/publisher/all/summary

Query params

Request

Response

GET /content/publisher/{publisherId}

Path Parameters

Request

Response

Adding/Editing Composers

POST /content/composer/save

Request Body

Request

Response

POST `/content/release/save`

POST `/media/audio/upload`

POST `/media/audio/upload/wav`

POST `/media/audio/upload/flac`

POST `/media/image/upload`

POST `/media/audio/pullexternal/wav`

GET `/content/release/all`

GET `/content/release/all/summary`

GET `/content/release/{releaseId}`

POST `/artists`

GET `/artists`

GET `/artists/summary`

GET `/artists/{artistId}`

GET `/content/artist/all`

Providing `artistExternalIds`

POST `/content/publisher/save`

GET `/content/publisher/all`

GET `/content/publisher/all/summary`

GET `/content/publisher/{publisherId}`

POST `/content/composer/save`

GET `/content/composer/all`

GET `/content/composer/all/summary`

GET `/content/composer/{composerId}`