Releases
A release is an album, EP, single, or other format that groups one or more assets together under shared metadata. A release can include release-level artist, label, and copyright information, depending on its type and configuration, and serves as the primary entity for distribution to Digital Service Providers (DSPs).
Note: For operations requiring an assetId rather than a releaseId, please review the
Understanding Assets & IDs section in the Getting Started guide.
Compilations
A release qualifies as a compilation either because it meets the Various Artists definition, or because it is
explicitly flagged as a compilation for Spotify with isCompilation.
Various Artists
Whether a release qualifies as Various Artists depends on whether a release-level main artist (artistId) is set
and on the number of distinct Primary Artists (roleId = 49). The count includes:
- the release’s
artistId, if provided; - Primary Artist contributors on the release;
- the main primary artist of each track in the release;
- Primary Artist contributors on each track.
Duplicate artists are counted only once. Providing the same artistId with the same roleId multiple times is not
allowed.
Release-level artistId | Primary Artist requirement |
|---|---|
| Provided | The release is treated as a standard release and may contain up to four distinct Primary Artists. |
| Omitted | The release is treated as a Various Artists compilation and must contain at least four distinct Primary Artists. |
The isCompilation Flag
isCompilation can explicitly identify a release as a compilation even when it does not meet the Various Artists
definition—for example, a Best Of release or a release with two or three Primary Artists.
- Spotify currently honors this flag through DDEX 4.3.
- Other DSPs may ignore the flag and apply their own release classification rules.
- If a release already qualifies as Various Artists,
isCompilationhas no additional effect.
Video Assets
A release groups tracks and videos through the same assets array. To include a video, add its universal assetId
with assetType set to video:
{
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419901, "assetType": "video", "discNumber": 1 }
]
}The two asset types can be mixed within a release, and array order determines the running order delivered to DSPs.
Create the video first via POST /catalog/v1/videos—the assetId returned by that
response is the ID used in the release and is distinct from the videoId.
GET /catalog/v1/releases/{releaseId}/assets returns both asset types side by side. Each
entry carries either trackId or videoId, and its recordingVersions entries are discriminated by type, populating
either the audio or video payload.
A video cannot be archived while it is assigned to an active release. See Videos for the video asset model, file requirements, and metadata rules.
Lock Levels
When retrieving a release via GET /catalog/v1/releases/{releaseId}, the lockLevel
property indicates which edits are currently permitted.
The value is determined by the release’s current state and the scope of the API caller. In particular, isProcessing
and inspectionStatus can affect the lock level, and the inspection statuses that produce a fully locked release vary
by caller scope.
| Value | Description |
|---|---|
unlocked | The release and its editable metadata can be changed. |
partiallyLocked | Structural fields such as asset composition, UPC, catalog number, release date, and the previously-released flag are read-only. Descriptive metadata such as title, artwork, and copyright remains editable. |
fullyLocked | No edits are permitted. |
A release becomes partiallyLocked once it has been distributed to at least one store. From that point on,
partiallyLocked is the lowest level the release can return to — even after processing finishes or an inspection status
clears, the release can no longer go back to unlocked. For what can still be changed, and how, once a release has
reached this state, see
How to update a release after it’s been distributed.
A release becomes fullyLocked while it is actively processing for distribution (isProcessing: true with
inspectionStatus: approved), or when its inspectionStatus is one of the statuses that locks the caller’s scope.
The applicable inspection statuses are:
| Scope | Fully locked when inspectionStatus is: |
|---|---|
| Organization | dealOwnerInspection, parkedByDealOwner |
| Client, Label Portal, Artist Portal | tenantInspection, parkedByTenant, dealOwnerInspection, parkedByDealOwner, rejectedByDealOwner |
| Payee Portal & Other Scopes | Always fullyLocked, regardless of inspectionStatus. |
The same release can therefore return a different lockLevel depending on the permissions and scope of the API caller.
Archiving Releases
A release can be archived only when:
- It is not already archived.
- It has either never been distributed, or its current distribution state is no longer active or processing.
Releases that are currently being processed for distribution cannot be archived. See the distribution status reference for the complete list of terminal and processing statuses.
Important: Archiving a release does not automatically archive the tracks or videos within it. Archive those assets separately if needed—see Archiving Tracks and Archiving Videos.
Data Deletion Warning: Archived release artwork is permanently deleted six months after archiving. You will receive an email notification two weeks prior to this deletion.
Deleted cover files cannot be restored, and the release cannot be unarchived after deletion. Archived releases cannot be edited.
Create Release
POST
/catalog/v1/releases Creates a new release.
Request Body *
object enterpriseId integer The client under which the release will be created. Defaults to the caller's client when using client permissions. Required when using organization permissions.
name * string Release title. Emoji are supported and preserved internally, but are automatically stripped when delivering to DSPs that don't support them (for example, Apple Music).
version string Release version subtitle (e.g., "Deluxe Edition", "Remastered").
phoneticName string Phonetic pronunciation of the title, used for voice assistant delivery.
phoneticVersion string Phonetic pronunciation of the version subtitle.
languageAndScriptCode string Language and script code for the release's phonetic name/version (
phoneticName/phoneticVersion), not the main title (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. upc string UPC/EAN/JAN code for the release. Unique across the entire system (sandbox accounts are exempt). If omitted, one is generated automatically upon distribution. Required when
previouslyReleased is true. catalog string Internal catalog reference number assigned to the release.
description string Optional release description. This will only be sent to platforms that support descriptions, such as Beatport.
hasRecordLabel boolean Whether the release is associated with a record label. Set to
false to deliver as "Independent". labelId integer ID of an existing label to assign to the release. Required when
hasRecordLabel is true; omit or set to null when hasRecordLabel is false. artistId integer ID of an existing artist to assign as the primary artist. Omit for compilations with no designated primary artist. See the Compilations section above.
posterImageId string File ID (GUID) of the release cover artwork, uploaded via the Files API.
isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery. See the Compilations section above for how this interacts with "Various Artists" validation.
metadataLanguageId * integer Language of the release metadata—the language of the title and other text fields, not the language of the audio or lyrics. Retrieved from GET /common/lookup/languages on the V1.0 API. English is 1.
parentalAdvisory boolean Whether this release contains explicit content. Ensure this is accurately identified — misidentifying explicit content can result in your distribution being disabled. Set to
true when the release contains strong language, sexual content, references to violence or abuse, or anything unsuitable for children. previouslyReleased boolean Whether the release was commercially available before being added to Revelator. When
true, upc and releaseDate are required. When false (default), do not manually set releaseDate—it is populated automatically after first distribution. releaseDate string (date-time) Official date the release was previously released. Required when
previouslyReleased is true; otherwise should not be provided. primaryMusicStyleId * integer Primary genre/music style ID for the release. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer Secondary genre/music style ID for the release. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
copyrightC * string Composition/artwork copyright (©). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
copyrightP * string Sound recording copyright (℗). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
assets * ReleaseAssetItemModel[] Tracks and videos assigned to this release. The array order determines track numbering on DSPs. Reference existing track or video assets—create them via their own endpoints first.
assetId * integer Universal asset ID of an existing track or video to include in the release.
assetType * AssetTypes Asset type.
Examples:
track, video discNumber integer Disc number for multi-disc releases (1–10).
null for single-disc releases. contributors * ContributorItemModel[] Release-level contributors (e.g., additional primary artists for compilations, featured artists). Required even if the array is empty. Track-level contributors are attached to individual track assets instead. See the Compilations section above for how Primary Artist contributors affect compilation determination.
artistId * integer ID of an existing artist to credit as a contributor.
roleId * integer Contributor role ID. Look up available roles using GET /common/lookup/contributorRoles on the V1.0 API.
locals ReleaseLocalItemModel[] Localized title and version strings for additional metadata languages.
languageId * integer Language ID for this localization entry. Each language can be used only once in the array. Retrieved from GET /common/lookup/languages on the V1.0 API.
name * string Release title in the specified language.
version string Version subtitle in the specified language.
phoneticName string Phonetic pronunciation of the title in the specified language.
phoneticVersion string Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string Language and script code for this entry's phonetic name/version, not the localized title (e.g.,
en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. distributorStoreGenreIds integer[] DSP-specific genre IDs configured for the release. Currently used for Beatport genre assignments. Retrieved from GET /common/lookup/DistributionStoreGenres on the V1.0 API.
Responses
object releaseId integer Unique identifier for the release.
assetId integer Universal asset ID for this release, used in archive, unarchive, and rights operations.
tenantId integer ID of the organization that owns this release.
enterpriseId integer ID of the client that owns this release.
name string | null Release title.
phoneticName string | null Phonetic pronunciation of the title, used for voice assistant delivery.
version string | null Release version subtitle.
phoneticVersion string | null Phonetic pronunciation of the version subtitle.
languageAndScriptCode string | null Language and script code for the release's phonetic name/version, not the main title.
upc string | null UPC/EAN/JAN code for the release.
isrc string | null ⚠ deprecated
Deprecated. Legacy ISRC field present on some ingested releases. Do not use for new releases.
catalog string | null Internal catalog reference number assigned to the release.
description string | null Release description.
featureFmSmartLink string | null Feature.fm smart link URL for the release.
featureFmSmartLinkId string | null Feature.fm smart link ID.
hasRecordLabel boolean Whether the release is associated with a record label.
labelId integer | null ID of the assigned label. Present only when
hasRecordLabel is true. artistId integer | null ID of the primary artist.
null for compilations with no designated primary artist. posterImageId string | null File ID of the release cover artwork.
isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery.
metadataLanguageId integer | null Language of the release metadata.
parentalAdvisory boolean | null Whether this release contains explicit content.
previouslyReleased boolean Whether the release was commercially available before being added to Revelator.
releaseDate string (date-time) | null Official release date.
releaseType WellKnownReleaseTypes Release type.
Examples:
album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum primaryMusicStyleId integer | null Primary genre/music style ID.
secondaryMusicStyleId integer | null Secondary genre/music style ID.
copyrightC string | null Composition/artwork copyright (©).
copyrightP string | null Sound recording copyright (℗).
assets ReleaseAssetItemModel[] Tracks and videos assigned to this release.
assetId * integer Universal asset ID of the track or video.
assetType * AssetTypes Asset type.
Examples:
track, video discNumber integer | null Disc number for multi-disc releases.
null for single-disc releases. contributors ContributorItemModel[] Release-level contributors.
artistId * integer Artist ID of the contributor.
roleId * integer Contributor role ID.
locals ReleaseLocalItemModel[] Localized title and version strings for additional metadata languages.
languageId * integer Language ID for this localization entry.
name * string Release title in the specified language.
version string | null Version subtitle in the specified language.
phoneticName string | null Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null Language and script code for this entry's phonetic name/version, not the localized title.
distributorStoreGenreIds integer[] DSP-specific genre IDs configured for the release.
isIngested boolean Whether this release was imported via ingestion rather than created manually.
creationDate string (date-time) UTC timestamp when the release was created.
createdBy string ID of the user who created the release.
createdByEmail string | null Email address of the user who created the release.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
lastUpdatedBy string | null ID of the user who last updated the release.
archivedAt string (date-time) | null UTC timestamp when the release was archived.
null if the release is active. archivedBy string | null ID of the user who archived the release.
null if the release is active. lockLevel AssetLockLevels Edit permission level for this release. See the Lock Levels section above for details.
Examples:
unlocked, partiallyLocked, fullyLocked inspectionStatus AssetInspectionStatuses Current inspection/review status. See the Lock Levels section above.
Examples:
tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved hasIssues boolean Whether the release has validation issues that would prevent successful distribution.
notesCount integer Number of internal notes attached to this release.
hasDistribution boolean Whether the release is currently distributed to at least one store.
isProcessing boolean Whether the release is actively being processed by the distribution pipeline.
firstDeliveryDate string (date-time) | null UTC timestamp of the first successful delivery to a DSP.
POST
/catalog/v1/releases curl -X POST "https://platform.revelator.com/catalog/v1/releases" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Midnight Tides",
"version": "Deluxe Edition",
"upc": "843563172001",
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": []
}'curl -X POST "https://platform.revelator.com/catalog/v1/releases" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Midnight Tides",
"version": "Deluxe Edition",
"upc": "843563172001",
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": []
}' Example response 200
{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"createdByEmail": "[email protected]",
"lastUpdateDate": null,
"lastUpdatedBy": null,
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"createdByEmail": "[email protected]",
"lastUpdateDate": null,
"lastUpdatedBy": null,
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}Get Release
GET
/catalog/v1/releases/{releaseId} Retrieves a release by its ID.
Path Parameters
| Parameter | Description |
|---|---|
releaseId * integer | The ID of the release. |
Responses
object releaseId integer Unique identifier for the release.
assetId integer Universal asset ID for this release, used in archive, unarchive, and rights operations.
tenantId integer ID of the organization that owns this release.
enterpriseId integer ID of the client that owns this release.
name string | null Release title.
phoneticName string | null Phonetic pronunciation of the title, used for voice assistant delivery.
version string | null Release version subtitle (e.g., "Deluxe Edition", "Remastered").
phoneticVersion string | null Phonetic pronunciation of the version subtitle.
languageAndScriptCode string | null Language and script code for the release's phonetic name/version, not the main title.
upc string | null UPC/EAN/JAN code for the release. Unique across the entire system (sandbox accounts are exempt).
isrc string | null ⚠ deprecated
Deprecated. Legacy ISRC field present on some ingested releases. Do not use for new releases.
catalog string | null Internal catalog reference number assigned to the release.
description string | null Optional release description. This will only be sent to platforms that support descriptions, such as Beatport.
featureFmSmartLink string | null Feature.fm smart link URL for the release.
featureFmSmartLinkId string | null Feature.fm smart link ID.
hasRecordLabel boolean Whether the release is associated with a record label. When
false, delivered as "Independent". labelId integer | null ID of the assigned label. Present only when
hasRecordLabel is true. artistId integer | null ID of the primary artist. Returns
null for compilations with no designated primary artist. posterImageId string | null File ID of the release cover artwork.
isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery. See the Compilations section above.
metadataLanguageId integer | null Language of the release metadata—the language of the title and other text fields.
parentalAdvisory boolean | null Whether this release contains explicit content. Ensure this is accurately identified — misidentifying explicit content can result in your distribution being disabled. Set to
true when the release contains strong language, sexual content, references to violence or abuse, or anything unsuitable for children. previouslyReleased boolean Whether the release was commercially available before being added to Revelator. Affects which structural fields are locked.
releaseDate string (date-time) | null Official release date. Set for previously-released content or populated automatically after first distribution.
releaseType WellKnownReleaseTypes Release type.
Examples:
album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum primaryMusicStyleId integer | null Primary genre/music style ID.
secondaryMusicStyleId integer | null Secondary genre/music style ID.
copyrightC string | null Composition/artwork copyright (©). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
copyrightP string | null Sound recording copyright (℗). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
assets ReleaseAssetItemModel[] Tracks and videos assigned to this release. The array order determines track numbering on DSPs.
assetId * integer Universal asset ID of the track or video.
assetType * AssetTypes Asset type.
Examples:
track, video discNumber integer | null Disc number for multi-disc releases.
null for single-disc releases. contributors ContributorItemModel[] Release-level contributors. Track-level contributors are attached to individual track assets and can be retrieved via the List Release Assets endpoint.
artistId * integer Artist ID of the contributor.
roleId * integer Contributor role ID. Look up available roles using the lookup endpoints.
locals ReleaseLocalItemModel[] Localized title and version strings for additional metadata languages.
languageId * integer Language ID for this localization entry.
name * string Release title in the specified language.
version string | null Version subtitle in the specified language.
phoneticName string | null Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null Language and script code for this entry's phonetic name/version, not the localized title.
distributorStoreGenreIds integer[] DSP-specific genre IDs configured for the release. Currently used for Beatport genre assignments.
isIngested boolean Whether this release was imported via ingestion rather than created manually. Ingested releases are partially locked.
creationDate string (date-time) UTC timestamp when the release was created.
createdBy string Email or identifier of the user who created the release.
createdByEmail string | null Email address of the user who created the release.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
lastUpdatedBy string | null Email or identifier of the user who last updated the release.
archivedAt string (date-time) | null UTC timestamp when the release was archived.
null if the release is active. archivedBy string | null Identifier of the user who archived the release.
null if the release is active. lockLevel AssetLockLevels Edit permission level for this release. See the Lock Levels section above for details.
Examples:
unlocked, partiallyLocked, fullyLocked inspectionStatus AssetInspectionStatuses Current inspection/review status. See the Lock Levels section above for how this affects editing permissions.
Examples:
tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved hasIssues boolean Whether the release has validation issues that would prevent successful distribution.
notesCount integer Number of internal notes attached to this release.
hasDistribution boolean Whether the release is currently distributed to at least one store.
isProcessing boolean Whether the release is actively being processed by the distribution pipeline.
firstDeliveryDate string (date-time) | null UTC timestamp of the first successful delivery to a DSP. Once set, the release becomes partially locked.
GET
/catalog/v1/releases/{releaseId} curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"featureFmSmartLink": "https://feature.fm/midnight-tides",
"featureFmSmartLinkId": "abc123",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "[email protected]",
"createdByEmail": "[email protected]",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "[email protected]",
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days.",
"featureFmSmartLink": "https://feature.fm/midnight-tides",
"featureFmSmartLinkId": "abc123",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "[email protected]",
"createdByEmail": "[email protected]",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "[email protected]",
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}List Releases
GET
/catalog/v1/releases Returns a paginated list of releases based on filters and sorting options.
Query Parameters
| Parameter | Description |
|---|---|
searchText string | Free-text search applied to release name and other supported fields. |
orderByProperty string | Property name used for sorting. Examples: releaseDate, creationDate, name, releaseId, artistName, labelName |
orderByDescending boolean | Set to |
pageNumber integer | Page number for paginated results. |
pageSize integer | Number of items per page. |
releaseDateFrom string (date-time) | Include releases with a release date on or after this UTC date-time. |
releaseDateTo string (date-time) | Include releases with a release date on or before this UTC date-time. |
creationDateFrom string (date-time) | Include releases created on or after this UTC date-time. |
creationDateTo string (date-time) | Include releases created on or before this UTC date-time. |
lastUpdateDateFrom string (date-time) | Include releases updated on or after this UTC date-time. |
lastUpdateDateTo string (date-time) | Include releases updated on or before this UTC date-time. |
hasFeatureFmLink boolean | Filter to releases that have ( |
archived boolean | Filter by archive state ( |
archivedDateFrom string (date-time) | Include releases archived on or after this UTC date-time. |
archivedDateTo string (date-time) | Include releases archived on or before this UTC date-time. |
inspectionStatus string | Filter by inspection status. Examples: tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved |
neverDistributed boolean | When |
hasIssues boolean | Filter to releases that have ( |
hasDistribution boolean | Filter to releases that have ( |
isProcessing boolean | Filter to releases currently being processed ( |
hasTakenDown boolean | Filter to releases that have been taken down from at least one store ( |
upcs string[] | Filter by one or more UPC codes. Maximum 100 per request. |
isrcs string[] | Filter to releases containing a track with one of the given ISRC codes. Maximum 100 per request. |
releaseTypes WellKnownReleaseTypes[] | Filter by one or more release types. Examples: album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum |
musicStyleIds integer[] | Filter by one or more primary music style IDs. Retrieved from GET /common/lookup/musicstyles on the V1.0 API. Maximum 100 IDs per request. |
metadataLanguageIds integer[] | Filter by one or more metadata language IDs. Maximum 100 IDs per request. Retrieved from GET /common/lookup/languages on the V1.0 API. |
releaseIds integer[] | Filter by one or more release IDs. Maximum 100 IDs per request. |
assetIds integer[] | Filter by the releases' own asset IDs—the |
trackAssetIds integer[] | Filter to releases that contain a track with one of the given asset IDs. Pass the track's |
videoAssetIds integer[] | Filter to releases that contain a video with one of the given asset IDs. Pass the video's |
payeeIds integer[] | Filter by one or more payee IDs associated with the release. Maximum 100 IDs per request. |
enterpriseIds integer[] | Filter by one or more client IDs. Maximum 100 IDs per request. |
labelIds integer[] | Filter by one or more label IDs. Maximum 100 IDs per request. |
artistIds integer[] | Filter by one or more primary artist IDs. Maximum 100 IDs per request. |
Responses
object pageNumber integer Current page number.
pageSize integer Number of items per page in this response.
totalItemsCount integer Total number of releases matching the applied filters.
totalPagesCount number Total number of pages at the current page size.
items ReleaseListModel[] Array of release summary objects for the current page.
releaseId integer Unique identifier for the release.
assetId integer Universal asset ID, used in archive, unarchive, and rights operations.
name string | null Release title.
version string | null Release version subtitle.
posterImageId string | null File ID of the release cover artwork.
catalog string | null Internal catalog reference number assigned to the release.
copyrightP string | null Sound recording copyright (℗).
copyrightC string | null Composition/artwork copyright (©).
artistId integer | null ID of the primary artist.
artistName string | null Display name of the primary artist.
artistLogoImageId string | null File ID of the primary artist's profile image.
labelId integer | null ID of the assigned label.
labelName string | null Name of the assigned label.
enterpriseId integer | null ID of the client that owns this release.
enterpriseName string | null Name of the client.
upc string | null UPC/EAN code for the release.
tracksCount integer Number of track assets assigned to the release.
duration integer Total playback duration of all tracks, in seconds.
releaseDate string (date-time) | null Official release date.
releaseType WellKnownReleaseTypes Release type.
Examples:
album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery. See the Compilations section above.
primaryMusicStyleId integer | null Primary genre/music style ID.
primaryMusicStyleName string | null Primary genre/music style name.
secondaryMusicStyleId integer | null Secondary genre/music style ID.
secondaryMusicStyleName string | null Secondary genre/music style name.
metadataLanguageId integer | null Language ID of the release metadata.
metadataLanguageName string | null Language name of the release metadata.
languageAndScriptCode string | null Language and script code for the release's phonetic name/version, not the main title.
featureFmSmartLink string | null Feature.fm smart link URL.
featureFmSmartLinkId string | null Feature.fm smart link ID.
creationDate string (date-time) UTC timestamp when the release was created.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
archivedAt string (date-time) | null UTC timestamp when the release was archived.
null if the release is active. lockLevel AssetLockLevels Edit permission level. See the Lock Levels section above.
Examples:
unlocked, partiallyLocked, fullyLocked inspectionStatus AssetInspectionStatuses Current inspection/review status. See the Lock Levels section above.
Examples:
tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved hasIssues boolean Whether the release has validation issues blocking distribution.
hasDistribution boolean Whether the release is currently distributed to at least one store.
hasTakenDown boolean Whether the release has been taken down from at least one store after a prior distribution.
isProcessing boolean Whether the release is actively being processed by the distribution pipeline.
firstDeliveryDate string (date-time) | null UTC timestamp of the first successful delivery to a DSP.
contributors ContributorListModel[] | null Release-level contributors.
artistId integer Artist ID of the contributor.
roleId integer Contributor role ID.
artistName string | null Display name of the contributing artist.
GET
/catalog/v1/releases curl -X GET "https://platform.revelator.com/catalog/v1/releases?pageNumber=1&pageSize=20&artistIds=4402&orderByProperty=creationDate&orderByDescending=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/releases?pageNumber=1&pageSize=20&artistIds=4402&orderByProperty=creationDate&orderByDescending=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
{
"releaseId": 8801,
"assetId": 5001100,
"name": "Midnight Tides",
"version": "Deluxe Edition",
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"catalog": "NLR-0042",
"copyrightP": "2024 Northline Records",
"copyrightC": "2024 Northline Records",
"artistId": 4402,
"artistName": "Nova Days",
"labelId": 120,
"labelName": "Northline Records",
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"upc": "843563172001",
"tracksCount": 2,
"duration": 450,
"releaseDate": null,
"releaseType": "album",
"isCompilation": false,
"primaryMusicStyleId": 17,
"primaryMusicStyleName": "Electronic",
"secondaryMusicStyleId": null,
"secondaryMusicStyleName": null,
"metadataLanguageId": 1,
"metadataLanguageName": "English",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"creationDate": "2024-05-01T10:00:00Z",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"archivedAt": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"hasDistribution": false,
"hasTakenDown": false,
"isProcessing": false,
"firstDeliveryDate": null,
"contributors": [
{ "artistId": 4409, "roleId": 12, "artistName": "Mara Quinn" }
]
}
]
}{
"pageNumber": 1,
"pageSize": 20,
"totalItemsCount": 1,
"totalPagesCount": 1,
"items": [
{
"releaseId": 8801,
"assetId": 5001100,
"name": "Midnight Tides",
"version": "Deluxe Edition",
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"catalog": "NLR-0042",
"copyrightP": "2024 Northline Records",
"copyrightC": "2024 Northline Records",
"artistId": 4402,
"artistName": "Nova Days",
"labelId": 120,
"labelName": "Northline Records",
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"upc": "843563172001",
"tracksCount": 2,
"duration": 450,
"releaseDate": null,
"releaseType": "album",
"isCompilation": false,
"primaryMusicStyleId": 17,
"primaryMusicStyleName": "Electronic",
"secondaryMusicStyleId": null,
"secondaryMusicStyleName": null,
"metadataLanguageId": 1,
"metadataLanguageName": "English",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"creationDate": "2024-05-01T10:00:00Z",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"archivedAt": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"hasDistribution": false,
"hasTakenDown": false,
"isProcessing": false,
"firstDeliveryDate": null,
"contributors": [
{ "artistId": 4409, "roleId": 12, "artistName": "Mara Quinn" }
]
}
]
}Export Releases
GET
/catalog/v1/releases/export Exports release and track metadata as a CSV file. Accepts the same filters as List Releases to narrow the export scope.
Query Parameters
| Parameter | Description |
|---|---|
searchText string | Free-text search applied to release name and other supported fields. |
orderByProperty string | Property name used for sorting. Examples: releaseDate, creationDate, name, releaseId, artistName, labelName |
orderByDescending boolean | Set to |
pageNumber integer | Page number for paginated results. |
pageSize integer | Number of items per page. |
releaseDateFrom string (date-time) | Include releases with a release date on or after this UTC date-time. |
releaseDateTo string (date-time) | Include releases with a release date on or before this UTC date-time. |
creationDateFrom string (date-time) | Include releases created on or after this UTC date-time. |
creationDateTo string (date-time) | Include releases created on or before this UTC date-time. |
lastUpdateDateFrom string (date-time) | Include releases updated on or after this UTC date-time. |
lastUpdateDateTo string (date-time) | Include releases updated on or before this UTC date-time. |
hasFeatureFmLink boolean | Filter to releases that have ( |
archived boolean | Filter by archive state ( |
archivedDateFrom string (date-time) | Include releases archived on or after this UTC date-time. |
archivedDateTo string (date-time) | Include releases archived on or before this UTC date-time. |
inspectionStatus string | Filter by inspection status. Examples: tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved |
neverDistributed boolean | When |
hasIssues boolean | Filter to releases that have ( |
hasDistribution boolean | Filter to releases that have ( |
isProcessing boolean | Filter to releases currently being processed ( |
hasTakenDown boolean | Filter to releases that have been taken down from at least one store ( |
upcs string[] | Filter by one or more UPC codes. |
isrcs string[] | Filter to releases containing a track with one of the given ISRC codes. Maximum 100 per request. |
releaseTypes WellKnownReleaseTypes[] | Filter by one or more release types. Examples: album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum |
musicStyleIds integer[] | Filter by one or more primary music style IDs. Retrieved from GET /common/lookup/musicstyles on the V1.0 API. |
metadataLanguageIds integer[] | Filter by one or more metadata language IDs. Retrieved from GET /common/lookup/languages on the V1.0 API. |
releaseIds integer[] | Filter by one or more release IDs. |
assetIds integer[] | Filter by the releases' own asset IDs—the |
trackAssetIds integer[] | Filter to releases that contain a track with one of the given asset IDs. Pass the track's |
videoAssetIds integer[] | Filter to releases that contain a video with one of the given asset IDs. Pass the video's |
payeeIds integer[] | Filter by one or more payee IDs associated with the release. |
enterpriseIds integer[] | Filter by one or more client IDs. |
labelIds integer[] | Filter by one or more label IDs. |
artistIds integer[] | Filter by one or more primary artist IDs. |
Responses
none GET
/catalog/v1/releases/export curl -X GET "https://platform.revelator.com/catalog/v1/releases/export?artistIds=4402&releaseDateFrom=2024-01-01T00:00:00Z" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o releases.csvcurl -X GET "https://platform.revelator.com/catalog/v1/releases/export?artistIds=4402&releaseDateFrom=2024-01-01T00:00:00Z" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o releases.csv Example response 200
ParentEnterprise,Enterprise,ReleaseLabel,ReleaseArtist,UPC,ReleaseRefId,Release,ReleaseVersion,ReleaseType,vISRC,Disc,TrkNo,TrackArtist,ISRC,Recording,TrackRefId,Track,TrackVersion,TrackType,Explicit,PrvwSecs,TitleLanguage,LyricsLanguage,TrackMainGenre,TrackSecondaryGenre,ReleaseCreated,ReleaseCreatedBy,TrackCreated,TrackCreatedBy,TrackRecordingCreated,ReleaseUpdated,ReleaseUpdatedBy,ReleaseDate,SalePreOrderDate,SaleStartDate,ReleaseArchived,ReleaseArchivedBy,ReleasePLine,ReleaseCLine,TrackPLine,TrackCLine,EnterpriseId,PayeeId,ReleaseId,ReleaseAssetId,ReleaseLabelId,ReleaseArtistId,TrackId,ReleaseTrackAssetId,TrackArtistId,ReleaseAppleId,TrackAppleId,ReleaseSpotifyId,TrackSpotifyId,ReleaseDeezerId,TrackDeezerId,YouTubeCIDAssetId,YouTubeVideoId,FeatureFmSmartLinkId
Identity - PARENT,Acme Music,Acme Music,Nova Days,,A01000266,Midnight Tides,,album,,01,01,Nova Days,QZN882500554,Stereo,,Night Lights,,Original,False,0,English,English,Electronic,,2024-05-01 12:00:00,[email protected],2024-05-01 11:45:00,[email protected],2024-05-01 12:05:00,2024-05-15 08:30:00,[email protected],,,,,2024 Northline Records,2024 Northline Records,2024 Northline Records,,3001,4402,8801,5001100,120,4402,7701,4419835,4402,,,,,,,,,ParentEnterprise,Enterprise,ReleaseLabel,ReleaseArtist,UPC,ReleaseRefId,Release,ReleaseVersion,ReleaseType,vISRC,Disc,TrkNo,TrackArtist,ISRC,Recording,TrackRefId,Track,TrackVersion,TrackType,Explicit,PrvwSecs,TitleLanguage,LyricsLanguage,TrackMainGenre,TrackSecondaryGenre,ReleaseCreated,ReleaseCreatedBy,TrackCreated,TrackCreatedBy,TrackRecordingCreated,ReleaseUpdated,ReleaseUpdatedBy,ReleaseDate,SalePreOrderDate,SaleStartDate,ReleaseArchived,ReleaseArchivedBy,ReleasePLine,ReleaseCLine,TrackPLine,TrackCLine,EnterpriseId,PayeeId,ReleaseId,ReleaseAssetId,ReleaseLabelId,ReleaseArtistId,TrackId,ReleaseTrackAssetId,TrackArtistId,ReleaseAppleId,TrackAppleId,ReleaseSpotifyId,TrackSpotifyId,ReleaseDeezerId,TrackDeezerId,YouTubeCIDAssetId,YouTubeVideoId,FeatureFmSmartLinkId
Identity - PARENT,Acme Music,Acme Music,Nova Days,,A01000266,Midnight Tides,,album,,01,01,Nova Days,QZN882500554,Stereo,,Night Lights,,Original,False,0,English,English,Electronic,,2024-05-01 12:00:00,[email protected],2024-05-01 11:45:00,[email protected],2024-05-01 12:05:00,2024-05-15 08:30:00,[email protected],,,,,2024 Northline Records,2024 Northline Records,2024 Northline Records,,3001,4402,8801,5001100,120,4402,7701,4419835,4402,,,,,,,,,List Release Assets
GET
/catalog/v1/releases/{releaseId}/assets Retrieves the tracks and videos linked to a release.
Path Parameters
| Parameter | Description |
|---|---|
releaseId * integer | The ID of the release. |
Responses
object[] assetId integer Universal asset ID for this track or video.
assetType AssetTypes Type of the asset.
Examples:
track, video discNumber integer | null Disc number for multi-disc releases.
null for single-disc releases. trackId integer | null Track entity ID. Use this when retrieving or updating track metadata.
null for video assets. videoId integer | null Video entity ID.
null for track assets. name * string Track or video title.
version string | null Recording version subtitle (e.g., "Remix", "Acoustic").
artistId integer | null Primary artist ID for this track or video.
artistName string | null Primary artist display name.
creationDate string (date-time) UTC timestamp when the track or video was created.
parentalAdvisory ParentalAdvisories Advisory label for the track or video content.
Examples:
notExplicit, clean, explicit contributors ContributorListModel[] | null Contributing artists credited on this track or video.
artistId integer ID of the contributing artist.
roleId integer Contributor role ID.
artistName string | null Display name of the contributing artist.
recordingVersions RecordingVersionItemModel[] | null Recording versions for this asset. Each entry carries either an
audio or a video payload, discriminated by type. type RecordingVersionType Discriminates which of
audio or video is populated for this recording version. Examples:
audio, video audio AudioRecordingItemModel Audio recording version details. Populated when
type is audio; null otherwise. isrc string | null ISRC code for this recording version.
recordingVersionType TrackRecordingVersionTypes Type of audio recording.
Examples:
stereo, dolbyAtmos files AudioFileModel[] Uploaded audio files for this recording version.
fileId string File ID of the uploaded audio file.
format WellKnownFileFormat Audio file format.
Examples:
wav, flac filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the audio file, in seconds.
bitDepth integer | null Bit depth of the audio file.
sampleRate integer | null Sample rate of the audio file, in Hz.
bitrate integer | null Bitrate of the audio file.
channels integer | null Number of audio channels.
size integer | null File size, in bytes.
video VideoRecordingItemModel Video recording version details. Populated when
type is video; null otherwise. isrc string | null ISRC code for this recording version.
recordingVersionType VideoRecordingVersionTypes Type of video recording.
Example:
standard files VideoFileModel[] Uploaded video files for this recording version.
fileId string File ID of the uploaded video file.
format VideoFileFormats Video file format.
Examples:
mp4, mov filename string | null Name of the uploaded file, including the extension.
duration integer | null Duration of the video file, in seconds.
bitDepth integer | null Bit depth of the video file.
sampleRate integer | null Sample rate of the video file, in Hz.
bitrate integer | null Bitrate of the video file.
resolution string | null Resolution of the video file (e.g., "1920x1080").
frameRate number Frame rate of the video file, in frames per second.
size integer | null File size, in bytes.
channels integer | null Number of audio channels in the video file.
acrCloud AcrCloudModel Automatic Content Recognition (ACR) scan results for this asset's audio, used for fingerprinting and rights matching. Populated automatically once the file has been processed;
null if no scan has run yet. fileId string File ID of the audio or video file that was scanned.
acrId string | null ACRCloud's identifier for this scan.
null until the scan completes. status AcrCloudScanStatus Scan status.
Examples:
inProcessing, complete, error creationDate string (date-time) UTC timestamp when the scan record was created.
timestampUtc string (date-time) | null UTC timestamp reported by ACRCloud for the scan result.
null until the scan completes. musicDetected integer | null Amount of music detected by the scan.
duration integer | null Duration analyzed by the scan, in seconds.
error string | null Error message if the scan failed.
null on success. isrc string | null ISRC reported by the scan for the matched recording.
null if the scan produced no match. scans object[] | null Individual fingerprint scan passes run against the file.
coverSongs object[] | null Cover-song matches detected by the scan.
derivativeWorks object[] | null Derivative-work matches detected by the scan.
speechDetection object[] | null Speech segments detected in the file.
aiDetection object[] | null AI-generated-content detection results for the file.
imageId string | null File ID of the asset's artwork image, for rendering the asset in a list or table.
null when the asset has no artwork of its own. GET
/catalog/v1/releases/{releaseId}/assets curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801/assets" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801/assets" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
[
{
"assetId": 4419835,
"assetType": "track",
"discNumber": 1,
"trackId": 7701,
"videoId": null,
"name": "Night Lights",
"version": null,
"artistId": 4402,
"artistName": "Nova Days",
"parentalAdvisory": "notExplicit",
"imageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"contributors": [],
"creationDate": "2024-05-01T11:45:00Z",
"recordingVersions": [
{
"type": "audio",
"audio": {
"isrc": "QZ8AB2400011",
"recordingVersionType": "stereo",
"files": [
{
"fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
"format": "wav",
"filename": "night-lights.wav",
"duration": 223,
"bitDepth": 24,
"sampleRate": 48000,
"bitrate": null,
"channels": 2,
"size": 42102300
}
]
},
"video": null
}
]
},
{
"assetId": 4419836,
"assetType": "track",
"discNumber": 1,
"trackId": 7702,
"videoId": null,
"name": "Open Sea",
"version": null,
"artistId": 4402,
"artistName": "Nova Days",
"parentalAdvisory": "notExplicit",
"imageId": null,
"contributors": [],
"creationDate": "2024-05-01T11:50:00Z",
"recordingVersions": [
{
"type": "audio",
"audio": {
"isrc": "QZ8AB2400012",
"recordingVersionType": "stereo",
"files": [
{
"fileId": "a5be1c2d-f840-48f2-9aa2-8b1234e99012",
"format": "wav",
"filename": "open-sea.wav",
"duration": 197,
"bitDepth": 24,
"sampleRate": 48000,
"bitrate": null,
"channels": 2,
"size": 37248900
}
]
},
"video": null
}
]
}
][
{
"assetId": 4419835,
"assetType": "track",
"discNumber": 1,
"trackId": 7701,
"videoId": null,
"name": "Night Lights",
"version": null,
"artistId": 4402,
"artistName": "Nova Days",
"parentalAdvisory": "notExplicit",
"imageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"contributors": [],
"creationDate": "2024-05-01T11:45:00Z",
"recordingVersions": [
{
"type": "audio",
"audio": {
"isrc": "QZ8AB2400011",
"recordingVersionType": "stereo",
"files": [
{
"fileId": "d12fd57a-e739-44fd-9246-31f50d4ee5f6",
"format": "wav",
"filename": "night-lights.wav",
"duration": 223,
"bitDepth": 24,
"sampleRate": 48000,
"bitrate": null,
"channels": 2,
"size": 42102300
}
]
},
"video": null
}
]
},
{
"assetId": 4419836,
"assetType": "track",
"discNumber": 1,
"trackId": 7702,
"videoId": null,
"name": "Open Sea",
"version": null,
"artistId": 4402,
"artistName": "Nova Days",
"parentalAdvisory": "notExplicit",
"imageId": null,
"contributors": [],
"creationDate": "2024-05-01T11:50:00Z",
"recordingVersions": [
{
"type": "audio",
"audio": {
"isrc": "QZ8AB2400012",
"recordingVersionType": "stereo",
"files": [
{
"fileId": "a5be1c2d-f840-48f2-9aa2-8b1234e99012",
"format": "wav",
"filename": "open-sea.wav",
"duration": 197,
"bitDepth": 24,
"sampleRate": 48000,
"bitrate": null,
"channels": 2,
"size": 37248900
}
]
},
"video": null
}
]
}
]List Release Contributors
GET
/catalog/v1/releases/{releaseId}/contributors Retrieves all contributors associated with a release.
Path Parameters
| Parameter | Description |
|---|---|
releaseId * integer | The ID of the release. |
Responses
object[] artistId integer Unique identifier for the artist.
name string | null Artist display name (stage name or act name).
firstName string | null Legal first name of the artist.
middleName string | null Legal middle name of the artist.
lastName string | null Legal last name of the artist.
logoImageId string | null File ID of the artist's profile image.
tenantId integer ID of the organization that owns this artist.
enterpriseId integer ID of the client that owns this artist.
enterpriseName string | null Name of the client.
hasPortal boolean Whether this artist has an associated artist portal account.
isni string | null International Standard Name Identifier for the artist.
languageAndScriptCode string | null Language and script code for the artist name.
creationDate string (date-time) UTC timestamp when the artist was created.
lastUpdateDate string (date-time) UTC timestamp of the most recent update.
archivedAt string (date-time) | null UTC timestamp when the artist was archived.
null if the artist is active. externalIds ArtistExternalIdItemModel[] | null External DSP profile IDs for this artist (e.g., Spotify artist URI, Apple Music artist ID).
profileId string | null The artist's profile ID on the external platform.
distributorStoreId integer | null Identifies the distributor store. Use the lookup endpoints to resolve store names.
musicStyleIds integer[] | null Primary music style IDs associated with this artist.
GET
/catalog/v1/releases/{releaseId}/contributors curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801/contributors" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"curl -X GET "https://platform.revelator.com/catalog/v1/releases/8801/contributors" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
[
{
"artistId": 4410,
"name": "DJ Prism",
"firstName": null,
"middleName": null,
"lastName": null,
"logoImageId": null,
"tenantId": 2001,
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"hasPortal": false,
"isni": null,
"languageAndScriptCode": null,
"creationDate": "2023-11-01T09:00:00Z",
"lastUpdateDate": "2024-03-10T14:20:00Z",
"archivedAt": null,
"externalIds": [
{ "profileId": "5NHQUkpP4tlGGBDNhrE7xx", "distributorStoreId": 9 }
],
"musicStyleIds": [17]
}
][
{
"artistId": 4410,
"name": "DJ Prism",
"firstName": null,
"middleName": null,
"lastName": null,
"logoImageId": null,
"tenantId": 2001,
"enterpriseId": 3001,
"enterpriseName": "Client Name",
"hasPortal": false,
"isni": null,
"languageAndScriptCode": null,
"creationDate": "2023-11-01T09:00:00Z",
"lastUpdateDate": "2024-03-10T14:20:00Z",
"archivedAt": null,
"externalIds": [
{ "profileId": "5NHQUkpP4tlGGBDNhrE7xx", "distributorStoreId": 9 }
],
"musicStyleIds": [17]
}
]Update Release
PUT
/catalog/v1/releases/{releaseId} Updates an existing release by its ID.
Path Parameters
| Parameter | Description |
|---|---|
releaseId * integer | The ID of the release to update. |
Request Body *
object enterpriseId integer Ignored when updating an existing release; the update always targets the release identified by
releaseId regardless of client. name * string Release title. Emoji are supported and preserved internally, but are automatically stripped when delivering to DSPs that don't support them (for example, Apple Music).
version string Release version subtitle (e.g., "Deluxe Edition", "Remastered").
phoneticName string Phonetic pronunciation of the title, used for voice assistant delivery.
phoneticVersion string Phonetic pronunciation of the version subtitle.
languageAndScriptCode string Language and script code for the release's phonetic name/version (
phoneticName/phoneticVersion), not the main title (e.g., en-Latn). Available values can be retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. upc string UPC/EAN/JAN code for the release. Unique across the entire system (sandbox accounts are exempt). You should never generate a new UPC for a release that already has one.
catalog string Internal catalog reference number assigned to the release.
description string Optional release description. This will only be sent to platforms that support descriptions, such as Beatport.
hasRecordLabel boolean Whether the release is associated with a record label. Set to
false to deliver as "Independent". labelId integer ID of an existing label to assign to the release. Required when
hasRecordLabel is true; omit or set to null when hasRecordLabel is false. artistId integer ID of an existing artist to assign as the primary artist. Omit for compilations with no designated primary artist. See the Compilations section above.
posterImageId string File ID (GUID) of the release cover artwork, uploaded via the Files API.
isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery. See the Compilations section above for how this interacts with "Various Artists" validation.
metadataLanguageId * integer Language of the release metadata—the language of the title and other text fields. Retrieved from GET /common/lookup/languages on the V1.0 API.
parentalAdvisory boolean Whether this release contains explicit content. Ensure this is accurately identified — misidentifying explicit content can result in your distribution being disabled.
previouslyReleased boolean Whether the release was commercially available before being added to Revelator. Structural fields become read-only once the release has a
partiallyLocked or fullyLocked state—see the Lock Levels section above. releaseDate string (date-time) Official date the release was previously released. When distributing through Revelator, do not set this manually.
primaryMusicStyleId integer Primary genre/music style ID for the release. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
secondaryMusicStyleId integer Secondary genre/music style ID for the release. Retrieved from GET /common/lookup/musicstyles on the V1.0 API.
copyrightC string Composition/artwork copyright (©). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
copyrightP * string Sound recording copyright (℗). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
assets * ReleaseAssetItemModel[] Tracks and videos assigned to this release. The array order determines track numbering on DSPs. In line with the general behavior of this API, patching is not supported—existing assets omitted from this array are removed from the release.
assetId * integer Universal asset ID of an existing track or video to include in the release.
assetType * AssetTypes Asset type.
Examples:
track, video discNumber integer Disc number for multi-disc releases (1–10).
null for single-disc releases. contributors * ContributorItemModel[] Release-level contributors. Required even if the array is empty. See the Compilations section above for how Primary Artist contributors affect compilation determination.
artistId * integer ID of an existing artist to credit as a contributor.
roleId * integer Contributor role ID. Retrieved from GET /common/lookup/contributorRoles on the V1.0 API.
locals ReleaseLocalItemModel[] Localized title and version strings for additional metadata languages.
languageId * integer Language ID for this localization entry. Each language can be used only once in the array. Retrieved from GET /common/lookup/languages on the V1.0 API.
name * string Release title in the specified language.
version string Version subtitle in the specified language.
phoneticName string Phonetic pronunciation of the title in the specified language.
phoneticVersion string Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string Language and script code for this entry's phonetic name/version, not the localized title (e.g.,
en-Latn). Retrieved from GET /common/lookup/languageAndScriptCodes on the V1.0 API. distributorStoreGenreIds integer[] DSP-specific genre IDs configured for the release. Currently used for Beatport genre assignments. Retrieved from GET /common/lookup/DistributionStoreGenres on the V1.0 API.
Responses
object releaseId integer Unique identifier for the release.
assetId integer Universal asset ID for this release.
tenantId integer ID of the organization that owns this release.
enterpriseId integer ID of the client that owns this release.
name string | null Release title.
phoneticName string | null Phonetic pronunciation of the title, used for voice assistant delivery.
version string | null Release version subtitle (e.g., "Deluxe Edition", "Remastered").
phoneticVersion string | null Phonetic pronunciation of the version subtitle.
languageAndScriptCode string | null Language and script code for the release's phonetic name/version, not the main title.
upc string | null UPC/EAN/JAN code for the release. Unique across the entire system (sandbox accounts are exempt).
isrc string | null ⚠ deprecated
Deprecated. Legacy ISRC field present on some ingested releases. Do not use for new releases.
catalog string | null Internal catalog reference number assigned to the release.
description string | null Optional release description. This will only be sent to platforms that support descriptions, such as Beatport.
featureFmSmartLink string | null Feature.fm smart link URL for the release.
featureFmSmartLinkId string | null Feature.fm smart link ID.
hasRecordLabel boolean Whether the release is associated with a record label. When
false, delivered as "Independent". labelId integer | null ID of the assigned label. Present only when
hasRecordLabel is true. artistId integer | null ID of the primary artist. Returns
null for compilations with no designated primary artist. posterImageId string | null File ID of the release cover artwork.
isCompilation boolean Whether the release is flagged as a compilation for Spotify delivery. See the Compilations section above.
metadataLanguageId integer | null Language of the release metadata—the language of the title and other text fields.
parentalAdvisory boolean | null Whether this release contains explicit content. Ensure this is accurately identified — misidentifying explicit content can result in your distribution being disabled. Set to
true when the release contains strong language, sexual content, references to violence or abuse, or anything unsuitable for children. previouslyReleased boolean Whether the release was commercially available before being added to Revelator. Affects which structural fields are locked.
releaseDate string (date-time) | null Official release date. Set for previously-released content or populated automatically after first distribution.
releaseType WellKnownReleaseTypes Release type.
Examples:
album, single, ep, compilation, videoAlbum, singleVideo, mixedAlbum primaryMusicStyleId integer | null Primary genre/music style ID.
secondaryMusicStyleId integer | null Secondary genre/music style ID.
copyrightC string | null Composition/artwork copyright (©). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
copyrightP string | null Sound recording copyright (℗). Format: year followed by the rights holder (e.g., "2024 Acme Inc.").
assets ReleaseAssetItemModel[] Tracks and videos assigned to this release. The array order determines track numbering on DSPs.
assetId * integer Universal asset ID of the track or video.
assetType * AssetTypes Asset type.
Examples:
track, video discNumber integer | null Disc number for multi-disc releases.
null for single-disc releases. contributors ContributorItemModel[] Release-level contributors. Track-level contributors are attached to individual track assets and can be retrieved via the List Release Assets endpoint.
artistId * integer Artist ID of the contributor.
roleId * integer Contributor role ID. Look up available roles using the lookup endpoints.
locals ReleaseLocalItemModel[] Localized title and version strings for additional metadata languages.
languageId * integer Language ID for this localization entry.
name * string Release title in the specified language.
version string | null Version subtitle in the specified language.
phoneticName string | null Phonetic pronunciation of the title in the specified language.
phoneticVersion string | null Phonetic pronunciation of the version in the specified language.
languageAndScriptCode string | null Language and script code for this entry's phonetic name/version, not the localized title.
distributorStoreGenreIds integer[] DSP-specific genre IDs configured for the release. Currently used for Beatport genre assignments.
isIngested boolean Whether this release was imported via ingestion rather than created manually. Ingested releases are partially locked.
creationDate string (date-time) UTC timestamp when the release was created.
createdBy string ID of the user who created the release.
createdByEmail string | null Email address of the user who created the release.
lastUpdateDate string (date-time) | null UTC timestamp of the most recent update.
lastUpdatedBy string | null ID of the user who last updated the release.
archivedAt string (date-time) | null UTC timestamp when the release was archived.
null if the release is active. archivedBy string | null ID of the user who archived the release.
null if the release is active. lockLevel AssetLockLevels Edit permission level for this release. See the Lock Levels section above for details.
Examples:
unlocked, partiallyLocked, fullyLocked inspectionStatus AssetInspectionStatuses Current inspection/review status. See the Lock Levels section above for how this affects editing permissions.
Examples:
tenantInspection, dealOwnerInspection, rejectedByTenant, rejectedByDealOwner, parkedByTenant, parkedByDealOwner, approved hasIssues boolean Whether the release has validation issues that would prevent successful distribution.
notesCount integer Number of internal notes attached to this release.
hasDistribution boolean Whether the release is currently distributed to at least one store.
isProcessing boolean Whether the release is actively being processed by the distribution pipeline.
firstDeliveryDate string (date-time) | null UTC timestamp of the first successful delivery to a DSP. Once set, the release becomes partially locked.
PUT
/catalog/v1/releases/{releaseId} curl -X PUT "https://platform.revelator.com/catalog/v1/releases/8801" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Midnight Tides",
"version": "Deluxe Edition",
"upc": "843563172001",
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days. Remastered for the 2024 reissue.",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": []
}'curl -X PUT "https://platform.revelator.com/catalog/v1/releases/8801" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Midnight Tides",
"version": "Deluxe Edition",
"upc": "843563172001",
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days. Remastered for the 2024 reissue.",
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": []
}' Example response 200
{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days. Remastered for the 2024 reissue.",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"createdByEmail": "[email protected]",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}{
"releaseId": 8801,
"assetId": 5001100,
"tenantId": 2001,
"enterpriseId": 3001,
"name": "Midnight Tides",
"phoneticName": null,
"version": "Deluxe Edition",
"phoneticVersion": null,
"languageAndScriptCode": null,
"upc": "843563172001",
"isrc": null,
"catalog": "NR-2024-014",
"description": "Debut album by Nova Days. Remastered for the 2024 reissue.",
"featureFmSmartLink": null,
"featureFmSmartLinkId": null,
"hasRecordLabel": true,
"labelId": 120,
"artistId": 4402,
"posterImageId": "f9af4e20-03b6-4f49-b7a8-a8d20ca8ddc2",
"isCompilation": false,
"metadataLanguageId": 1,
"parentalAdvisory": false,
"previouslyReleased": false,
"releaseDate": null,
"releaseType": "album",
"primaryMusicStyleId": 17,
"secondaryMusicStyleId": null,
"copyrightC": "2024 Northline Records",
"copyrightP": "2024 Northline Records",
"assets": [
{ "assetId": 4419835, "assetType": "track", "discNumber": 1 },
{ "assetId": 4419836, "assetType": "track", "discNumber": 1 }
],
"contributors": [],
"locals": [],
"distributorStoreGenreIds": [],
"isIngested": false,
"creationDate": "2024-05-01T10:00:00Z",
"createdBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"createdByEmail": "[email protected]",
"lastUpdateDate": "2024-05-15T08:30:00Z",
"lastUpdatedBy": "b3f1a2c4-1111-4e5f-a678-426614174000",
"archivedAt": null,
"archivedBy": null,
"lockLevel": "unlocked",
"inspectionStatus": null,
"hasIssues": false,
"notesCount": 0,
"hasDistribution": false,
"isProcessing": false,
"firstDeliveryDate": null
}Archive Releases
POST
/catalog/v1/releases/archive Archives releases in batch by their universal asset IDs.
Request Body *
object assetIds * integer[] List of release asset IDs to archive.
Responses
object results ArchiveResult[] One result entry per asset ID in the request.
id integer The release asset ID from the request.
succeeded boolean Whether the archive operation succeeded for this release.
errors ArchiveResultError[] | null List of errors if the operation failed.
null when succeeded is true. code string Machine-readable error code.
message string Human-readable error message.
POST
/catalog/v1/releases/archive curl -X POST "https://platform.revelator.com/catalog/v1/releases/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [5001100, 5001101]
}'curl -X POST "https://platform.revelator.com/catalog/v1/releases/archive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [5001100, 5001101]
}' Example response 200
{
"results": [
{
"id": 5001100,
"succeeded": true,
"errors": null
},
{
"id": 5001101,
"succeeded": true,
"errors": null
}
]
}{
"results": [
{
"id": 5001100,
"succeeded": true,
"errors": null
},
{
"id": 5001101,
"succeeded": true,
"errors": null
}
]
}Unarchive Releases
POST
/catalog/v1/releases/unarchive Unarchives releases in batch by their universal asset IDs.
Request Body *
object assetIds * integer[] List of release asset IDs to unarchive.
Responses
object results UnarchiveResult[] One result entry per asset ID in the request.
id integer The release asset ID from the request.
succeeded boolean Whether the unarchive operation succeeded for this release.
errors UnarchiveResultError[] | null List of errors if the operation failed.
null when succeeded is true. code string Machine-readable error code.
message string Human-readable error message.
POST
/catalog/v1/releases/unarchive curl -X POST "https://platform.revelator.com/catalog/v1/releases/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [5001100, 5001101]
}'curl -X POST "https://platform.revelator.com/catalog/v1/releases/unarchive" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetIds": [5001100, 5001101]
}' Example response 200
{
"results": [
{
"id": 5001100,
"succeeded": true,
"errors": null
},
{
"id": 5001101,
"succeeded": true,
"errors": null
}
]
}{
"results": [
{
"id": 5001100,
"succeeded": true,
"errors": null
},
{
"id": 5001101,
"succeeded": true,
"errors": null
}
]
}