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. This endpoint allows you to:

Manage release metadata and uploaded files
Create new tracks and assign them to a release
Assign existing tracks to a release

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 reviewing the request body, please read these key requirements and rules that affect release creation and validation.

Track Association and Reuse

As of November 26, 2025, a single trackId can be assigned to multiple releases. This includes using the same track across singles, albums, compilations, and any other release types.

Current Behavior

A track entity (identified by trackId) can appear on any number of releases.
Each release may reference both new and existing tracks.
Reusing the same ISRC across multiple releases no longer requires creating duplicate track entities.

Important Limitation: Locked Releases

A track becomes read-only when it belongs to a release in a fully locked distribution status (see Distribution Statuses: -10, -11, -20, -21).

Child enterprise users cannot modify tracks associated with fully locked releases.
Parent enterprise users may modify these tracks except when the release is in status -20 (Pending Owner Inspection).

Using Locked Tracks on Other Releases

When assigning a fully locked track to another release:

The release save operation will succeed.
Any attempted changes to that track’s metadata (e.g., changing the name) will be ignored.
The track becomes editable again only when none of the releases referencing it are in a fully locked state.

How to Identify Which Releases Use a Track

When retrieving either a release or a track (GET /content/release/{releaseId} or GET /content/track/{trackId}), each track includes a releaseTracks array that lists all release associations:

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

This object allows you to:

See all releases that include the track (releaseId).
Check platform-specific IDs per release (e.g., spotifyId, appleId).
Determine whether any connected release is currently fully locked - which directly affects whether the track is editable.

Global UPC Uniqueness

UPCs must be unique across the entire Revelator system.

However, sandbox accounts are excluded from UPC uniqueness validation:

UPCs used in a sandbox can be reused in production.
UPCs can be duplicated across multiple sandbox releases without validation errors.

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, often differentiating between the strict industry “Various Artists” standard and platform-specific flags.

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 (Various Artists) Our system determines if a release qualifies as the industry standard “Various Artists” compilation based on the absence of a main release artist and the count of primary artist contributors (roleId = 49) across the 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.
- Note: If the requirements for “Various Artists” are met, the isCompilation flag (detailed below) is ignored, as the stricter “Various Artists” logic takes precedence.
The isCompilation Flag (Platform-Specific) The isCompilation boolean flag (detailed in the Request Body) allows you to mark a release as a compilation even if it does not meet the “Various Artists” threshold (e.g., a “Best Of” by a single artist, or a release with 2-3 artists).
- Platform Scope: This flag relies on specific metadata rules (currently DDEX 4.3). For the time being, only Spotify supports this logic. Other platforms, such as Apple, still enforce the strict “Various Artists” rules regardless of this flag.
- Default Behavior: For DSPs that do not utilize this flag, the release will be delivered as an Album, Single, or EP based on the track count and metadata.

POST `/content/release/save`

November 3, 2025

Effective December 17, 2025, the data type for the upc property will change from number to string across all endpoints.

Integrators must update their code to handle the UPC field as a string value to avoid potential parsing errors.

For full details, see the Changelog entry.

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` optional	array of objects	Release details in different languages. Each object in the array represents the details in a different language.
`releasesLocals.name` optional	string	Name (title) in the indicated language. If omitted, this localization entry is ignored.
`releasesLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`releasesLocals.version` optional	string	Version in the indicated language.
`releasesLocals.phoneticVersion` optional	string	Phonetic pronunciation of the version in the indicated language.
`releasesLocals.languageId` optional	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 omitted, this localization entry is ignored. Lookup up the `languageId` using the `GET /common/lookup/languages` resource.
`artistLocals` optional	array of objects	Artist name(s) in different languages. Each object represents a name in a different language.
`artistLocals.name` optional	string	Name in the indicated language. If omitted, this localization entry is ignored.
`artistLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`artistLocals.languageId` optional	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 omitted, this localization entry is ignored. 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.
`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.
`isCompilation` optional	boolean	Indicates if the release should be treated as a compilation. Defaults to `false` if omitted. If set to `true`, the `releaseTypeId` in the response will automatically be set to `6` (Compilation). This flag is primarily used for releases that should be marked as compilations but do not meet the “Various Artists” criteria (e.g., “Best Of” by a single artist). Note on Support: Currently, only Spotify utilizes this flag for distribution via DDEX 4.3; other DSPs typically enforce the stricter “Various Artists” rules. If the release meets the system’s “Various Artists” validation rules (no main `artistId` and 4 or more primary artists), the `isCompilation` flag is ignored.
`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": [],
    "isCompilation": false,
    "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(s) in different languages. Each object represents a name in a different language.
`artistLocals.name` optional	string	Name in the indicated language. If omitted, this localization entry is ignored.
`artistLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`artistLocals.languageId` optional	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 omitted, this localization entry is ignored. 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

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 details in different languages. Each object in the array represents the details in a different language.
`tracksLocals.name` optional	string	Name (title) in the indicated language. If omitted, this localization entry is ignored.
`tracksLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`tracksLocals.version` optional	string	Version in the indicated language.
`tracksLocals.phoneticVersion` optional	string	Phonetic pronunciation of the version in the indicated language.
`tracksLocals.languageId` optional	integer	Language ID indicating the language of the entry. Each language can be used only once in the array. Updates to local names are based on this field. If omitted, this localization entry is ignored. Lookup up the `languageId` using the GET `/common/lookup/languages` resource.
`artistLocals` optional	array of objects	Artist name(s) in different languages. Each object represents a name in a different language.
`artistLocals.name` optional	string	Name in the indicated language. If omitted, this localization entry is ignored.
`artistLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`artistLocals.languageId` optional	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 omitted, this localization entry is ignored. 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.
`discNumber` optional	integer	Specifies the disc number to which a track belongs within a disc release. Track numbering is independent for each disc. The order of tracks in the `tracks` array payload determines their sequential order on the release. Validation Rules: Max Discs: A release can have a maximum of `10` discs. Consistency: Within a release, all tracks must either have a `discNumber` (starting from `1`) or none of them (`discNumber=null`). Mixed usage is not allowed. Sequential Discs: Disc numbers must be sequential and incremental. For example, you cannot have tracks on disc `1` and disc `3` without also having tracks on disc `2`. Immutable on Distributed Releases: The total number of discs (`discNumber` values) on a distributed release cannot be altered. Important note: The `discNumber` metadata is always included in the delivery; however, some DSPs may not support or display this information.
`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`. Used only when `publisherId` = `0`. When `publisherId` = `0`: The system performs a case-insensitive search for an existing publisher with this name. If a match is found, the composer is associated with it, and the existing publisher’s name is updated to exactly match the provided `publisherName` (e.g., “Universal” → “universal”). If no match is found, a new publisher is created using the provided name. When `publisherId` != `0`: The `publisherName` is ignored; only the ID is used for association. When `publisherId` is omitted or `null`: The publisher entry is skipped entirely.
`composerContentsDTO.publisherId` optional*	integer	ID of the publisher to assign to the composer. Only relevant when `rightsId` is `2`. Non-zero value: Associates the composer with the existing publisher of that ID. The provided `publisherName` (if any) is ignored. Value = 0: Enables the “find or create” logic using the provided `publisherName` - attempting to locate an existing publisher (case-insensitive) or create one if not found. The existing name may be updated to match the provided case. Omitted or `null`: The entire publisher entry is omitted (no publisher assigned). *To trigger the search or creation logic, set `publisherId` to `0` and provide a valid `publisherName`.
`composerContentsDTO.composersLocals` optional	array of objects	A list of Composer’s name in different languages.
`composerContentsDTO.composersLocals.name` required	string	Composer’s name in the indicated language.
`composerContentsDTO.composersLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`composerContentsDTO.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 include `languageId` withing an object, it will result in an error.
`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 applies to both audio and image assets.

POST `/media/audio/upload`

Uploads WAV or FLAC audio files.

All uploaded audio files must be longer than 2 seconds. Invalid files will be rejected.

The request must use the multipart/form-data content type.

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, used to reference it within the application.
`filename`	string	The name 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`

Uploads image files.

The request must use the multipart/form-data content type.

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	Whether the image is used as cover art.

Form Data

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

Response

The response returns a single string - the ID of the uploaded file.

"2b0b8df2-9a9a-4e9a-91b3-f0d442dbb7b1"

POST `/media/audio/pullexternal/wav`

Uploads audio files directly from a publicly available URL. This can be useful if the file is already hosted or if you prefer not to handle the upload manually.

All uploaded audio files must be longer than 2 seconds. Invalid files will be rejected.

You can use expiring links for security purposes, as long as the file remains accessible at the time of upload.

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. Must include the file extension (e.g., `my-track.wav`).

Response

Field	Type	Description
`fileId`	string	The ID of the uploaded file, used to reference it within the application.
`filename`	string	The name of the uploaded file.

Retrieving Releases

Use the following endpoints to retrieve release data.

November 3, 2025

Effective December 17, 2025, the data type for the upc property will change from number to string across all endpoints.

Integrators must update their code to handle the UPC field as a string value to avoid potential parsing errors.

For full details, see the Changelog entry.

By default, these endpoints return all releases the user has permission to view, not just the ones within the user’s own account. Parent account users will receive releases from all associated child accounts.

When using multiple filters of the same type, provide each property separately. For example: labels=2391&labels=8902.

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
6 - Compilation

Some endpoints may also include an additionalCounters object. This object contains counts of release types that match the search criteria but were not included in the returned list due to pagination or applied filters.

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.
`distributionStatus` optional	array	An array of distribution status IDs used to filter releases. Only releases matching one of the provided status IDs will be returned. See Distribution Statuses for ID definitions.
`isLocked` optional	boolean	Filters releases based on their `isLockedForDistribution` flag. If `true`, returns only releases that are locked for distribution, meaning they have been successfully distributed or submitted to DSPs at some point. If `false`, returns only releases that are not locked for distribution. If omitted, returns all releases (both locked and not locked). Important Note: The returned value of the `isLockedForDistribution` property within the response items of this endpoint may be unreliable (it can incorrectly display `false`). To confirm the definitive locked status for any individual release, use the dedicated `/content/release/{releaseId}` endpoint.
`releaseTypes` optional	array	An array of release type IDs (`1`: Album, `2`: Single, `4`: EP, `6`: Compilation) to filter releases. Example: To filter for `releaseTypes=[4, 6]`, your query string would look like this: `?releaseTypes%5B0%5D=6&releaseTypes%5B1%5D=4`
`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 single exact UPC match.
`upcs` optional	array	Filters releases by multiple UPCs. Each UPC must match exactly. The filter behaves as an OR search - releases matching any of the provided UPCs are included. UPC values that do not match any release are simply ignored.
`isCompilation` optional	boolean	Filters releases based on their `isCompilation` flag. If `true`, returns only releases marked as compilations. If `false`, returns only releases not marked as compilations. If omitted, returns all releases (both compilations and non-compilations).
`archived` optional	boolean	Filters releases based on their archive status. If `true`, returns only archived releases. If `false`, returns only unarchived releases. If omitted, returns all releases (both archived and unarchived).
`archivedFrom` optional	date-time	Returns releases whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns releases whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

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,
            "isCompilation": false,
            "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": [],
            "archivedAt": "2024-10-26T00:00:00"
        }
    ],
    "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, `6`: Compilation) to filter releases. Example: To filter for `releaseTypes=[4, 6]`, your query string would look like this: `?releaseTypes%5B0%5D=6&releaseTypes%5B1%5D=4`
`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.
`upcs` optional	array	Filters releases by multiple UPCs. Each UPC must match exactly. The filter behaves as an OR search - releases matching any of the provided UPCs are included. UPC values that do not match any release are simply ignored.
`isCompilation` optional	boolean	Filters releases based on their `isCompilation` flag. If `true`, returns only releases marked as compilations. If `false`, returns only releases not marked as compilations. If omitted, returns all releases (both compilations and non-compilations).
`archived` optional	boolean	Filters releases based on their archive status. If `true`, returns only archived releases. If `false`, returns only unarchived releases. If omitted, returns all releases (both archived and unarchived).
`archivedFrom` optional	date-time	Returns releases whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns releases whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

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,
        "isCompilation": false,
        "contributors": [],
        "archivedAt": "2024-10-26T00:00:00"
    },
]

GET `/content/release/{releaseId}`

Retrieves a release by its unique releaseId.

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,
    "isCompilation": 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,
    "archivedAt": "2024-10-26T00:00:00"
}

Retrieving Tracks

Use the following endpoints to retrieve track data.

By default, these endpoints return all tracks the user has permission to view, not just the tracks in the user’s account. A parent account user will receive tracks from every associated child account.

GET `/content/track/all`

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

When using multiple filters of the same type, provide each property separately. For example: artists=2384320&artists=1628168.

Query params

Parameter	Type	Description
`pageNumber` optional	integer	The page number of the results to retrieve. Default: `1`.
`pageSize` optional	integer	The maximum number of items to return per page. Default: `10`.
`orderByProperty` optional	string	The property to sort the results by. Available options: `name` `artistName` `releasescount` `creationDate`
`orderByDescending` optional	boolean	If `true`, orders the results in descending order. If `false` or omitted, orders in ascending order.
`searchText` optional	string	A case-insensitive search term to filter tracks by name or artist name.
`fromDate` optional	date-time	Returns tracks created on or after this date (ISO 8601 format: `YYYY-MM-DDTHH:MM:SS`).
`toDate` optional	date-time	Returns tracks created on or before this date (ISO 8601 format: `YYYY-MM-DDTHH:MM:SS`).
`artists` optional	array	One or more artist IDs. Returns only tracks where the provided artist ID is the main primary artist of the track.
`labels` optional	array	Label IDs to filter tracks by.
`enterprises` optional	array	Enterprise IDs to filter tracks by. Only relevant for parent account users.
`musicStyles` optional	array	Music Style IDs to filter tracks associated with any of the specified music styles (primary or secondary).
`languages` optional	array	Language IDs to filter tracks by.
`isrcs` optional	array	Filters tracks by multiple ISRCs. Each ISRC must match exactly. The filter behaves as an OR search - tracks matching any of the provided ISRCs are included. ISRC values that do not match any track are simply ignored.
`isHighResolution` optional	boolean	Filters tracks based on audio resolution: If `true`, returns only Hi-Res tracks. If `false`, returns only non Hi-Res tracks. If omitted, returns all tracks (both Hi-Res and non Hi-Res).
`isMissingAudioFile` optional	boolean	Filters tracks without audio files: If `true`, returns only tracks without audio files. If `false`, returns only tracks with audio files. If omitted, returns all tracks (both with and without audio files).
`recordingVersionType` optional	string	Filters tracks by the type of audio recording version available: If `DolbyAtmos`, returns only tracks with Dolby Atmos audio. If `Stereo`, returns only tracks with Stereo audio. If omitted, returns all tracks, regardless of version type.
`archived` optional	boolean	Filters tracks based on their archive status: If `true`, returns only archived tracks. If `false`, returns only unarchived tracks. If omitted, returns all tracks (both archived and unarchived).
`archivedFrom` optional	date-time	Returns tracks whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns tracks whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

Example

Request

curl -X GET
'https://api.revelator.com/content/track/all?pageNumber=1&pageSize=10&searchText=title'

Response

{
    "totalItemsCount": 20,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "trackId": 123456,
            "name": "Title",
            "artistId": 12345,
            "artistName": "Artist Name",
            "trackLength": 154,
            "trackVendorId": null,
            "isrc": null,
            "iswcs": [],
            "description": null,
            "languageId": 65,
            "explicit": true,
            "version": "Live",
            "posterImageId": null,
            "wavFileId": "00000000-0000-0000-000000000000",
            "flacFileId": null,
            "assetId": 1352123,
            "image": null,
            "wav": {
                "fileId": "00000000-0000-0000-000000000000",
                "isTemp": false,
                "filename": "AudioFileName.wav",
                "externalUrl": null,
                "lastUpdateDate": "0001-01-01T00:00:00"
            },
            "flac": null,
            "primaryMusicStyleId": null,
            "secondaryMusicStyleId": null,
            "trackType": 2,
            "licenseRequestStatus": null,
            "isAudioValid": null,
            "catalog": null,
            "isFullyLocked": false,
            "enterpriseId": 129858,
            "enterpriseName": "Enterprise Name",
            "archivedAt": null,
            "releases": [],
            "monetizations": null,
            "royaltyToken": null,
            "acrCloud": null,
            "trackRecordingVersions": [
                {
                    "isrc": null,
                    "recordingVersionType": 1,
                    "audioFiles": [
                        {
                            "audioId": "00000000-0000-0000-000000000000",
                            "fileFormat": 1,
                            "audioFilename": "AudioFileName.wav",
                            "audioChannels": 2,
                            "audioBitDepth": 24,
                            "audioSampleRate": 48000,
                            "audioBitrate": 2307152,
                            "audioSeconds": 154,
                            "audioSize": 44136826
                        }
                    ]
                }
            ],
            "contributors": [
                {
                    "contributorId": "00000000-0000-0000-000000000000",
                    "roleId": 5,
                    "releaseId": null,
                    "trackId": 123456,
                    "artist": {
                        "artistId": 123556,
                        "name": "Artist Name",
                        "firstName": null,
                        "lastName": null,
                        "middleName": null,
                        "isni": null,
                        "releasesCount": 1,
                        "tracksCount": 4,
                        "archivedAt": null,
                        "image": null
                    }
                },
                {
                    "contributorId": "00000000-0000-0000-000000000000",
                    "roleId": 6,
                    "releaseId": null,
                    "trackId": 123564,
                    "artist": {
                        "artistId": 123555,
                        "name": "Artist Name 2",
                        "firstName": null,
                        "lastName": null,
                        "middleName": null,
                        "isni": null,
                        "releasesCount": 0,
                        "tracksCount": 1,
                        "archivedAt": null,
                        "image": {
                            "fileId": "00000000-0000-0000-000000000000",
                            "isTemp": false,
                            "filename": "profile.jpg",
                            "externalUrl": null,
                            "lastUpdateDate": "2024-07-04T20:38:10.917"
                        }
                    }
                }
            ]
        },
    ],
    "additionalCounters": null
}

GET `/content/track/all/summary`

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

Query params

Parameter	Type	Description
`query` optional	string	A search term to filter tracks by name. The search is case-insensitive.
`archived` optional	boolean	Filters tracks based on their archive status. If `true`, returns only archived tracks. If `false`, returns only unarchived tracks. If omitted, returns all tracks (both archived and unarchived).

Example

Request

curl -X GET
'https://api.revelator.com/content/track/all/summary?query=Track'

Response

[
    {
        "trackId": 123456,
        "name": "Track Title",
        "artistId": 366600,
        "artistName": "Artist Name",
        "isrc": null,
        "trackRecordingVersions": [
            {
                "isrc": null,
                "recordingVersionType": 1,
                "audioFiles": [
                    {
                        "audioId": "00000000-0000-0000-0000-000000000000",
                        "audioFilename": "AudioFileName.wav",
                        "fileFormat": 1
                    }
                ]
            }
        ],
        "version": "",
        "enterpriseName": "Enterprise Name",
        "enterpriseId": 223813,
        "assetId": 3224117,
        "releasesCount": 0,
        "archivedAt": null,
        "image": null
    },
]

GET `/content/track/{trackId}`

Retrieves a track by its unique trackId.

July 23, 2025

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

November 3, 2025

Effective December 17, 2025, the data type for the upc property will change from number to string across all endpoints.

Integrators must update their code to handle the UPC field as a string value to avoid potential parsing errors.

For full details, see the Changelog entry.

Example

Request

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

Response

{
    "enterpriseName": "Enterprise Name",
    "enterpriseId": 141898,
    "trackId": 1863548,
    "name": "Track Name",
    "artistId": 382319,
    "artistName": "Artist Name",
    "artistAppleId": null,
    "artistSpotifyId": null,
    "artistExternalIds": [],
    "labelId": 148196,
    "labelName": "Label Name",
    "discNumber": null,
    "trackLength": 205,
    "channels": 2,
    "sampleRate": 48000,
    "bitDepth": 16,
    "bitrate": 1536000,
    "trackVendorId": null,
    "isrc": "USQZ52500001",
    "version": null,
    "copyrightC": null,
    "copyrightP": "2020 Artist",
    "description": null,
    "languageId": 48,
    "explicit": true,
    "lyrics": null,
    "playingCount": 0,
    "priceTierId": null,
    "previewStartSeconds": null,
    "totalSales": 0.0,
    "image": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": false,
        "filename": null,
        "externalUrl": null,
        "lastUpdateDate": "2014-03-23T09:25:23.43"
    },
    "wav": {
        "fileId": "00000000-0000-0000-0000-000000000000",
        "isTemp": false,
        "filename": "AudioFileName.wav",
        "externalUrl": null,
        "lastUpdateDate": "0001-01-01T00:00:00"
    },
    "flac": null,
    "trackRecordingVersions": [
        {
            "isrc": "USQZ52500001",
            "recordingVersionType": 1,
            "audioFiles": [
                {
                    "audioId": "00000000-0000-0000-0000-000000000000",
                    "fileFormat": 1,
                    "audioFilename": "AudioFileName.wav",
                    "audioChannels": 2,
                    "audioBitDepth": 16,
                    "audioSampleRate": 48000,
                    "audioBitrate": 1536000,
                    "audioSeconds": 205,
                    "audioSize": 39484962
                }
            ]
        }
    ],
    "fileExtension": ".wav",
    "isLockedForDistribution": false,
    "isDolbyAtmosReadOnly": false,
    "primaryMusicStyleId": 16,
    "secondaryMusicStyleId": null,
    "previouslyReleased": false,
    "trackType": 0,
    "licenseRequestStatus": null,
    "isAudioValid": null,
    "tracksLocals": [
        {
            "trackId": 1863548,
            "name": "Localized Track Name",
            "phoneticName": null,
            "languageId": 50,
            "version": null,
            "phoneticVersion": null
        }
    ],
    "artistLocals": [
        {
            "artistId": 382319,
            "name": "Localized Artist Name",
            "phoneticName": null,
            "languageId": 50
        }
    ],
    "contributors": [],
    "catalog": null,
    "compositions": [],
    "releaseIds": [
        575296
    ],
    "releases": [
        {
            "releaseId": 575296,
            "name": "Release Name",
            "version": null,
            "releaseDate": null,
            "releaseTypeId": 4,
            "upc": 7290114249003.0,
            "isLockedForDistribution": false,
            "isDolbyAtmosReadOnly": false,
            "isIngested": false,
            "enterpriseName": "Enterprise Name",
            "enterpriseId": 141898,
            "assetId": 1748486,
            "image": {
                "fileId": "00000000-0000-0000-0000-000000000000",
                "isTemp": false,
                "filename": "CoverFileName.jpg",
                "externalUrl": null,
                "lastUpdateDate": "2020-08-25T08:06:24.27"
            },
            "artist": {
                "artistId": 382319,
                "name": "Artist Name",
                "firstName": null,
                "lastName": null,
                "middleName": null,
                "isni": null,
                "releasesCount": 4,
                "tracksCount": 12,
                "archivedAt": null,
                "image": null
            },
            "tracksCount": 6,
            "archivedAt": null,
            "isCompilation": false,
            "contributors": []
        }
    ],
    "composerContentsDTO": [
        {
            "contributorId": 1167888,
            "composerId": 442638,
            "composerName": "Composer Name",
            "composerImageId": null,
            "share": 100.00,
            "publisherId": null,
            "publisherName": "",
            "publisherAdminId": null,
            "publisherAdminName": null,
            "proId": null,
            "rightsId": 1,
            "proRegistrationId": null,
            "roleId": 2,
            "composersLocals": []
        }
    ],
    "isFullyLocked": false,
    "copyTrackId": null,
    "isIngested": false,
    "isLicensePaid": null,
    "distributorStoreGenreIds": [],
    "assetId": 3032257,
    "archivedAt": null,
    "monetizations": [],
    "acrCloud": null,
    "royaltyToken": null,
    "trackProperties": [
        1
    ],
    "releasesCount": 1,
    "spotifyId": null,
    "appleId": null,
    "rdioId": null,
    "releaseTracks": [
        {
            "releaseId": 575296,
            "spotifyId": null,
            "appleId": null,
            "rdioId": null,
            "deezerId": null
        }
    ]
}

Adding/Editing Artists

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

You don’t need to manually create artists before creating assets, unless you are performing an ingestion process (such as importing or creating an entire catalog) or creating “Various Artists” releases. For details, see Workflow: Importing an Existing Catalog or Creating New Release.

Artists can also be created automatically as part of the asset creation process — see Adding/Editing Releases. When editing an artist already associated with assets, all linked assets are updated automatically.

Due to DSP requirements, an artist cannot be listed as a primary artist twice, or appear as both a primary and featuring artist on the same track or release.

The Revelator API enforces this by returning an error if you attempt to set an artist as both the main primary artist (artistId / artistName) and as a contributor with a primary or featuring role.

POST `/artists`

Creates or edits artists within the account associated with the access token.

For Child Account implementations, you can also run this request on behalf of a child enterprise 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(s) in different languages. Each object represents a name in a different language.
`artistLocals.name` optional	string	Name in the indicated language. If omitted, this localization entry is ignored.
`artistLocals.phoneticName` optional	string	Phonetic pronunciation of the name in the indicated language.
`artistLocals.languageId` optional	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 omitted, this localization entry is ignored. 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.
`additionalContacts.contactId` optional	integer	The ID of an existing contact (omit or use `0` to create a new one).
`additionalContacts.name` optional	string	Full legal name of the contact.
`additionalContacts.email` optional	string	Contact email address.
`additionalContacts.contactRoleId` optional	integer	Role ID for the contact, obtained through `GET /common/lookup/contactRoles`.
`additionalContacts.phone` optional	string	Contact phone number.
`additionalContacts.address` optional	string	Primary address line 1.
`additionalContacts.address2` optional	string	Primary address line 2.
`additionalContacts.zipcode` optional	string	Zip/postal code.
`additionalContacts.countryId` optional	integer	Country ID for the contact’s address.
`additionalContacts.city` optional	string	City.
`additionalContacts.state` optional	string	State/Province.
`additionalContacts.location` optional	string	General location information.
`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.
`archived` optional	boolean	Filters artists based on their archive status. If `true`, returns only archived artists. If `false`, returns only unarchived artists. If omitted, returns all artists (both archived and unarchived).
`archivedFrom` optional	date-time	Returns artists whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns artists whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

Example

Request

curl -X GET '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"
      },
      "archivedAt": "2025-06-12T12:38:18.124Z"
    }
  ],
  "additionalCounters": {}
}

GET `/artists/summary`

Retrieves a summary of all artists in the account.

Query params

Parameter	Type	Description
`query` optional	string	A search term to filter artists by name. The search is case-insensitive.
`archived` optional	boolean	Filters artists based on their archive status. If `true`, returns only archived artists. If `false`, returns only unarchived artists. If omitted, returns all artists (both archived and unarchived).

Example

Request

curl -X GET 'http://api.revelator.com/artists/summary'

Response

[
    {
        "artistId": 503102,
        "name": "Artist Name",
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "isni": null,
        "releasesCount": 2,
        "tracksCount": 2,
        "archivedAt": null,
        "image": null
    }
]

GET `/artists/{artistId}`

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

Example

Request

curl -X GET 'http://api.revelator.com/artists/503102'

Response

{
    "artistLabels": [],
    "additionalContacts": [],
    "contributorRoleGroupIds": [
        1,
        3
    ],
    "hasPortal": false,
    "labelId": null,
    "labelName": "",
    "contactId": null,
    "contact": null,
    "biography": null,
    "yearsActive": [],
    "influencers": [],
    "contemporaries": [],
    "tags": [],
    "isSigned": false,
    "musicStyles": [],
    "artistExternalIds": [],
    "socialUrls": [],
    "artistLocals": [],
    "artistsWebsites": [],
    "webAlias": null,
    "enterpriseId": 129858,
    "activeFromDate": null,
    "activeToDate": null,
    "artistId": 503102,
    "name": "Artist name",
    "firstName": null,
    "lastName": null,
    "middleName": null,
    "isni": null,
    "releasesCount": 2,
    "tracksCount": 2,
    "archivedAt": null,
    "image": null
}

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.
`archived` optional	boolean	Filters artists based on their archive status. If `true`, returns only archived artists. If `false`, returns only unarchived artists. If omitted, returns all artists (both archived and unarchived).
`archivedFrom` optional	date-time	Returns artists whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns artists whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

Example

Request

curl -X GET '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"
      },
      "archivedAt": "2025-06-12T12:38:18.124Z"
    }
  ],
  "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)

October 15, 2025

Effective November 15, 2025, providing "0" as a value to indicate new profile creation will no longer be supported. To create a new profile, you must either omit the entry for the store or provide null.

For full details, see the Changelog entry.

When working with artistExternalIds, always provide a profileId if one already exists for the artist. If the artist is new to a DSP, you should either:

Omit the DSP entry entirely, or
Set the value to null

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 includes the most up-to-date artistExternalIds array, containing any newly generated IDs. See Artist Object for details.
Use the current IDs in your release request: Provide the complete artistExternalIds array in your POST /content/release/save request.
⚠️ Do not continuously poll for new IDs. Run the GET request only immediately before distributing a new release that requires the ID. A profileId may never be generated for some DSPs (e.g., if a Spotify release does not go live).

Adding/Editing Publishers

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

Enterprise ID Assignment (Implicit Creation)

When a new Publisher is created implicitly as part of saving a Release or Track (i.e., you include a new publisher in the asset payload):

The Publisher’s enterpriseId will automatically be set to match the enterpriseId of the Release or Track being saved.

When managing Publishers directly via the /content/publisher/save endpoint, you retain explicit control over the enterpriseId using the parameter detailed in the Request Body below.

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.

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.
`additionalContacts.contactId` optional	integer	The ID of an existing contact (omit or use `0` to create a new one).
`additionalContacts.name` optional	string	Full legal name of the contact.
`additionalContacts.email` optional	string	Contact email address.
`additionalContacts.contactRoleId` optional	integer	Role ID for the contact, obtained through `GET /common/lookup/contactRoles`.
`additionalContacts.phone` optional	string	Contact phone number.
`additionalContacts.address` optional	string	Primary address line 1.
`additionalContacts.address2` optional	string	Primary address line 2.
`additionalContacts.zipcode` optional	string	Zip/postal code.
`additionalContacts.countryId` optional	integer	Country ID for the contact’s address.
`additionalContacts.city` optional	string	City.
`additionalContacts.state` optional	string	State/Province.
`additionalContacts.location` optional	string	General location information.
`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-0000-000000000000",
    "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.
`archived` optional	boolean	Filters publishers based on their archive status. If `true`, returns only archived publishers. If `false`, returns only unarchived publishers. If omitted, returns all publishers (both archived and unarchived).
`archivedFrom` optional	date-time	Returns publishers whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns publishers whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

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,
            "archivedAt": "2020-05-23T19:06:44"
        },
        {
            "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,
            "archivedAt": "2020-05-23T19:06:44"
        },
    ],
    "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.
`archived` optional	boolean	Filters publishers based on their archive status. If `true`, returns only archived publishers. If `false`, returns only unarchived publishers. If omitted, returns all publishers (both archived and unarchived).

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,
        "archivedAt": "2020-05-23T19:06:44"
    }
]

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,
    "archivedAt": "2020-05-23T19:06:44",
}

Adding/Editing Composers

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

Enterprise ID Assignment (Implicit Creation)

When a new Composer is created implicitly as part of saving a Release or Track (i.e., you include a new composer in the asset payload):

The Composer’s enterpriseId will automatically be set to match the enterpriseId of the Release or Track being saved.

When managing Composers directly via the /content/composer/save endpoint, you retain explicit control over the enterpriseId using the parameter detailed in the Request Body below.

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.

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.phoneticName` optional	string	Phonetic pronunciation of the 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 include `languageId` withing an object, it will result in an error.
`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.
`additionalContacts.contactId` optional	integer	The ID of an existing contact (omit or use `0` to create a new one).
`additionalContacts.name` optional	string	Full legal name of the contact.
`additionalContacts.email` optional	string	Contact email address.
`additionalContacts.contactRoleId` optional	integer	Role ID for the contact, obtained through `GET /common/lookup/contactRoles`.
`additionalContacts.phone` optional	string	Contact phone number.
`additionalContacts.address` optional	string	Primary address line 1.
`additionalContacts.address2` optional	string	Primary address line 2.
`additionalContacts.zipcode` optional	string	Zip/postal code.
`additionalContacts.countryId` optional	integer	Country ID for the contact’s address.
`additionalContacts.city` optional	string	City.
`additionalContacts.state` optional	string	State/Province.
`additionalContacts.location` optional	string	General location information.
`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": [
    {
        "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.
`archived` optional	boolean	Filters composers based on their archive status. If `true`, returns only archived composers. If `false`, returns only unarchived composers. If omitted, returns all composers (both archived and unarchived).
`archivedFrom` optional	date-time	Returns composers whose `archivedAt` timestamp is on or after this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).
`archivedTo` optional	date-time	Returns composers whose `archivedAt` timestamp is on or before this date (ISO 8601: `YYYY-MM-DDTHH:MM:SS`).

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",
          "phoneticName": "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"
        }
      ],
      "archivedAt": "2025-06-13T06:52:11.117Z"
    }
  ],
  "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.
`archived` optional	boolean	Filters composers based on their archive status. If `true`, returns only archived composers. If `false`, returns only unarchived composers. If omitted, returns all composers (both archived and unarchived).

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",
        "phoneticName": "string",
        "languageId": 0
      }
    ],
    "imageId": "00000000-0000-0000-0000-000000000000",
    "archivedAt": "2025-06-13T06:52:11.117Z"
  }
]

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",
      "phoneticName": "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"
    }
  ],
  "archivedAt": "2025-06-13T06:52:11.117Z"
}

Archiving content

Archiving allows you to remove content and its associated entities from active use within your catalog.

You can view or restore archived assets using query parameters on supported endpoints or via dedicated unarchiving endpoints.

To exclude archived content from your query results, set the query parameter isArchived=false.

Additional details:

Archived content cannot be modified.
To edit any properties of an archived asset, you must first unarchive it.
Archived assets are excluded from the active catalog and cannot participate in catalog integrations or workflows.

After archiving, associated cover images and audio files are permanently deleted after 6 months. Once deleted, they cannot be restored.

You will receive an email notification two weeks prior to deletion.

POST `/releases/archive`

Archives one or more releases.

Prerequisites for Archiving a Release:

The release must not be currently archived.
The release must either have never been distributed, or be in one of the following terminal/inactive distribution statuses:
- -13: Rejected by Inspector
- 11: Encoding Audio Failed
- 21: Validation Failed
- 32: Package Creation Failed
- 42: Package Upload Failed
- 78: Takedown Delivered
- 79: Removed from Store
- Note: Processing releases (e.g., status 0, 4, 5, 8, 10, 20, 30, 31, 40, 41, 45, 46, 50, 60, 70, 71, 72, 75, 76, 77) cannot be archived.
Archiving a release will not automatically archive the tracks within it.

Each release has an assetId. You can retrieve this ID using endpoints like GET /content/release/all or GET /content/release/{id}.

Request Body

Parameter	Type	Description
`assetIds`	array of integers	An array of `assetId` values for releases to archive.

Example: Succesfully Archiving Releases

Request

curl -X POST 'https://api.revelator.com/releases/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Live Releases

Request

curl -X POST 'https://api.revelator.com/releases/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This release is live on YouTube Music and cannot be archived. Please request takedown from store(s) before attempting to archive."
                }
            ]
        }
    ]
}

POST `/tracks/archive`

Archives one or more tracks.

Prerequisites for Archiving a Track:

The track must not be currently archived.
The track must not be associated with any active (unarchived) releases. This implies that any associated releases must first be either unlinked from the track, or taken down from all stores and already archived.

Each track has an assetId. You can retrieve this ID using endpoints like GET /content/track/all or GET /content/track/{id}.

Request Body

Parameter	Type	Description
`assetIds`	array of integers	An array of `assetId` values for tracks to archive.

Example: Successfully Archiving Track

Request

curl -X POST 'https://api.revelator.com/releases/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Track on Active Release

Request

curl -X POST 'https://api.revelator.com/tracks/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 4389046,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This track cannot be archived because it has active release(s)."
                }
            ]
        }
    ]
}

POST `/artists/archive`

Archives one or more artists.

Prerequisites for Archiving an Artist:

The artist must not be currently archived.
The artist must not be a Main Primary Artist (MPA) on any active (unarchived) release.
The artist must not be a Main Primary Artist (MPA) on any active (unarchived) track.
The artist must not be a contributor on any active (unarchived) release.
The artist must not be a contributor on any active (unarchived) track.
The artist must not be set as the default artist on any enterprise.
Portal accounts will lose access to the artist once it is archived.

Request Body

Parameter	Type	Description
`artistIds`	array of integers	An array of `artistId` values for artists to archive.

Example: Successfully Archiving Artist

Request

curl -X POST 'https://api.revelator.com/artists/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Artist with Active Releases

Request

curl -X POST 'https://api.revelator.com/artists/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 512247,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This artist cannot be archived because it is assigned as main primary artist to active release(s)."
                }
            ]
        }
    ]
}

POST `/labels/archive`

Archives one or more labels.

Prerequisites for Archiving a Label:

The label must not be currently archived.
The label must not be assigned to any active (unarchived) release.
The label must not be assigned to any active (unarchived) track.
The label must not be assigned to any active (unarchived) artist.
The label must not be set as the default label on any enterprise.
Portal accounts will lose access to the label once it is archived.

Request Body

Parameter	Type	Description
`labelIds`	array of integers	An array of `labelId` values for labels to archive.

Example: Succesfully Archiving Label

Request

curl -X POST 'https://api.revelator.com/labels/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"labelIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Label with Active Releases

Request

curl -X POST 'https://api.revelator.com/labels/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"labelIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This label cannot be archived because it is assigned to active release(s)."
                }
            ]
        }
    ]
}

POST `/composers/archive`

Archives one or more composers.

Prerequisites for Archiving a Composer:

The composer must not be currently archived.
The composer must not be assigned to any active (unarchived) release.
The composer must not be assigned to any active (unarchived) track.

Request Body

Parameter	Type	Description
`composerIds`	array of integers	An array of `composerId` values for composers to archive.

Example: Successfully Archiving Composer

Request

curl -X POST 'https://api.revelator.com/composers/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"composerIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Composer with Active Track

Request

curl -X POST 'https://api.revelator.com/composers/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"composerIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This composer cannot be archived because it is assigned to active track(s)."
                }
            ]
        }
    ]
}

POST `/publishers/archive`

Archives one or more publishers.

Prerequisites for Archiving a Publisher:

The publisher must not be currently archived.
The publisher must not be assigned to any active (unarchived) release.
The publisher must not be assigned to any active (unarchived) track.

Request Body

Parameter	Type	Description
`publisherIds`	array of integers	An array of `publisherId` values for publishers to archive.

Example: Succesfully Archiving Publisher

Request

curl -X POST 'https://api.revelator.com/publishers/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"publisherIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Example: Failed Archiving Publisher with Active Track

Request

curl -X POST 'https://api.revelator.com/publishers/archive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"publisherIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": false,
            "errors": [
                {
                    "code": "General.Validation",
                    "message": "This publisher cannot be archived because it is assigned to active track(s)."
                }
            ]
        }
    ]
}

Unarchiving content

Unarchiving restores previously archived content and its associated entities to an active state.

POST `/releases/unarchive`

Unarchives one or more releases. This action will also unarchive all tracks, artists, composers, and labels directly associated with the release, as a release cannot contain archived tracks or link to archived entities.

Each release has an assetId. You can retrieve this ID using endpoints like GET /content/release/all or GET /content/release/{id}.

Request Body

Parameter	Type	Description
`assetIds`	array of integers	An array of `assetId` values for releases to unarchive.

Example: Successfully Unarchiving Releases

Request

curl -X POST 'https://api.revelator.com/releases/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

POST `/tracks/unarchive`

Unarchives one or more tracks. This action will also unarchive all related entities like artists, composers, labels and publishers directly associated with the track.

Each track has an assetId. You can retrieve this ID using endpoints like GET /content/track/all or GET /content/track/{id}.

Request Body

Parameter	Type	Description
`assetIds`	array of integers	An array of `assetId` values for tracks to unarchive.

Example: Successfully Unarchiving Track

Request

curl -X POST 'https://api.revelator.com/tracks/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

POST `/artists/unarchive`

Unarchives one or more artists. This action will also unarchive all related labels entities directly associated with the artist.

Request Body

Parameter	Type	Description
`artistIds`	array of integers	An array of `artistId` values for artists to unarchive.

Example: Successfully Unarchiving Artist

Request

curl -X POST 'https://api.revelator.com/artists/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"assetIds": [ 123456]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

POST `/labels/unarchive`

Unarchives one or more labels. This action will not automatically unarchive any related entities like tracks or releases associated with the label.

Request Body

Parameter	Type	Description
`labelIds`	array of integers	An array of `labelId` values for labels to unarchive.

Example: Successfully Unarchiving Label

Request

curl -X POST 'https://api.revelator.com/labels/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"labelIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

POST `/composers/unarchive`

Unarchives one or more composers. This action will not automatically unarchive any related tracks associated with the composer.

Request Body

Parameter	Type	Description
`composerIds`	array of integers	An array of `composerId` values for composers to unarchive.

Example: Successfully Unarchiving Composer

Request

curl -X POST 'https://api.revelator.com/composers/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"composerIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

POST `/publishers/unarchive`

Unarchives one or more publishers. This action will not automatically unarchive any related tracks associated with the publisher.

Request Body

Parameter	Type	Description
`publisherIds`	array of integers	An array of `publisherId` values for publishers to unarchive.

Example: Successfully Unarchiving Publisher

Request

curl -X POST 'https://api.revelator.com/publisher/unarchive' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
     -d '{"publisherIds": [ 123456 ]}'

Response

{
    "results": [
        {
            "id": 123456,
            "succeeded": true,
            "errors": null
        }
    ]
}

Getting Started

Distribution

Catalog management

Adding/Editing Releases

Important Considerations for Creating 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

Retrieving Tracks

GET /content/track/all

Query params

Request

Response

GET /content/track/all/summary

Query params

Request

Response

GET /content/track/{trackId}

Request

Response

Adding/Editing Artists

POST /artists

Request Body

Retrieving Artists

GET /artists

Query params

Request

Response

GET /artists/summary

Query params

Request

Response

GET /artists/{artistId}

Request

Response

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

Enterprise ID Assignment (Implicit Creation)

POST /content/publisher/save

Request Body

Request

Retrieving Publishers

GET /content/publisher/all

Query params

Request

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}`

GET `/content/track/all`

GET `/content/track/all/summary`

GET `/content/track/{trackId}`

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}`

POST `/releases/archive`

POST `/tracks/archive`

POST `/artists/archive`

POST `/labels/archive`

POST `/composers/archive`

POST `/publishers/archive`

POST `/releases/unarchive`